簡介¶
Python 的應用程式程式設計介面 (API) 為 C 和 C++ 程式設計師提供了在各種級別訪問 Python 直譯器的能力。該 API 同樣適用於 C++，但為了簡潔起見，通常稱為 Python/C API。使用 Python/C API 有兩個根本不同的原因。第一個原因是編寫用於特定目的的擴充套件模組；這些是擴充套件 Python 直譯器的 C 模組。這可能是最常見的用法。第二個原因是將 Python 用作更大應用程式中的元件；這種技術通常被稱為在應用程式中嵌入 Python。
編寫擴充套件模組是一個相對容易理解的過程，其中“菜譜”方法非常有效。有一些工具可以在一定程度上自動化該過程。雖然人們自早期就將 Python 嵌入到其他應用程式中，但嵌入 Python 的過程不如編寫擴充套件模組那麼直接。
許多 API 函式在嵌入或擴充套件 Python 時都很有用；此外，大多數嵌入 Python 的應用程式也需要提供自定義擴充套件，因此最好在嘗試在實際應用程式中嵌入 Python 之前熟悉如何編寫擴充套件。
編碼標準¶
如果你正在編寫 C 程式碼以包含在 CPython 中，你必須遵循 PEP 7 中定義的指南和標準。這些指南適用於你貢獻的任何 Python 版本。對於你自己的第三方擴充套件模組，無需遵循這些約定，除非你最終期望將它們貢獻給 Python。
包含檔案¶
要使用 Python/C API 所需的所有函式、型別和宏定義都透過以下行包含在你的程式碼中
#define PY_SSIZE_T_CLEAN
#include <Python.h>
這暗示了以下標準標頭的包含：<stdio.h>、 <string.h>、 <errno.h>、 <limits.h>、 <assert.h> 和 <stdlib.h> (如果可用)。
注意
由於 Python 可能會定義一些預處理器定義，這些定義會影響某些系統上的標準標頭，因此你必須在包含任何標準標頭之前包含 Python.h。
建議始終在包含 Python.h 之前定義 PY_SSIZE_T_CLEAN。有關此宏的描述，請參閱 解析引數和構建值。
Python.h 定義的所有使用者可見名稱（除了包含的標準標頭定義的名稱）都具有 Py 或 _Py 字首之一。以 _Py 開頭的名稱供 Python 實現內部使用，擴充套件編寫者不應使用。結構成員名稱沒有保留的字首。
注意
使用者程式碼絕不應定義以 Py 或 _Py 開頭的名稱。這會使讀者感到困惑，並危及使用者程式碼向未來 Python 版本的可移植性，未來 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 是安裝程式指定的安裝目錄。
要包含標頭檔案，請將兩個目錄（如果不同）放在編譯器的包含搜尋路徑中。請勿將父目錄放在搜尋路徑中，然後使用 #include <pythonX.Y/Python.h>；這將會在多平臺構建中中斷，因為 prefix 下的平臺無關標頭檔案包含來自 exec_prefix 的平臺特定標頭檔案。
C++ 使用者應注意，儘管 API 完全使用 C 定義，但標頭檔案正確地將入口點宣告為 extern "C"。因此，無需執行任何特殊操作即可從 C++ 使用該 API。
有用的宏¶
Python 標頭檔案中定義了幾個有用的宏。許多宏在它們有用的地方附近定義（例如 Py_RETURN_NONE）。其他更通用的實用程式在此處定義。這不一定是完整的列表。
-
PyMODINIT_FUNC¶
宣告一個擴充套件模組
PyInit初始化函式。該函式的返回型別是 PyObject*。該宏宣告平臺所需的任何特殊連結宣告，併為 C++ 將該函式宣告為extern "C"。初始化函式必須命名為
PyInit_name，其中 name 是模組的名稱，並且應該是模組檔案中定義的唯一非static項。示例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¶
要求編譯器始終內聯一個靜態行內函數。編譯器可以忽略它並決定不內聯該函式。
當在停用函式內聯的情況下以除錯模式構建 Python 時，它可用於內聯效能關鍵的靜態行內函數。例如，當以除錯模式構建時，MSC 會停用函式內聯。
盲目地使用 Py_ALWAYS_INLINE 標記靜態行內函數可能會導致更差的效能（例如，由於程式碼大小增加）。在成本/收益分析方面，編譯器通常比開發人員更聰明。
如果 Python 是以除錯模式構建的（如果定義了
Py_DEBUG宏），則Py_ALWAYS_INLINE宏不執行任何操作。它必須在函式返回型別之前指定。用法
static inline Py_ALWAYS_INLINE int random(void) { return 4; }
在版本 3.11 中新增。
-
Py_CHARMASK(c)¶
引數必須是字元或 [-128, 127] 或 [0, 255] 範圍內的整數。此宏返回強制轉換為
unsigned char的c。
-
Py_DEPRECATED(version)¶
將此用於已棄用的宣告。宏必須放在符號名稱之前。
示例
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
在版本 3.8 中更改：添加了 MSVC 支援。
-
Py_GETENV(s)¶
類似於
getenv(s)，但如果命令列上傳遞了-E（請參閱PyConfig.use_environment），則返回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()¶
當您有一個按設計無法到達的程式碼路徑時使用此宏。例如，在
switch語句中的default:子句中，其中所有可能的值都已在case語句中涵蓋。在您可能想放置assert(0)或abort()呼叫的地方使用它。在釋出模式下，該宏有助於編譯器最佳化程式碼，並避免有關不可達程式碼的警告。例如，該宏在釋出模式下使用 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 中的規定，為支援在沒有文件字串的情況下構建 Python，請使用
PyDoc_STRVAR來處理文件字串。示例
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element."); static PyMethodDef deque_methods[] = { // ... {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc}, // ... }
物件、型別和引用計數¶
大多數 Python/C API 函式都有一個或多個型別為 PyObject* 的引數以及一個返回值。此型別是指向表示任意 Python 物件的不透明資料型別的指標。由於在大多數情況下（例如，賦值、作用域規則和引數傳遞），Python 語言以相同的方式處理所有 Python 物件型別，因此它們應該由單個 C 型別表示。幾乎所有的 Python 物件都存在於堆中：永遠不要宣告 PyObject 型別的自動或靜態變數，只能宣告 PyObject* 型別的指標變數。唯一的例外是型別物件；由於這些物件永遠不應該被釋放，它們通常是靜態的 PyTypeObject 物件。
所有 Python 物件（甚至是 Python 整數）都有一個型別和一個引用計數。物件的型別決定了它是什麼型別的物件（例如，整數、列表或使用者定義的函式；正如 標準型別層次結構 中解釋的那樣，還有很多）。對於每個眾所周知的型別，都有一個宏來檢查物件是否屬於該型別；例如，如果（並且僅當）a 指向的物件是 Python 列表，則 PyList_Check(a) 為真。
引用計數¶
引用計數很重要，因為今天的計算機具有有限（且通常受到嚴格限制）的記憶體大小；它計算有多少不同的地方對某個物件有強引用。這樣一個地方可能是另一個物件，或者是一個全域性（或靜態）的 C 變數，或者是一些 C 函式中的區域性變數。當對物件的最後一個 強引用 被釋放（即其引用計數變為零）時，該物件將被釋放。如果它包含對其他物件的引用，則這些引用將被釋放。如果沒有對其他物件的更多引用，則那些其他物件可能會依次被釋放，依此類推。（這裡，相互引用的物件會存在一個明顯的問題；目前，解決方案是“不要這樣做”。）
引用計數總是被顯式操作。通常的方法是使用宏 Py_INCREF() 來獲取對物件的新引用（即將其引用計數增加 1），並使用 Py_DECREF() 來釋放該引用（即將其引用計數減 1）。Py_DECREF() 宏比 incref 宏複雜得多，因為它必須檢查引用計數是否變為零，然後導致呼叫物件的釋放器。釋放器是包含在物件型別結構中的函式指標。特定於型別的釋放器負責釋放物件中包含的其他物件的引用（如果這是一個複合物件型別，例如列表），並執行所需的任何其他最終化操作。引用計數不可能溢位；至少使用與虛擬記憶體中不同記憶體位置一樣多的位來儲存引用計數（假設 sizeof(Py_ssize_t) >= sizeof(void*)）。因此，引用計數遞增是一個簡單的操作。
對於每個包含指向物件的指標的區域性變數，不必持有 強引用（即增加引用計數）。理論上，當變數指向物件時，物件的引用計數會增加 1，而當變數超出作用域時，物件的引用計數會減少 1。但是，這兩者相互抵消，因此最終引用計數不會改變。使用引用計數的唯一真正原因是防止物件在我們變數指向它時被釋放。如果我們知道至少還有另一個對該物件的引用與我們的變數一樣長，則無需臨時獲取新的 強引用（即增加引用計數）。出現這種情況的一個重要場景是，在從 Python 呼叫的擴充套件模組中作為引數傳遞給 C 函式的物件；呼叫機制保證在呼叫期間保持對每個引數的引用。
但是，一個常見的陷阱是從列表中提取一個物件並在不獲取新引用的情況下保留它一段時間。一些其他操作可能會將物件從列表中刪除，釋放該引用，並可能釋放它。真正的危險是，看起來無辜的操作可能會呼叫任意的 Python 程式碼，而這些程式碼可能會執行此操作；有一條程式碼路徑允許控制從 Py_DECREF() 返回到使用者，因此幾乎任何操作都可能存在危險。
一種安全的方法是始終使用通用操作（名稱以 PyObject_、PyNumber_、PySequence_ 或 PyMapping_ 開頭的函式）。這些操作始終會建立返回物件的新 強引用（即增加引用計數）。這讓呼叫者負責在使用完結果後呼叫 Py_DECREF()；這很快就會成為第二天性。
引用計數詳情¶
Python/C API 中函式的引用計數行為最好用引用所有權來解釋。所有權與引用有關，而與物件無關（物件不被擁有：它們總是被共享的）。“擁有引用”意味著當不再需要該引用時，有責任呼叫 Py_DECREF。所有權也可以轉移，這意味著接收引用的程式碼隨後有責任在不再需要時透過呼叫 Py_DECREF() 或 Py_XDECREF() 來最終釋放它，或者將此責任傳遞給（通常是其呼叫者）。當函式將引用的所有權傳遞給其呼叫者時，呼叫者被稱為接收到一個新的引用。當沒有所有權轉移時，呼叫者被稱為借用該引用。對於借用的引用，無需進行任何操作。
相反，當呼叫函式傳入對一個物件的引用時，有兩種可能性：函式竊取對該物件的引用，或者不竊取。竊取引用意味著當你將一個引用傳遞給一個函式時，該函式假定它現在擁有該引用，並且你不再對此負責。
很少有函式會竊取引用；兩個著名的例外是 PyList_SetItem() 和 PyTuple_SetItem()，它們會竊取對專案（但不是對專案放入的元組或列表！）的引用。這些函式被設計為竊取引用，因為這是一種用新建立的物件填充元組或列表的常見習慣用法；例如，建立元組 (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() 是設定元組專案的唯一方法；PySequence_SetItem() 和 PyObject_SetItem() 拒絕這樣做，因為元組是不可變的資料型別。你應該只對你正在自己建立的元組使用 PyTuple_SetItem()。
可以使用 PyList_New() 和 PyList_SetItem() 編寫等效的用於填充列表的程式碼。
然而，在實踐中，你很少會使用這些方法來建立和填充元組或列表。有一個通用函式 Py_BuildValue()，它可以根據 C 值，在格式化字串的指導下建立大多數常見物件。例如，上面的兩個程式碼塊可以用以下程式碼替換（它還處理了錯誤檢查）
PyObject *tuple, *list;
tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
更常見的是使用 PyObject_SetItem() 及其同類，處理你只是借用其引用的專案，例如傳遞給你正在編寫的函式的引數。在這種情況下，它們關於引用的行為更合理，因為你無需為了放棄引用而獲取新的引用（“讓它被竊取”）。例如，此函式將列表（實際上是任何可變序列）的所有項設定為給定的項
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()）總是返回一個新的引用（呼叫者成為引用的所有者）。
重要的是要認識到，你是否擁有函式返回的引用僅取決於你呼叫的函式，而羽毛（傳遞給函式的引數物件的型別）並不起作用！因此，如果你使用 PyList_GetItem() 從列表中提取一個專案，你並不擁有該引用；但是如果你使用 PySequence_GetItem()（恰好採用相同的引數）從同一個列表中獲取相同的專案，則你確實擁有對返回物件的引用。
以下是如何編寫一個計算整數列表項之和的函式的示例；一個使用 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¶
- 屬於 穩定 ABI 的一部分。
一個有符號的整數型別，使得
sizeof(Py_ssize_t) == sizeof(size_t)。C99 沒有直接定義這樣的型別（size_t 是一個無符號整數型別）。有關詳細資訊，請參閱 PEP 353。PY_SSIZE_T_MAX是Py_ssize_t型別可以表示的最大正值。
異常¶
Python 程式設計師只有在需要特定的錯誤處理時才需要處理異常；未處理的異常會自動傳播給呼叫者，然後傳播給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡它們會伴隨著堆疊回溯報告給使用者。
但是，對於 C 程式設計師來說，錯誤檢查始終必須是顯式的。Python/C API 中的所有函式都可以引發異常，除非在函式的文件中明確宣告不是這樣。一般來說，當函式遇到錯誤時，它會設定一個異常，丟棄它擁有的任何物件引用，並返回一個錯誤指示符。如果未另行記錄，則此指示符為 NULL 或 -1，具體取決於函式的返回型別。一些函式返回布林值 true/false 結果，其中 false 表示錯誤。極少數函式不返回顯式錯誤指示符或具有不明確的返回值，並且需要使用 PyErr_Occurred() 進行顯式錯誤測試。這些例外情況始終會明確記錄。
異常狀態在每個執行緒的儲存中維護（這相當於在非執行緒應用程式中使用全域性儲存）。執行緒可以處於兩種狀態之一：已發生異常或未發生異常。函式 PyErr_Occurred() 可用於檢查這一點：當發生異常時，它返回對異常型別物件的借用引用，否則返回 NULL。有許多函式可以設定異常狀態：PyErr_SetString() 是設定異常狀態最常見（但不是最通用）的函式，而 PyErr_Clear() 清除異常狀態。
完整的異常狀態由三個物件組成（所有物件都可以是 NULL）：異常型別、相應的異常值和回溯。它們的含義與 Python 的 sys.exc_info() 的結果相同；但是，它們並不相同：Python 物件表示 Python try … except 語句正在處理的最後一個異常，而 C 級別的異常狀態僅在異常在 C 函式之間傳遞時存在，直到它到達 Python 位元組碼直譯器的主迴圈，後者負責將其傳輸到 sys.exc_info() 及相關函式。
請注意，從 Python 1.5 開始，從 Python 程式碼訪問異常狀態的首選執行緒安全方式是呼叫函式 sys.exc_info()，該函式返回 Python 程式碼的每個執行緒的異常狀態。此外，訪問異常狀態的兩種方式的語義已更改，以便捕獲異常的函式將儲存並恢復其執行緒的異常狀態，從而保留其呼叫者的異常狀態。這可以防止異常處理程式碼中常見的錯誤，這些錯誤是由一個看似無害的函式覆蓋正在處理的異常引起的；它還減少了回溯中堆疊幀引用的物件通常不希望的生命週期延長。
作為一般原則，呼叫另一個函式來執行某些任務的函式應檢查被呼叫函式是否引發了異常，如果是，則將異常狀態傳遞給其呼叫者。它應該丟棄它擁有的任何物件引用，並返回錯誤指示符，但它不應設定另一個異常——這將覆蓋剛剛引發的異常，並丟失有關錯誤確切原因的重要資訊。
上面 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'；當遇到 NULL 引用時，Py_DECREF() 會崩潰）。重要的是，用於儲存擁有的引用的變數要初始化為 NULL 才能使其正常工作；同樣，建議的返回值初始化為 -1 (失敗)，並且僅在最後一次呼叫的成功後才設定為成功。
嵌入 Python¶
Python 直譯器的嵌入者（而不是擴充套件編寫者）需要擔心的一個重要任務是 Python 直譯器的初始化，以及可能的最終確定。只有在初始化直譯器之後，才能使用直譯器的大多數功能。
基本的初始化函式是 Py_Initialize()。這將初始化已載入模組的表，並建立基本模組 builtins、__main__ 和 sys。它還會初始化模組搜尋路徑 (sys.path)。
Py_Initialize() 不設定“指令碼引數列表”(sys.argv)。如果稍後要執行的 Python 程式碼需要此變數，則必須設定 PyConfig.argv 和 PyConfig.parse_argv：請參閱Python 初始化配置。
在大多數系統上（特別是 Unix 和 Windows 上，儘管細節略有不同），Py_Initialize() 根據其對標準 Python 直譯器可執行檔案位置的最佳猜測來計算模組搜尋路徑，假設 Python 庫位於相對於 Python 直譯器可執行檔案的固定位置。特別是，它會在 shell 命令搜尋路徑（環境變數 PATH）上找到名為 python 的可執行檔案的父目錄的相對位置，查詢名為 lib/pythonX.Y 的目錄。
例如，如果 Python 可執行檔案在 /usr/local/bin/python 中找到，它將假定庫在 /usr/local/lib/pythonX.Y 中。（事實上，當在 PATH 上找不到名為 python 的可執行檔案時，也會使用此特定路徑作為“回退”位置。）使用者可以透過設定環境變數 PYTHONHOME 來覆蓋此行為，或者透過設定 PYTHONPATH 在標準路徑前面插入其他目錄。
嵌入應用程式可以透過在呼叫 Py_InitializeFromConfig()之前設定 PyConfig.program_name 來控制搜尋。請注意，PYTHONHOME 仍然會覆蓋此設定，並且 PYTHONPATH 仍然插入在標準路徑之前。需要完全控制的應用程式必須提供 Py_GetPath()、Py_GetPrefix()、Py_GetExecPrefix() 和 Py_GetProgramFullPath() 的自己的實現（所有這些都在 Modules/getpath.c 中定義）。
有時，希望“取消初始化” Python。例如，應用程式可能希望重新開始（再次呼叫 Py_Initialize()）或者應用程式只是完成了對 Python 的使用，並希望釋放 Python 分配的記憶體。這可以透過呼叫 Py_FinalizeEx() 來完成。如果 Python 當前處於初始化狀態，則函式 Py_IsInitialized() 返回 true。有關這些函式的更多資訊將在後面的章節中給出。請注意，Py_FinalizeEx() 不會釋放 Python 直譯器分配的所有記憶體，例如，擴充套件模組分配的記憶體當前無法釋放。
除錯版本¶
可以使用多個宏構建 Python，以啟用對直譯器和擴充套件模組的額外檢查。這些檢查往往會給執行時增加大量的開銷，因此預設情況下不啟用它們。
Python 原始碼分發中的檔案 Misc/SpecialBuilds.txt 中提供了各種型別的除錯版本的完整列表。可以使用支援跟蹤引用計數、除錯記憶體分配器或主直譯器迴圈的低階分析的版本。本節的其餘部分將僅描述最常用的版本。
-
Py_DEBUG¶
使用定義了 Py_DEBUG 宏的直譯器進行編譯，會產生通常所說的 Python 的除錯版本。Py_DEBUG 在 Unix 構建中透過將 --with-pydebug 新增到 ./configure 命令中啟用。它也隱含於非 Python 特定的 _DEBUG 宏的存在。當在 Unix 構建中啟用 Py_DEBUG 時，編譯器最佳化將被停用。
除了下面描述的引用計數除錯之外，還會執行額外的檢查，請參閱 Python 除錯版本。
定義 Py_TRACE_REFS 會啟用引用跟蹤（請參閱 configure --with-trace-refs 選項）。當定義時，透過向每個 PyObject 新增兩個額外欄位，來維護活動物件的迴圈雙向連結串列。還會跟蹤總分配量。退出時，將列印所有現有的引用。（在互動模式下，這會在直譯器執行的每個語句之後發生。）
有關更詳細的資訊，請參閱 Python 原始碼發行版中的 Misc/SpecialBuilds.txt。