diff --git a/c-api/arg.po b/c-api/arg.po index d00a73959f..ee0b42c42f 100644 --- a/c-api/arg.po +++ b/c-api/arg.po @@ -21,7 +21,7 @@ msgstr "" #: ../../c-api/arg.rst:6 msgid "Parsing arguments and building values" -msgstr "" +msgstr "剖析引數與建置數值" #: ../../c-api/arg.rst:8 msgid "" diff --git a/c-api/intro.po b/c-api/intro.po index b6ae3f073a..9e140983c3 100644 --- a/c-api/intro.po +++ b/c-api/intro.po @@ -3,13 +3,14 @@ # This file is distributed under the same license as the Python package. # # Translators: +# Matt Wang , 2023 msgid "" msgstr "" "Project-Id-Version: Python 3.11\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2023-03-16 00:18+0000\n" -"PO-Revision-Date: 2018-05-23 14:06+0000\n" -"Last-Translator: Adrian Liaw \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" @@ -17,6 +18,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Poedit 3.2.2\n" #: ../../c-api/intro.rst:8 msgid "Introduction" @@ -34,6 +36,12 @@ msgid "" "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 "" @@ -43,6 +51,9 @@ msgid "" "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 "" @@ -52,10 +63,13 @@ msgid "" "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 "Coding standards" -msgstr "" +msgstr "編寫標準" #: ../../c-api/intro.rst:36 msgid "" @@ -65,16 +79,21 @@ msgid "" "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:46 msgid "Include Files" -msgstr "" +msgstr "引入檔案 (include files)" #: ../../c-api/intro.rst:48 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:54 msgid "" @@ -82,6 +101,8 @@ msgid "" "````, ````, ````, ```` and ```` (if available)." msgstr "" +"這意味著會引入以下標準標頭：````、````、````、" +"````、```` 和 ````\\ （如果可用）。" #: ../../c-api/intro.rst:60 msgid "" @@ -89,12 +110,16 @@ msgid "" "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:64 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:67 msgid "" @@ -104,6 +129,9 @@ msgid "" "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:74 msgid "" @@ -112,6 +140,9 @@ msgid "" "future Python versions, which may define additional names beginning with one " "of these prefixes." msgstr "" +"使用者程式碼不應定義任何以 ``Py`` 或 ``_Py`` 開頭的名稱。這會讓讀者感到困惑，" +"並危及使用者程式碼在未來 Python 版本上的可移植性，這些版本可能會定義以這些前" +"綴之一開頭的其他名稱。" #: ../../c-api/intro.rst:79 msgid "" @@ -124,6 +155,12 @@ msgid "" "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:88 msgid "" @@ -134,6 +171,10 @@ msgid "" "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:95 msgid "" @@ -141,10 +182,12 @@ msgid "" "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:101 msgid "Useful macros" -msgstr "" +msgstr "有用的巨集" #: ../../c-api/intro.rst:103 msgid "" @@ -153,6 +196,8 @@ msgid "" "Others of a more general utility are defined here. This is not necessarily " "a complete listing." msgstr "" +"Python 標頭檔中定義了幾個有用的巨集，大多被定義在它們有用的地方附近（例如 :c:" +"macro:`Py_RETURN_NONE`），其他是更通用的工具程式。以下並不一定是完整的列表。" #: ../../c-api/intro.rst:110 msgid "Return the absolute value of ``x``." @@ -163,6 +208,8 @@ msgid "" "Ask the compiler to always inline a static inline function. The compiler can " "ignore it and decides to not inline the function." msgstr "" +"要求編譯器總是嵌入靜態行內函式 (static inline function)，編譯器可以忽略它並決" +"定不嵌入該函式。" #: ../../c-api/intro.rst:119 msgid "" @@ -170,6 +217,8 @@ msgid "" "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:123 msgid "" @@ -177,28 +226,37 @@ msgid "" "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:127 msgid "" "If Python is :ref:`built in debug mode ` (if the ``Py_DEBUG`` " "macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing." msgstr "" +"如果 Python 是\\ :ref:`在除錯模式下建置 `\\ （如果 ``Py_DEBUG`` " +"巨集有被定義），:c:macro:`Py_ALWAYS_INLINE` 巨集就什麼都不會做。" #: ../../c-api/intro.rst:130 msgid "It must be specified before the function return type. Usage::" msgstr "" +"它必須在函式回傳型別之前被指定。用法：\n" +"\n" +"::" #: ../../c-api/intro.rst:138 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:143 msgid "" "Use this for deprecated declarations. The macro must be placed before the " "symbol name." -msgstr "" +msgstr "將其用於已棄用的聲明。巨集必須放在符號名稱之前。" #: ../../c-api/intro.rst:146 ../../c-api/intro.rst:232 #: ../../c-api/intro.rst:250 @@ -210,25 +268,27 @@ msgstr "" #: ../../c-api/intro.rst:150 msgid "MSVC support was added." -msgstr "" +msgstr "新增了 MSVC 支援。" #: ../../c-api/intro.rst:155 msgid "" "Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the " "command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set)." msgstr "" +"類似於 ``getenv(s)``，但如果在命令列上傳遞了 :option:`-E`\\ （即如果設定了 " +"``Py_IgnoreEnvironmentFlag``\\ ）則回傳 ``NULL``。" #: ../../c-api/intro.rst:160 msgid "Return the maximum value between ``x`` and ``y``." -msgstr "" +msgstr "回傳 ``x`` 和 ``y`` 之間的最大值。" #: ../../c-api/intro.rst:166 msgid "Return the size of a structure (``type``) ``member`` in bytes." -msgstr "" +msgstr "以位元組為單位回傳結構 (``type``) ``member`` 的大小。" #: ../../c-api/intro.rst:172 msgid "Return the minimum value between ``x`` and ``y``." -msgstr "" +msgstr "回傳 ``x`` 和 ``y`` 之間的最小值。" #: ../../c-api/intro.rst:178 msgid "" @@ -236,15 +296,21 @@ msgid "" "consumption: useful on LTO+PGO builds which heavily inline code (see :issue:" "`33720`)." msgstr "" +"禁用函式的嵌入。例如，它減少了 C 堆疊的消耗：對大量嵌入程式碼的 LTO+PGO 建置" +"很有用（請參閱 :issue:`33720`）。" #: ../../c-api/intro.rst:182 msgid "Usage::" msgstr "" +"用法：\n" +"\n" +"::" #: ../../c-api/intro.rst:190 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:197 msgid "" @@ -253,6 +319,9 @@ msgid "" "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:202 msgid "" @@ -260,12 +329,17 @@ msgid "" "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:206 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:209 msgid "" @@ -275,40 +349,51 @@ msgid "" "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:219 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:226 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:229 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:244 msgid "" "Creates a docstring for the given input string or an empty string if " "docstrings are disabled." -msgstr "" +msgstr "為給定的輸入字串建立一個文件字串，如果文件字串被禁用則建立空字串。" #: ../../c-api/intro.rst:247 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:262 msgid "Objects, Types and Reference Counts" -msgstr "" +msgstr "物件、型別和參照計數" #: ../../c-api/intro.rst:266 msgid "" @@ -324,6 +409,14 @@ msgid "" "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:277 msgid "" @@ -335,10 +428,15 @@ msgid "" "``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:288 msgid "Reference Counts" -msgstr "" +msgstr "參照計數" #: ../../c-api/intro.rst:290 msgid "" @@ -353,6 +451,13 @@ msgid "" "(There's an obvious problem with objects that reference each other here; " "for now, the solution is \"don't do that.\")" msgstr "" +"參照計數很重要，因為現今的電腦記憶體大小是有限的（而且通常是非常有限的）；它" +"計算有多少個不同的地方參照了一個物件。這樣的地方可以是另一個物件，或者全域" +"（或靜態）C 變數，或者某個 C 函式中的本地變數。當一個物件的參照計數變為零時，" +"該物件將被釋放 (deallocated)。如果它包含對其他物件的參照，則它們的參照計數會" +"減少。如果這樣的減少使它們的參照計數變為零，則可以依次釋放那些其他物件，依此" +"類推。 （此處相互參照物件的存在是個明顯的問題；目前，解決方案是「就不要那樣" +"做」。）" #: ../../c-api/intro.rst:305 msgid "" @@ -371,6 +476,14 @@ msgid "" "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:319 msgid "" @@ -388,6 +501,13 @@ msgid "" "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 "" +"沒有必要為每個包含物件指標的本地變數增加物件的參照計數。理論上，當變數指向它" +"時，物件的參照計數會增加 1，而當變數離開作用域時就會減少 1。然而這兩者會相互" +"抵消，所以最後參照計數沒有改變。使用參照計數的唯一真正原因是防止物件還有變數" +"指向它時被釋放。如果我們知道至少有一個物件的其他參照生存了至少與我們的變數一" +"樣久，就不需要臨時增加參照計數。出現這種情況的一個重要情況是在從 Python 呼叫" +"的擴充模組中作為引數傳遞給 C 函式的物件；呼叫機制保證在呼叫期間保持對每個參數" +"的參照。" #: ../../c-api/intro.rst:333 msgid "" @@ -399,6 +519,11 @@ msgid "" "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:341 msgid "" @@ -409,10 +534,14 @@ msgid "" "call :c:func:`Py_DECREF` when they are done with the result; this soon " "becomes second nature." msgstr "" +"一種安全的方法是都使用通用 (generics) 操作（名稱以 ``PyObject_``、" +"``PyNumber_``、``PySequence_`` 或 ``PyMapping_`` 開頭的函式）。這些操作總是增" +"加它們回傳的物件的參照計數。這讓呼叫者有責任在處理完結果後呼叫 :c:func:" +"`Py_DECREF`；這就成為第二本質。" #: ../../c-api/intro.rst:351 msgid "Reference Count Details" -msgstr "" +msgstr "參照計數詳細資訊" #: ../../c-api/intro.rst:353 msgid "" @@ -430,6 +559,14 @@ msgid "" "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:366 msgid "" @@ -439,6 +576,9 @@ msgid "" "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:376 msgid "" @@ -451,6 +591,11 @@ msgid "" "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:391 msgid "" @@ -459,6 +604,9 @@ msgid "" "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:396 msgid "" @@ -467,12 +615,18 @@ msgid "" "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:401 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:404 msgid "" @@ -482,6 +636,12 @@ msgid "" "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` 引導。例如上面的兩個程式碼可以用以下程式碼替換（它還負責了錯誤檢" +"查）：\n" +"\n" +"::" #: ../../c-api/intro.rst:415 msgid "" @@ -493,6 +653,10 @@ msgid "" "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:445 msgid "" @@ -506,6 +670,11 @@ msgid "" "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:454 msgid "" @@ -517,6 +686,11 @@ msgid "" "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:466 msgid "" @@ -524,10 +698,14 @@ msgid "" "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`：\n" +"\n" +"::" #: ../../c-api/intro.rst:530 msgid "Types" -msgstr "" +msgstr "型別" #: ../../c-api/intro.rst:532 msgid "" @@ -539,6 +717,10 @@ msgid "" "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:542 msgid "" @@ -547,6 +729,9 @@ msgid "" "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:551 msgid "Exceptions" @@ -560,6 +745,9 @@ msgid "" "level interpreter, where they are reported to the user accompanied by a " "stack traceback." msgstr "" +"如果需要特定的錯誤處理，Python 開發者就只需要處理例外；未處理的例外會自動傳遞" +"給呼叫者，然後傳遞給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡" +"它們透過堆疊回溯 (stack trace) 回報給使用者。" #: ../../c-api/intro.rst:561 msgid "" @@ -575,6 +763,13 @@ msgid "" "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:576 msgid "" @@ -588,6 +783,12 @@ msgid "" "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:586 msgid "" @@ -601,6 +802,12 @@ msgid "" "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:598 msgid "" @@ -615,6 +822,12 @@ msgid "" "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:609 msgid "" @@ -626,6 +839,10 @@ msgid "" "that was just raised, and lose important information about the exact cause " "of the error." msgstr "" +"作為一般原則，呼叫另一個函式來執行某些任務的函式應該檢查被呼叫函式是否引發了" +"例外，如果是，則將例外狀態傳遞給它的呼叫者。它應該丟棄它擁有的任何物件參照，" +"並回傳一個錯誤指示符，但它\\ *不應該*\\ 設定另一個例外 --- 這將覆蓋剛剛引發的" +"例外，並丟失關於錯誤確切原因的重要資訊。" #: ../../c-api/intro.rst:618 msgid "" @@ -635,10 +852,15 @@ msgid "" "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 程式碼：\n" +"\n" +"::" #: ../../c-api/intro.rst:633 msgid "Here is the corresponding C code, in all its glory::" -msgstr "" +msgstr "這是相應的 C 程式碼：" #: ../../c-api/intro.rst:685 msgid "" @@ -652,6 +874,12 @@ msgid "" "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:699 msgid "Embedding Python" @@ -664,6 +892,8 @@ msgid "" "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:714 msgid "" @@ -672,6 +902,9 @@ msgid "" "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:719 msgid "" @@ -680,6 +913,10 @@ msgid "" "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:724 msgid "" @@ -692,6 +929,12 @@ msgid "" "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:733 msgid "" @@ -703,6 +946,12 @@ msgid "" "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:748 msgid "" @@ -714,6 +963,12 @@ msgid "" "`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_Initialize` *之前*\\ 呼叫 " +"``Py_SetProgramName(file)`` 來引導搜索。請注意 :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:758 msgid "" @@ -728,10 +983,17 @@ msgid "" "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:772 msgid "Debugging Builds" -msgstr "" +msgstr "除錯建置" #: ../../c-api/intro.rst:774 msgid "" @@ -739,6 +1001,8 @@ msgid "" "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 可以在建置時使用多個巨集來啟用對直譯器和擴充模組的額外檢查，這些檢查往" +"往會在運行時增加大量開銷 (overhead)，因此預設情況下不啟用它們。" #: ../../c-api/intro.rst:778 msgid "" @@ -749,6 +1013,9 @@ msgid "" "most frequently used builds will be described in the remainder of this " "section." msgstr "" +"Python 原始碼發佈版本中的 :file:`Misc/SpecialBuilds.txt` 檔案有一份包含多種除" +"錯構置的完整列表，為支援追蹤參照計數、為記憶體分配器除錯或對主直譯器迴圈進行" +"低階分析的建置。本節的其餘部分將僅描述最常用的建置。" #: ../../c-api/intro.rst:784 msgid "" @@ -760,12 +1027,19 @@ msgid "" "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:792 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:795 msgid "" @@ -776,9 +1050,16 @@ msgid "" "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:802 msgid "" "Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source " "distribution for more detailed information." msgstr "" +"有關更多詳細資訊，請參閱 Python 原始碼發布版中的 :file:`Misc/SpecialBuilds." +"txt`。" diff --git a/reference/datamodel.po b/reference/datamodel.po index ca384d90a6..7a3d90b96a 100644 --- a/reference/datamodel.po +++ b/reference/datamodel.po @@ -138,7 +138,7 @@ msgstr "" #: ../../reference/datamodel.rst:120 msgid "The standard type hierarchy" -msgstr "" +msgstr "標準型別階層" #: ../../reference/datamodel.rst:129 msgid ""