簡介

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

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

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

編寫標準

如果你正在編寫要引入於 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。

有用的巨集

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

PyMODINIT_FUNC

Declare an extension module PyInit initialization function. The function return type is PyObject*. The macro declares any special linkage declarations required by the platform, and for C++ declares the function as extern "C".

The initialization function must be named PyInit_name, where name is the name of the module, and should be the only non-static item defined in the module file. Example:

static struct PyModuleDef spam_module = {
    PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
};

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spam_module);
}

Py_ABS(x)

回傳 x 的絕對值。

在 3.3 版新加入.

Py_ALWAYS_INLINE

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

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

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

If Python is built in debug mode (if the Py_DEBUG macro is defined), the Py_ALWAYS_INLINE macro does nothing.

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

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

在 3.11 版新加入.

Py_CHARMASK(c)

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

Py_DEPRECATED(version)

將其用於已棄用的聲明。巨集必須放在符號名稱之前。

範例：

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

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

Py_GETENV(s)

類似於 getenv(s)，但如果在命令列上傳遞了 -E（即如果設定了 Py_IgnoreEnvironmentFlag）則回傳 NULL。

Py_MAX(x, y)

回傳 x 和 y 之間的最大值。

在 3.3 版新加入.

Py_MEMBER_SIZE(type, member)

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

在 3.6 版新加入.

Py_MIN(x, y)

回傳 x 和 y 之間的最小值。

在 3.3 版新加入.

Py_NO_INLINE

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

用法：

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

在 3.11 版新加入.

Py_STRINGIFY(x)

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

在 3.4 版新加入.

Py_UNREACHABLE()

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

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

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

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

在 3.7 版新加入.

Py_UNUSED(arg)

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

在 3.4 版新加入.

PyDoc_STRVAR(name, str)

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

如 PEP 7 中所指明，使用 PyDoc_STRVAR 作為文件字串可以支援在沒有文件字串的情況下建置 Python。

範例：

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

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

PyDoc_STR(str)

為給定的輸入字串建立一個文件字串，如果文件字串被禁用則建立空字串。

如 PEP 7 中所指明，使用 PyDoc_STR 指定文件字串以支援在沒有文件字串下建置 Python。

範例：

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

物件、型別和參照計數

大多數 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) 為真。

參照計數

The reference count is important because today's computers have a finite (and often severely limited) memory size; it counts how many different places there are that have a strong reference to an object. Such a place could be another object, or a global (or static) C variable, or a local variable in some C function. When the last strong reference to an object is released (i.e. its reference count becomes zero), the object is deallocated. If it contains references to other objects, those references are released. Those other objects may be deallocated in turn, if there are no more references to them, and so on. (There's an obvious problem with objects that reference each other here; for now, the solution is "don't do that.")

Reference counts are always manipulated explicitly. The normal way is to use the macro Py_INCREF() to take a new reference to an object (i.e. increment its reference count by one), and Py_DECREF() to release that reference (i.e. decrement the reference count by one). The Py_DECREF() macro is considerably more complex than the incref one, since it must check whether the reference count becomes zero and then cause the object's deallocator to be called. The deallocator is a function pointer contained in the object's type structure. The type-specific deallocator takes care of releasing references for other objects contained in the object if this is a compound object type, such as a list, as well as performing any additional finalization that's needed. There's no chance that the reference count can overflow; at least as many bits are used to hold the reference count as there are distinct memory locations in virtual memory (assuming sizeof(Py_ssize_t) >= sizeof(void*)). Thus, the reference count increment is a simple operation.

It is not necessary to hold a strong reference (i.e. increment the reference count) for every local variable that contains a pointer to an object. In theory, the object's reference count goes up by one when the variable is made to point to it and it goes down by one when the variable goes out of scope. However, these two cancel each other out, so at the end the reference count hasn't changed. The only real reason to use the reference count is to prevent the object from being deallocated as long as our variable is pointing to it. If we know that there is at least one other reference to the object that lives at least as long as our variable, there is no need to take a new strong reference (i.e. increment the reference count) temporarily. An important situation where this arises is in objects that are passed as arguments to C functions in an extension module that are called from Python; the call mechanism guarantees to hold a reference to every argument for the duration of the call.

However, a common pitfall is to extract an object from a list and hold on to it for a while without taking a new reference. Some other operation might conceivably remove the object from the list, releasing that reference, and possibly deallocating it. The real danger is that innocent-looking operations may invoke arbitrary Python code which could do this; there is a code path which allows control to flow back to the user from a Py_DECREF(), so almost any operation is potentially dangerous.

A safe approach is to always use the generic operations (functions whose name begins with PyObject_, PyNumber_, PySequence_ or PyMapping_). These operations always create a new strong reference (i.e. increment the reference count) of the object they return. This leaves the caller with the responsibility to call Py_DECREF() when they are done with the result; this soon becomes second nature.

參照計數詳細資訊

The reference count behavior of functions in the Python/C API is best explained in terms of ownership of references. Ownership pertains to references, never to objects (objects are not owned: they are always shared). "Owning a reference" means being responsible for calling Py_DECREF on it when the reference is no longer needed. Ownership can also be transferred, meaning that the code that receives ownership of the reference then becomes responsible for eventually releasing it by calling Py_DECREF() or Py_XDECREF() when it's no longer needed---or passing on this responsibility (usually to its caller). When a function passes ownership of a reference on to its caller, the caller is said to receive a new reference. When no ownership is transferred, the caller is said to borrow the reference. Nothing needs to be done for a borrowed reference.

相反地，當呼叫的函式傳入物件的參照時，有兩種可能性：函式有竊取 (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");

It is much more common to use PyObject_SetItem() and friends with items whose references you are only borrowing, like arguments that were passed in to the function you are writing. In that case, their behaviour regarding references is much saner, since you don't have to take a new reference just so you can give that reference away ("have it be stolen"). For example, this function sets all items of a list (actually, any mutable sequence) to a given item:

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; /* Not a list */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyLong_Check(item)) continue; /* Skip non-integers */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Integer too big to fit in a C long, bail out */
            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; /* Has no length */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Integer too big to fit in a C long, bail out */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* Discard reference ownership */
        }
    }
    return total;
}

型別

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

type Py_ssize_t

Part of the Stable 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) 參照的物件減少了通常不需要的生命週期延長。

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

A simple example of detecting exceptions and passing them on is shown in the sum_sequence() example above. It so happens that this example doesn't need to clean up any owned references when it detects an error. The following example function shows some error cleanup. First, to remind you why you like Python, we show the equivalent Python code:

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 在標準路徑前面插入額外的目錄。

嵌入的應用程式可以透過在呼叫 Py_Initialize() 之前呼叫 Py_SetProgramName(file) 來引導搜索。請注意 PYTHONHOME 仍然覆蓋它並且 PYTHONPATH 仍然插入在標準路徑的前面。需要完全控制權的應用程式必須實作自己的 Py_GetPath()、Py_GetPrefix()、Py_GetExecPrefix() 和 Py_GetProgramFullPath()（全部定義在 Modules/getpath.c)。

有時會希望能夠「取消初始化 (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. Py_DEBUG is enabled in the Unix build by adding --with-pydebug to the ./configure command. It is also implied by the presence of the not-Python-specific _DEBUG macro. When Py_DEBUG is enabled in the Unix build, compiler optimization is disabled.

除了下面描述的參照計數除錯之外，還會執行額外的檢查，請參閱 Python 除錯建置。

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

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