# 簡介

對於 Python 的應用程式開發介面使得 C 和 C++ 開發者能夠在各種層級存取 Python 直譯器。該 API 同樣可用於 C++，但為簡潔起見，通常將其稱為 Python/C API。使用 Python/C API 有兩個不同的原因，第一個是為特定目的來編寫擴充模組；這些是擴充 Python 直譯器的 C 模組，這可能是最常見的用法。第二個原因是在更大的應用程式中將 Python 作為零件使用；這種技術通常在應用程式中稱為 embedding（嵌入式）Python。

編寫擴充模組是一個相對容易理解的過程，其中「食譜 (cookbook)」方法很有效。有幾種工具可以在一定程度上自動化該過程，儘管人們從早期就將 Python 嵌入到其他應用程式中，但嵌入 Python 的過程並不像編寫擴充那樣簡單。

不論你是嵌入還是擴充 Python，許多 API 函式都是很有用的；此外，大多數嵌入 Python 的應用程式也需要提供自訂擴充模組，因此在嘗試將 Python 嵌入實際應用程式之前熟悉編寫擴充可能是個好主意。

## 語言版本相容性

Python 的 C API 與 C11 和 C++11 版本的 C 和 C++ 相容。

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".

## 編寫標準

如果你正在編寫要引入於 CPython 中的 C 程式碼，你必須遵循 PEP 7 中定義的指南和標準。無論你貢獻的 Python 版本如何，這些指南都適用。對於你自己的第三方擴充模組，則不必遵循這些約定，除非你希望最終將它們貢獻給 Python。

## 引入檔案 (include files)

使用 Python/C API 所需的所有函式、型別和巨集的定義都透過以下這幾行來在你的程式碼中引入：

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

這意味著會引入以下標準標頭：`<stdio.h>`、`<string.h>`、`<errno.h>`、`<limits.h>`、`<assert.h>` 和 `<stdlib.h>`（如果可用）。

備註

由於 Python 可能會定義一些會影響某些系統上標準標頭檔的預處理器 (pre-processor)，因此你必須在引入任何標準標頭檔之前引入 `Python.h`。

建議在引入 `Python.h` 之前都要定義 `PY_SSIZE_T_CLEAN`。有關此巨集的說明，請參閱剖析引數與建置數值。

所有定義於 Python.h 中且使用者可見的名稱（另外透過標準標頭檔引入的除外）都具有 `Py` 或 `_Py` 前綴。以 `_Py` 開頭的名稱供 Python 實作內部使用，擴充編寫者不應使用。結構成員名稱沒有保留前綴。

備註

使用者程式碼不應定義任何以 `Py` 或 `_Py` 開頭的名稱。這會讓讀者感到困惑，並危及使用者程式碼在未來 Python 版本上的可移植性，這些版本可能會定義以這些前綴之一開頭的其他名稱。

標頭檔通常隨 Python 一起安裝。在 Unix 上它們位於目錄 `prefix/include/pythonversion/` 和 `exec_prefix/include/pythonversion/`，其中 `prefix` 和 `exec_prefix` 由 Python 的 configure 腳本的相應參數定義，version 是 `'%d.%d' % sys.version_info[:2]`。在 Windows 上，標頭安裝在 `prefix/include` 中，其中 `prefix` 是指定給安裝程式 (installer) 用的安裝目錄。

要引入標頭，請將兩個（如果不同）目錄放在編譯器的引入搜尋路徑 (search path) 中。不要將父目錄放在搜尋路徑上，然後使用 `#include <pythonX.Y/Python.h>`；這會在多平台建置上壞掉，因為 `prefix` 下獨立於平台的標頭包括來自 `exec_prefix` 的平台特定標頭。

C++ 使用者應注意，儘管 API 完全使用 C 來定義，但標頭檔適當地將入口點聲明為 `extern "C"`。因此，無需執行任何特殊操作即可使用 C++ 中的 API。

### System includes

> `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. The implicit includes are:

> - `<assert.h>`

> - `<intrin.h>` (on Windows)

> - `<inttypes.h>`

> - `<limits.h>`

> - `<math.h>`

> - `<stdarg.h>`

> - `<string.h>`

> - `<wchar.h>`

> - `<sys/types.h>` (if present)

> The following are included for backwards compatibility, unless using Limited API 3.13 or newer:

> - `<ctype.h>`

> - `<unistd.h>` (on POSIX)

> The following are included for backwards compatibility, unless using Limited API 3.11 or newer:

> - `<errno.h>`

> - `<stdio.h>`

> - `<stdlib.h>`

備註

由於 Python 可能會定義一些會影響某些系統上標準標頭檔的預處理器 (pre-processor)，因此你必須在引入任何標準標頭檔之前引入 `Python.h`。

## 有用的巨集

Python 標頭檔中定義了幾個有用的巨集，大多被定義在它們有用的地方附近（例如 `Py_RETURN_NONE`、`PyMODINIT_FUNC`），其他是更通用的工具程式。以下並不一定是完整的列表。

Py_CAN_START_THREADS

  如果有定義此巨集，則目前系統就能夠啟動執行緒。

  Currently, all systems supported by CPython (per PEP 11), with the exception of some WebAssembly platforms, support starting threads.

  在 3.13 版被加入.

Py_GETENV(s)

  類似於 `getenv(s)`，但如果在命令列上傳遞了 `-E` 則回傳 `NULL` （請見 `PyConfig.use_environment`）。

### 文件字串巨集

PyDoc_STRVAR(name, str)

  建立一個名為 name 的變數，可以在文件字串中使用。如果 Python 是在沒有文件字串的情況下建置 (`--without-doc-strings`)，則該值將為空字串。

  範例：

      PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

      static PyMethodDef deque_methods[] = {
          // ...
          {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
          // ...
      }

  Expands to `PyDoc_VAR(name) = PyDoc_STR(str)`.

PyDoc_STR(str)

  擴展至給定的輸入字串，或如果文件字串被禁用 (`--without-doc-strings`) 則建立空字串。

  範例：

      static PyMethodDef pysqlite_row_methods[] = {
          {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
              PyDoc_STR("Returns the keys of the row.")},
          {NULL, NULL}
      };

PyDoc_VAR(name)

  Declares a static character array variable with the given name. Expands to `static const char name[]`

  範例：

      PyDoc_VAR(python_doc) = PyDoc_STR(
         "A genus of constricting snakes in the Pythonidae family native "
         "to the tropics and subtropics of the Eastern Hemisphere.");

### General utility macros

The following macros are for common tasks not specific to Python.

Py_UNUSED(arg)

  將此用於函式定義中未使用的參數以消除編譯器警告。例如：`int func(int a, int Py_UNUSED(b)) { return a; }`。

  在 3.4 版被加入.

Py_GCC_ATTRIBUTE(name)

  Use a GCC attribute name, hiding it from compilers that don't support GCC attributes (such as MSVC).

  This expands to `__attribute__((name))` on a GCC compiler, and expands to nothing on compilers that don't support GCC attributes.

#### Numeric utilities

Py_ABS(x)

  回傳 `x` 的絕對值。

  The argument may be evaluated more than once. Consequently, do not pass an expression with side-effects directly to this macro.

  If the result cannot be represented (for example, if `x` has `INT_MIN` value for int type), the behavior is undefined.

  Corresponds roughly to `((x) < 0 ? -(x) : (x))`

  在 3.3 版被加入.

Py_MAX(x, y)
Py_MIN(x, y)

  Return the larger or smaller of the arguments, respectively.

  Any arguments may be evaluated more than once. Consequently, do not pass an expression with side-effects directly to this macro.

  `Py_MAX` corresponds roughly to `(((x) > (y)) ? (x) : (y))`.

  在 3.3 版被加入.

Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)

  Similar to `integer >> positions`, but forces sign extension, as the C standard does not define whether a right-shift of a signed integer will perform sign extension or a zero-fill.

  integer should be any signed integer type. positions is the number of positions to shift to the right.

  Both integer and positions can be evaluated more than once; consequently, avoid directly passing a function call or some other operation with side-effects to this macro. Instead, store the result as a variable and then pass it.

  type is unused and only kept for backwards compatibility. Historically, type was used to cast integer.

  在 3.1 版的變更: This macro is now valid for all signed integer types, not just those for which `unsigned type` is legal. As a result, type is no longer used.

Py_CHARMASK(c)

  引數必須是 [-128, 127] 或 [0, 255] 範圍內的字元或整數。這個巨集會將 `c` 轉換為 `unsigned char` 並回傳。

#### Assertion utilities

Py_UNREACHABLE()

  當你的設計中有無法達到的程式碼路徑時，請使用此選項。例如在 `case` 語句已涵蓋了所有可能值的 `switch` 陳述式中的 `default:` 子句。在你可能想要呼叫 `assert(0)` 或 `abort()` 的地方使用它。

  在發布模式 (release mode) 下，巨集幫助編譯器最佳化程式碼，並避免有關無法存取程式碼的警告。例如該巨集是在發布模式下於 GCC 使用 `__builtin_unreachable()` 來實作。

  In debug mode, and on unsupported compilers, the macro expands to a call to `Py_FatalError()`.

  `Py_UNREACHABLE()` 的一個用途是，在對一個永不回傳但並未聲明為 `_Noreturn` 的函式之呼叫後使用。

  如果程式碼路徑是極不可能但在特殊情況下可以到達，則不得使用此巨集。例如在低記憶體條件下或系統呼叫回傳了超出預期範圍的值。在這種情況下，最好將錯誤回報給呼叫者。如果無法回報錯誤則可以使用 `Py_FatalError()`。

  在 3.7 版被加入.

Py_SAFE_DOWNCAST(value, larger, smaller)

  Cast value to type smaller from type larger, validating that no information was lost.

  On release builds of Python, this is roughly equivalent to `((smaller) value)` (in C++, `static_cast<smaller>(value)` will be used instead).

  On debug builds (implying that `Py_DEBUG` is defined), this asserts that no information was lost with the cast from larger to smaller.

  value, larger, and smaller may all be evaluated more than once in the expression; consequently, do not pass an expression with side-effects directly to this macro.

Py_BUILD_ASSERT(cond)

  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.

  Corresponds roughly to `static_assert(cond)` on C23 and above.

  範例：

      Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));

  在 3.3 版被加入.

Py_BUILD_ASSERT_EXPR(cond)

  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.

  範例：

      #define foo_to_char(foo) \
          ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))

  在 3.3 版被加入.

#### Type size utilities

Py_ARRAY_LENGTH(array)

  Compute the length of a statically allocated C array at compile time.

  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.

  這大致上相當於：

      sizeof(array) / sizeof((array)[0])

Py_MEMBER_SIZE(type, member)

  以位元組為單位回傳結構 (type) member 的大小。

  Corresponds roughly to `sizeof(((type *)NULL)->member)`.

  在 3.6 版被加入.

#### Macro definition utilities

Py_FORCE_EXPANSION(X)

  This is equivalent to `X`, which is useful for token-pasting in macros, as macro expansions in X are forcefully evaluated by the preprocessor.

Py_STRINGIFY(x)

  將 `x` 轉換為 C 字串。例如 `Py_STRINGIFY(123)` 會回傳 `"123"`。

  在 3.4 版被加入.

### Declaration utilities

The following macros can be used in declarations. They are most useful for defining the C API itself, and have limited use for extension authors. Most of them expand to compiler-specific spellings of common extensions to the C language.

Py_ALWAYS_INLINE

  要求編譯器總是嵌入靜態行內函式 (static inline function)，編譯器可以忽略它並決定不嵌入該函式。

  Corresponds to `always_inline` attribute in GCC and `__forceinline` in MSVC.

  在禁用函式嵌入的除錯模式下建置 Python 時，它可用於嵌入有性能要求的靜態行內函式。例如，MSC 在除錯模式下建置時禁用函式嵌入。

  盲目地使用 Py_ALWAYS_INLINE 標記靜態行內函式可能會導致更差的性能（例如程式碼大小增加）。在成本/收益分析方面，編譯器通常比開發人員更聰明。

  如果 Python 是在除錯模式下建置（如果 `Py_DEBUG` 巨集有被定義），`Py_ALWAYS_INLINE` 巨集就什麼都不會做。

  它必須在函式回傳型別之前被指定。用法：

      static inline Py_ALWAYS_INLINE int random(void) { return 4; }

  在 3.11 版被加入.

Py_NO_INLINE

  禁用函式的嵌入。例如，它減少了 C 堆疊的消耗：對大量嵌入程式碼的 LTO+PGO 建置很有用（請參閱 bpo-33720）。

  Corresponds to the `noinline` attribute/specification on GCC and MSVC.

  用法：

      Py_NO_INLINE static int random(void) { return 4; }

  在 3.11 版被加入.

Py_DEPRECATED(version)

  Use this to declare APIs that were deprecated in a specific CPython version. The macro must be placed before the symbol name.

  範例：

      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

  在 3.8 版的變更: 新增了 MSVC 支援。

Py_LOCAL(type)

  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`.

Py_LOCAL_INLINE(type)

  Equivalent to `Py_LOCAL` but additionally requests the function be inlined.

Py_LOCAL_SYMBOL

  Macro used to declare a symbol as local to the shared library (hidden). On supported platforms, it ensures the symbol is not exported.

  On compatible versions of GCC/Clang, it expands to `__attribute__((visibility("hidden")))`.

Py_EXPORTED_SYMBOL

  Macro used to declare a symbol (function or data) as exported. On Windows, this expands to `__declspec(dllexport)`. On compatible versions of GCC/Clang, it expands to `__attribute__((visibility("default")))`. This macro is for defining the C API itself; extension modules should not use it.

Py_IMPORTED_SYMBOL

  Macro used to declare a symbol as imported. On Windows, this expands to `__declspec(dllimport)`. This macro is for defining the C API itself; extension modules should not use it.

PyAPI_FUNC(type)

  Macro used by CPython to declare a function as part of the C API. Its expansion depends on the platform and build configuration. This macro is intended for defining CPython's C API itself; extension modules should not use it for their own symbols.

PyAPI_DATA(type)

  Macro used by CPython to declare a public global variable as part of the C API. Its expansion depends on the platform and build configuration. This macro is intended for defining CPython's C API itself; extension modules should not use it for their own symbols.

### Outdated macros

The following soft deprecated macros have been used to features that have been standardized in C11 (or previous standards).

Py_ALIGNED(num)

  On some GCC-like compilers, specify alignment to num bytes. This does nothing on other compilers.

  Use the standard `alignas` specifier rather than this macro.

  Soft deprecated since version 3.15.

PY_FORMAT_SIZE_T

  The `printf()` formatting modifier for `size_t`. Use `"z"` directly instead.

  Soft deprecated since version 3.15.

Py_LL(number)
Py_ULL(number)

  Use number as a `long long` or `unsigned long long` integer literal, respectively.

  Expands to number followed by `LL` or `LLU`, respectively, but will expand to some compiler-specific suffixes on some older compilers.

  Consider using the C99 standard suffixes `LL` and `LLU` directly.

  Soft deprecated since version 3.15.

PY_LONG_LONG
PY_INT32_T
PY_UINT32_T
PY_INT64_T
PY_UINT64_T

  Aliases for the types `long long`, `int32_t`, `uint32_t`. `int64_t` and `uint64_t`, respectively. Historically, these types needed compiler-specific extensions.

  Soft deprecated since version 3.15.

PY_LLONG_MIN
PY_LLONG_MAX
PY_ULLONG_MAX
PY_SIZE_MAX

  Aliases for the values `LLONG_MIN`, `LLONG_MAX`, `ULLONG_MAX`, and `SIZE_MAX`, respectively. Use these standard names instead.

  The required header, `<limits.h>`, is included in `Python.h`.

  Soft deprecated since version 3.15.

Py_MEMCPY(dest, src, n)

  This is an alias to `memcpy()`.

  Soft deprecated since version 3.14: Use `memcpy()` directly instead.

Py_UNICODE_SIZE

  Size of the `wchar_t` type. Use `sizeof(wchar_t)` or `WCHAR_WIDTH/8` instead.

  The required header for the latter, `<limits.h>`, is included in `Python.h`.

  Soft deprecated since version 3.15.

Py_UNICODE_WIDE

  Defined if `wchar_t` can hold a Unicode character (UCS-4). Use `sizeof(wchar_t) >= 4` instead

  Soft deprecated since version 3.15.

Py_VA_COPY

  This is an alias to the C99-standard `va_copy` function.

  Historically, this would use a compiler-specific method to copy a `va_list`.

  在 3.6 版的變更: 這現在是 `va_copy` 的別名。

  Soft deprecated since version 3.15.

## 物件、型別和參照計數

大多數 Python/C API 函式都有一個或多個引數以及一個型別為 PyObject* 的回傳值，此型別是一個指標，指向一個表示任意 Python 物件的晦暗 (opaque) 資料型別。由於在大多數情況下，Python 語言以相同的方式處理所有 Python 物件型別（例如賦值、作用域規則和引數傳遞），因此它們應該由單個 C 型別來表示。幾乎所有的 Python 物件都存在於堆積 (heap) 中：你永遠不會聲明 `PyObject` 型別的自動變數或靜態變數，只能聲明 PyObject* 型別的指標變數。唯一的例外是型別物件；由於它們絕不能被釋放，因此它們通常是靜態 `PyTypeObject` 物件。

所有 Python 物件（甚至是 Python 整數）都有一個型別 (type) 和一個參照計數 (reference count)。一個物件的型別決定了它是什麼種類的物件（例如一個整數、一個 list 或一個使用者定義的函式；還有更多型別，請見標準型別階層）。對於每個眾所周知的型別，都有一個巨集來檢查物件是否屬於該型別；例如，若（且唯若）*a* 指向的物件是 Python list 時，`PyList_Check(a)` 為真。

### 參照計數

參照計數很重要，因為現今的電腦記憶體大小是有限的（而且通常是非常有限的）；它計算有多少個不同的地方用有了一個物件的強參照。這樣的地方可以是另一個物件，或者全域（或靜態）C 變數，或者某個 C 函式中的本地變數。當一個物件的最後一個強參照被釋放時（即其的參照計數變為零），該物件將被解除配置 (deallocated)。如果它包含對其他物件的參照，則它們的參照會被釋放。如果這樣的釋放使得再也沒有任何對於它們的參照，則可以依次為那些其他物件解除配置，依此類推。（此處相互參照物件的存在是個明顯的問題；目前，解決方案是「就不要那樣做」。）

參照計數總是被明確地操作。正常的方法是使用巨集 `Py_INCREF()` 來取得對於物件的參照（即參照計數加一），並使用巨集 `Py_DECREF()` 來釋放參照（即將參照計數減一）。`Py_DECREF()` 巨集比 incref 巨集複雜得多，因為它必須檢查參照計數是否變為零，然後呼叫物件的釋放器 (deallocator)。釋放器是包含在物件型別結構中的函式指標。特定型別的釋放器，在如果是一個複合物件型別（例如 list）時負責釋放物件中包含的其他物件的參照，並執行任何需要的額外完結步驟。參照計數不可能溢出；至少與虛擬記憶體中用來保存參照計數的不同記憶體位置數量一樣多的位元會被使用（假設 `sizeof(Py_ssize_t) >= sizeof(void*)`）。因此參照計數增加是一個簡單的操作。

沒有必要為每個包含物件指標的本地變數物件都持有一個強參照（即增加參照計數）。理論上，當變數指向它時，物件的參照計數會增加 1，而當變數離開作用域時就會減少 1。然而這兩者會相互抵消，所以最後參照計數沒有改變。使用參照計數的唯一真正原因是防止物件還有變數指向它時被解除配置。如果我們知道至少有一個物件的其他參照生存了至少與我們的變數一樣久，就不需要臨時增加建立新的強參照（即增加參照計數）。出現這種情況的一個重要情況是在從 Python 呼叫的擴充模組中作為引數傳遞給 C 函式的物件；呼叫機制保證在呼叫期間保持對每個參數的參照。

然而，一個常見的陷阱是從一個 list 中提取一個物件並保留它一段時間而不取得其參照。某些其他操作可能會從列表中刪除該物件，減少其參照計數並可能取消分配它。真正的危險是看似無害的操作可能會叫用可以執行此操作的任意 Python 程式碼；有一個程式碼路徑允許控制權從 `Py_DECREF()` 回歸使用者，因此幾乎任何操作都有潛在危險。

一種安全的方法是都使用通用 (generics) 操作（名稱以 `PyObject_`、`PyNumber_`、`PySequence_` 或 `PyMapping_` 開頭的函式）。這些操作總是建立新的對於它們回傳物件的強參照（即增加其參照計數）。這讓呼叫者有責任在處理完結果後呼叫 `Py_DECREF()`；這就成為第二本質。

#### 參照計數詳細資訊

Python/C API 中函式的參照計數行為最好用參照的所有權來解釋。所有權附屬於參照而非物件（物件並非被擁有，它們總是共享的）。「擁有參照」意味著當不再需要該參照時，負責在其上呼叫 Py_DECREF。所有權也可以轉移，這意味著接收參照所有權的程式碼最終會負責在不需要參照時透過呼叫 `Py_DECREF()` 或 `Py_XDECREF()` 釋放參照 --- 或者將這個責任再傳遞出去（通常是給它的呼叫者）。當一個函式將參照的所有權傳遞給它的呼叫者時，呼叫者被稱為接收到一個新參照。當沒有所有權轉移時，呼叫者被稱為借用參照。如果是借用參照就不需要做任何事情。

相反地，當呼叫的函式傳入物件的參照時，有兩種可能性：函式有竊取 (steal) 物件的參照，或者沒有。 竊取參照意味著當你將參照傳遞給函式時，該函式假定它現在擁有該參照，並且你不再對它負責。

很少有函式會竊取參照；兩個值得注意的例外是 `PyList_SetItem()` 和 `PyTuple_SetItem()`，它們竊取了對項目的參照（但不是對項目所在的 tuple 或 list 的參照！）。因為有著使用新建立的物件來增加 (populate) tuple 或 list 的習慣，這些函式旨在竊取參照；例如，建立 tuple `(1, 2, "three")` 的程式碼可以如下所示（先暫時忘記錯誤處理；更好的編寫方式如下所示）：

    PyObject *t;

    t = PyTuple_New(3);
    PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
    PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
    PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

這裡 `PyLong_FromLong()` 會回傳一個新的參照，它立即被 `PyTuple_SetItem()` 竊取。如果你想繼續使用一個物件，儘管對它的參照將被竊取，請在呼叫參照竊取函式之前使用 `Py_INCREF()` 來取得另一個參照。

附帶地說，`PyTuple_SetItem()` 是設定 tuple 項目的唯一方法； `PySequence_SetItem()` 和 `PyObject_SetItem()` 拒絕這樣做，因為 tuple 是一種不可變 (immutable) 的資料型別。你應該只對你自己建立的 tuple 使用 `PyTuple_SetItem()`。

可以使用 `PyList_New()` 和 `PyList_SetItem()` 編寫用於填充列表的等效程式碼。

但是在實際操作中你很少會使用這些方法來建立和增加 tuple 和 list。有一個通用函式 `Py_BuildValue()` 可以從 C 值建立最常見的物件，由 format string 引導。例如上面的兩個程式碼可以用以下程式碼替換（它還負責了錯誤檢查）：

    PyObject *tuple, *list;

    tuple = Py_BuildValue("(iis)", 1, 2, "three");
    list = Py_BuildValue("[iis]", 1, 2, "three");

更常見的是以那些借用參照的項目來使用 `PyObject_SetItem()` 及其系列函式，比如傳遞給你正在編寫的函式的引數。在那種情況下，他們關於參照的行為會比較穩健，因為你不取得新的一個參照就可以放棄參照（「讓它被竊取」）。例如，此函式將 list（實際上是任何可變序列）的所有項目設定於給定項目：

    int
    set_all(PyObject *target, PyObject *item)
    {
        Py_ssize_t i, n;

        n = PyObject_Length(target);
        if (n < 0)
            return -1;
        for (i = 0; i < n; i++) {
            PyObject *index = PyLong_FromSsize_t(i);
            if (!index)
                return -1;
            if (PyObject_SetItem(target, index, item) < 0) {
                Py_DECREF(index);
                return -1;
            }
            Py_DECREF(index);
        }
        return 0;
    }

函式回傳值的情況略有不同。雖然傳遞對大多數函式的參照不會改變你對該參照的所有權責任，但許多回傳物件參照的函式會給你該參照的所有權。原因很簡單：在很多情況下，回傳的物件是即時建立的，你獲得的參照是對該物件的唯一參照。因此回傳物件參照的通用函式，如 `PyObject_GetItem()` 和 `PySequence_GetItem()`，總是回傳一個新的參照（呼叫者成為參照的所有者）。

重要的是要意識到你是否擁有一個函式回傳的參照只取決於你呼叫哪個函式 --- 羽毛 (plumage)（作為引數傳遞給函式的物件之型別）不會進入它！因此，如果你使用 `PyList_GetItem()` 從 list 中提取一個項目，你不會擁有其參照 --- 但如果你使用 `PySequence_GetItem()` 從同一 list 中取得相同的項目（且恰好使用完全相同的引數），你確實會擁有對回傳物件的參照。

以下是一個範例，說明如何編寫函式來計算一個整數 list 中項目的總和；一次使用 `PyList_GetItem()`，一次使用 `PySequence_GetItem()`：

    long
    sum_list(PyObject *list)
    {
        Py_ssize_t i, n;
        long total = 0, value;
        PyObject *item;

        n = PyList_Size(list);
        if (n < 0)
            return -1; /* 不是 list */
        for (i = 0; i < n; i++) {
            item = PyList_GetItem(list, i); /* 不會失敗 */
            if (!PyLong_Check(item)) continue; /* 跳過非整數 */
            value = PyLong_AsLong(item);
            if (value == -1 && PyErr_Occurred())
                /* 整數太大，無法放入 C long，退出 */
                return -1;
            total += value;
        }
        return total;
    }

    long
    sum_sequence(PyObject *sequence)
    {
        Py_ssize_t i, n;
        long total = 0, value;
        PyObject *item;
        n = PySequence_Length(sequence);
        if (n < 0)
            return -1; /* 沒有長度 */
        for (i = 0; i < n; i++) {
            item = PySequence_GetItem(sequence, i);
            if (item == NULL)
                return -1; /* 不是序列或其他錯誤 */
            if (PyLong_Check(item)) {
                value = PyLong_AsLong(item);
                Py_DECREF(item);
                if (value == -1 && PyErr_Occurred())
                    /* 整數太大，無法放入 C long，退出 */
                    return -1;
                total += value;
            }
            else {
                Py_DECREF(item); /* 丟棄參照所有權 */
            }
        }
        return total;
    }

### 型別

有少數幾個其他的資料型別在 Python/C API 中發揮重要作用；大多數是簡單的 C 型別，例如 int、long、double 和 char*。一些結構型別被用於描述用於列出模組所匯出的函式或新物件型別的資料屬性的靜態表，其他則用於描述複數的值。這些將與使用它們的函式一起討論。

type Py_ssize_t
  為 穩定 ABI 的一部分.

  一個帶符號的整數型別，使得 `sizeof(Py_ssize_t) == sizeof(size_t)`。 C99 沒有直接定義這樣的東西（size_t 是無符號整數型別）。有關詳細資訊，請參閱 PEP 353。 `PY_SSIZE_T_MAX` 是 `Py_ssize_t` 型別的最大正值。

## 例外

如果需要特定的錯誤處理，Python 開發者就只需要處理例外；未處理的例外會自動傳遞給呼叫者，然後傳遞給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡它們透過堆疊回溯 (stack trace) 回報給使用者。

然而，對於 C 開發者來說，錯誤檢查總是必須是顯式的。除非在函式的文件中另有明確聲明，否則 Python/C API 中的所有函式都可以引發例外。通常當一個函式遇到錯誤時，它會設定一個例外，丟棄它擁有的任何物件參照，並回傳一個錯誤指示器。如果沒有另外文件記錄，這個指示器要麼是 `NULL` 不然就是 `-1`，取決於函式的回傳型別。有些函式會回傳布林值 true/false 結果，false 表示錯誤。很少有函式不回傳明確的錯誤指示器或者有不明確的回傳值，而需要使用 `PyErr_Occurred()` 明確測試錯誤。這些例外都會被明確地記錄於文件。

例外的狀態會在個別執行緒的儲存空間 (per-thread storage) 中維護（這相當於在非執行緒應用程式中使用全域儲存空間）。執行緒可以處於兩種狀態之一：發生例外或未發生例外。函式 `PyErr_Occurred()` 可用於檢查這一點：當例外發生時，它回傳對例外型別物件的借用參照，否則回傳 `NULL`。設定例外狀態的函式有很多：`PyErr_SetString()` 是最常見的（儘管不是最通用的）設定例外狀態的函式，而 `PyErr_Clear()` 是用來清除例外狀態。

完整的例外狀態由三個（都可以為 `NULL` 的）物件組成：例外型別、對應的例外值和回溯。這些與 `sys.exc_info()` 的 Python 結果具有相同的含義；但是它們並不相同：Python 物件表示由 Python `try` ... `except` 陳述式處理的最後一個例外，而 C 層級的例外狀態僅在例外在 C 函式間傳遞時存在，直到它到達 Python 位元組碼直譯器的主迴圈，該迴圈負責將它傳遞給 `sys.exc_info()` 和其系列函式。

請注意，從 Python 1.5 開始，從 Python 程式碼存取例外狀態的首選且支援執行緒安全的方法是呼叫 `sys.exc_info()` 函式，它回傳 Python 程式碼的個別執行緒例外狀態。此外，兩種存取例外狀態方法的語義都發生了變化，因此捕獲例外的函式將保存和恢復其執行緒的例外狀態，從而保留其呼叫者的例外狀態。這可以防止例外處理程式碼中的常見錯誤，這些錯誤是由看似無辜的函式覆蓋了正在處理的例外而引起的；它還替回溯中被堆疊框 (stack frame) 參照的物件減少了通常不需要的生命週期延長。

作為一般原則，呼叫另一個函式來執行某些任務的函式應該檢查被呼叫函式是否引發了例外，如果是，則將例外狀態傳遞給它的呼叫者。它應該丟棄它擁有的任何物件參照，並回傳一個錯誤指示符，但它不應該設定另一個例外 --- 這將覆蓋剛剛引發的例外，並丟失關於錯誤確切原因的重要資訊。

上面的 `sum_sequence()` 範例展示了一個檢測例外並將其繼續傳遞的例子。碰巧這個例子在檢測到錯誤時不需要清理任何擁有的參照。以下範例函式展示了一些錯誤清理。首先，為了提醒你為什麼喜歡 Python，我們展示了等效的 Python 程式碼：

    def incr_item(dict, key):
        try:
            item = dict[key]
        except KeyError:
            item = 0
        dict[key] = item + 1

這是相應的 C 程式碼：

    int
    incr_item(PyObject *dict, PyObject *key)
    {
        /* Objects all initialized to NULL for Py_XDECREF */
        PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
        int rv = -1; /* Return value initialized to -1 (failure) */

        item = PyObject_GetItem(dict, key);
        if (item == NULL) {
            /* Handle KeyError only: */
            if (!PyErr_ExceptionMatches(PyExc_KeyError))
                goto error;

            /* Clear the error and use zero: */
            PyErr_Clear();
            item = PyLong_FromLong(0L);
            if (item == NULL)
                goto error;
        }
        const_one = PyLong_FromLong(1L);
        if (const_one == NULL)
            goto error;

        incremented_item = PyNumber_Add(item, const_one);
        if (incremented_item == NULL)
            goto error;

        if (PyObject_SetItem(dict, key, incremented_item) < 0)
            goto error;
        rv = 0; /* Success */
        /* Continue with cleanup code */

     error:
        /* Cleanup code, shared by success and failure path */

        /* Use Py_XDECREF() to ignore NULL references */
        Py_XDECREF(item);
        Py_XDECREF(const_one);
        Py_XDECREF(incremented_item);

        return rv; /* -1 for error, 0 for success */
    }

這個例子代表了在 C 語言中對使用 `goto` 陳述句的認同！它闡述了以 `PyErr_ExceptionMatches()` 和 `PyErr_Clear()` 來處理特定的例外，以及以 `Py_XDECREF()` 來配置其所擁有且可能為 `NULL` 的參照（注意名稱中的 `'X'`；`Py_DECREF()` 在遇到 `NULL` 參照時會崩潰）。重要的是，用於保存擁有的參照的變數被初始化為 `NULL` 以使其能夠順利作用；同樣地，回傳值被初始化為 `-1`（失敗），並且僅在最後一次呼叫成功後才設定為成功。

## 嵌入式Python

只有 Python 直譯器的嵌入者（而不是擴充編寫者）需要擔心的一項重要任務是 Python 直譯器的初始化與完成階段。直譯器的大部分功能只能在直譯器初始化後使用。

基本的初始化函式是 `Py_Initialize()`。這會初始化帶有載入模組的表，並建立基礎模組 `builtins`、`__main__` 和 `sys`。它還會初始化模組搜索路徑 (`sys.path`)。

`Py_Initialize()` 不設定「腳本引數列表 (script argument list)」 (`sys.argv`)。如果稍後將要執行的 Python 程式碼需要此變數，則必須設定 `PyConfig.argv` 和 `PyConfig.parse_argv`，請見 Python 初始化配置。

在大多數系統上（特別是在 Unix 和 Windows 上，儘管細節略有不同），`Py_Initialize()` 會假設Python 函式庫相對於 Python 直譯器可執行檔案的位置固定，並根據其對標準 Python 直譯器可執行檔案位置的最佳猜測來計算模組搜尋路徑。或者更詳細地說，它會在 shell 命令搜尋路徑（環境變數 `PATH`）中找到名為 `python` 的可執行檔案，並在其父目錄中查找一個名為 `lib/pythonX.Y` 的目錄的相對位置。

例如，如果在 `/usr/local/bin/python` 中找到 Python 可執行檔案，它將假定函式庫位於 `/usr/local/lib/pythonX.Y` 中。（事實上這個特定的路徑也是「後備 (fallback)」位置，當在 `PATH` 中找不到名為 `python` 的可執行檔案時使用。）使用者可以透過設定環境變數來覆蓋此行為 `PYTHONHOME`，或者透過設定 `PYTHONPATH` 在標準路徑前面插入額外的目錄。

The embedding application can steer the search by setting `PyConfig.program_name` before calling `Py_InitializeFromConfig()`. Note that `PYTHONHOME` still overrides this and `PYTHONPATH` is still inserted in front of the standard path.

有時會希望能夠「取消初始化 (uninitialize)」Python。例如，應用程式可能想要重新開始（再次呼叫 `Py_Initialize()`）或者應用程式簡單地完成了對 Python 的使用並想要釋放 Python 分配的記憶體。這可以透過呼叫 `Py_FinalizeEx()` 來完成。如果 Python 目前處於初始化狀態，函式 `Py_IsInitialized()` 會回傳 true。有關這些功能的更多資訊將在後面的章節中給出。請注意 `Py_FinalizeEx()` 不會釋放由 Python 直譯器分配的所有記憶體，例如目前無法釋放被擴充模組所分配的記憶體。

## 除錯建置

Python 可以在建置時使用多個巨集來啟用對直譯器和擴充模組的額外檢查，這些檢查往往會在執行環境 (runtime) 增加大量開銷 (overhead)，因此預設情況下不啟用它們。

Python 原始碼發佈版本中的 `Misc/SpecialBuilds.txt` 檔案有一份包含多種除錯構置的完整列表，為支援追蹤參照計數、為記憶體分配器除錯或對主直譯器迴圈進行低階分析的建置。本節的其餘部分將僅描述最常用的建置。

Py_DEBUG

Compiling the interpreter with the `Py_DEBUG` macro defined produces what is generally meant by a debug build of Python.

On Unix, `Py_DEBUG` can be enabled by adding `--with-pydebug` to the `./configure` command. This will also disable compiler optimization.

On Windows, selecting a debug build (e.g., by passing the `-d` option to `PCbuild/build.bat`) automatically enables `Py_DEBUG`. Additionally, the presence of the not-Python-specific `_DEBUG` macro, when defined by the compiler, will also implicitly enable `Py_DEBUG`.

In addition to the reference count debugging described below, extra checks are performed. See Python Debug Build for more details.

定義 `Py_TRACE_REFS` 來啟用參照追蹤（參見`設定 --with-trace-refs 選項`）。當有定義時，透過向每個 `PyObject` 新增兩個額外欄位來維護有效物件的循環雙向鍊表 (circular doubly linked list)。全體分配也有被追蹤。退出時將印出所有現行參照。（在交互模式下，這發生在直譯器運行的每個陳述句之後。）

有關更多詳細資訊，請參閱 Python 原始碼發布版中的 `Misc/SpecialBuilds.txt`。

## 建議的第三方工具

以下第三方工具提供了更簡單且更細緻的方法來為 Python 建立 C、C++ 和 Rust 擴充模組：

- Cython

- cffi

- HPy

- nanobind (C++)

- Numba

- pybind11 (C++)

- PyO3 (Rust)

- SWIG

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.

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.

也參考

Python Packaging User Guide: Binary Extensions

  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.