extending.po

# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
# Leon H., 2017
# Adrian Liaw <adrianliaw2000@gmail.com>, 2018
# Matt Wang <mattwang44@gmail.com>, 2025
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-08-17 00:09+0000\n"
"PO-Revision-Date: 2025-02-17 14:34+0000\n"
"Last-Translator: Matt Wang <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"

#: ../../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 <https://cffi.readthedocs.io/>`_ 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 "
"<https://cffi.readthedocs.io/>`_ 函式庫，而不是編寫自訂的 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:704
msgid ""
"#define PY_SSIZE_T_CLEAN\n"
"#include <Python.h>"
msgstr ""
"#define PY_SSIZE_T_CLEAN\n"
"#include <Python.h>"

#: ../../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 ""
"所有由 :file:`Python.h` 定義的使用者可見符號都具有 ``Py`` 或 ``PY`` 的前綴，"
"在標準標頭檔中定義的除外。"

#: ../../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 ""
"為了向後相容，:file:`Python.h` 引入了數個標準標頭檔。C 擴充應該引入它們使用的"
"標準標頭檔，而不應依賴這些隱式的引入。如果使用限定 C API 版本 3.13 或更新版"
"本，隱式引入的有："

#: ../../extending/extending.rst:87
msgid "``<assert.h>``"
msgstr "``<assert.h>``"

#: ../../extending/extending.rst:88
msgid "``<intrin.h>`` (on Windows)"
msgstr "``<intrin.h>``\\ （在 Windows 上）"

#: ../../extending/extending.rst:89
msgid "``<inttypes.h>``"
msgstr "``<inttypes.h>``"

#: ../../extending/extending.rst:90
msgid "``<limits.h>``"
msgstr "``<limits.h>``"

#: ../../extending/extending.rst:91
msgid "``<math.h>``"
msgstr "``<math.h>``"

#: ../../extending/extending.rst:92
msgid "``<stdarg.h>``"
msgstr "``<stdarg.h>``"

#: ../../extending/extending.rst:93
msgid "``<wchar.h>``"
msgstr "``<wchar.h>``"

#: ../../extending/extending.rst:94
msgid "``<sys/types.h>`` (if present)"
msgstr "``<sys/types.h>``\\ （如果存在）"

#: ../../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 ""
"如果 :c:macro:`Py_LIMITED_API` 未被定義，或是被設定為版本 3.12 或更舊，則也會"
"引入以下標頭檔："

#: ../../extending/extending.rst:99
msgid "``<ctype.h>``"
msgstr "``<ctype.h>``"

#: ../../extending/extending.rst:100
msgid "``<unistd.h>`` (on POSIX)"
msgstr "``<unistd.h>``\\ （在 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 ""
"如果 :c:macro:`Py_LIMITED_API` 未被定義，或是被設定為版本 3.10 或更舊，則也會"
"引入以下標頭檔："

#: ../../extending/extending.rst:105
msgid "``<errno.h>``"
msgstr "``<errno.h>``"

#: ../../extending/extending.rst:106
msgid "``<stdio.h>``"
msgstr "``<stdio.h>``"

#: ../../extending/extending.rst:107
msgid "``<stdlib.h>``"
msgstr "``<stdlib.h>``"

#: ../../extending/extending.rst:108
msgid "``<string.h>``"
msgstr "``<string.h>``"

#: ../../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 ""
"並透過在模組的 :c:data:`Py_mod_exec` 函式（:c:func:`!spam_module_exec`）中呼"
"叫 :c:func:`PyErr_NewException` 來初始化它： ::"

#: ../../extending/extending.rst:240
msgid "SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);"
msgstr "SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);"

#: ../../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 ""
"由於 :c:data:`!SpamError` 是一個全域變數，每次模組被重新初始化、即 :c:data:"
"`Py_mod_exec` 函式被呼叫時，它都會被覆寫。"

#: ../../extending/extending.rst:245
msgid ""
"For now, let's avoid the issue: we will block repeated initialization by "
"raising an :py:exc:`ImportError`::"
msgstr ""
"目前，讓我們先避免這個問題：我們會透過引發 :py:exc:`ImportError` 來阻止重複初"
"始化： ::"

#: ../../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 ""
"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,  // 非負數\n"
"    .m_slots = spam_module_slots,\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    return PyModuleDef_Init(&spam_module);\n"
"}"

#: ../../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 ""
"目前，用來移除此參照的 :c:func:`Py_DECREF` 呼叫是缺失的。即使 Python 直譯器關"
"閉時，全域的 :c:data:`!SpamError` 變數也不會被垃圾回收。它會「洩漏」。然而，"
"我們確實有確保這每個行程最多只會發生一次。"

#: ../../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 ""
"static struct PyModuleDef spam_module = {\n"
"    ...\n"
"    .m_methods = spam_methods,\n"
"    ...\n"
"};"

#: ../../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 ""
"當每個直譯器首次 import 其 :mod:`!spam` 模組時，就會呼叫 :c:func:`!"
"PyInit_spam`。（關於嵌入 Python 的說明請見下方。）必須透過 :c:func:"
"`PyModuleDef_Init` 回傳一個指向模組定義的指標，好讓 import 機制可以建立模組並"
"將其儲存在 ``sys.modules`` 中。"

#: ../../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 <Python.h>\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 <Python.h>\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"