### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](stable.xhtml "穩定的應用程序二進制接口") | - [上一頁](index.xhtml "Python/C API 參考手冊") | -  - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python/C API 參考手冊](index.xhtml) ? - $('.inline-search').show(0); | # 概述 Python 的應用編程接口（API）使得 C 和 C++ 程序員可以在多個層級上訪問 Python 解釋器。該 API 在 C++ 中同樣可用，但為簡化描述，通常將其稱為 Python/C API。使用 Python/C API 有兩個基本的理由。第一個理由是為了特定目的而編寫 *擴展模塊*；它們是擴展 Python 解釋器功能的 C 模塊。這可能是最常見的使用場景。第二個理由是將 Python 用作更大規模應用的組件；這種技巧通常被稱為在一個應用中 *embedding* Python。 編寫擴展模塊的過程相對來說更易于理解，可以通過“菜譜”的形式分步驟介紹。使用某些工具可在一定程度上自動化這一過程。雖然人們在其他應用中嵌入 Python 的做法早已有之，但嵌入 Python 的過程沒有編寫擴展模塊那樣方便直觀。 許多 API 函數在你嵌入或是擴展 Python 這兩種場景下都能發揮作用；此外，大多數嵌入 Python 的應用程序也需要提供自定義擴展，因此在嘗試在實際應用中嵌入 Python 之前先熟悉編寫擴展應該會是個好主意。 ## 代碼標準 如果你想要編寫可包含于 CPython 的 C 代碼，你 **必須** 遵循在 [**PEP 7**](https://www.python.org/dev/peps/pep-0007) \[https://www.python.org/dev/peps/pep-0007\] 中定義的指導原則和標準。這些指導原則適用于任何你所要擴展的 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`。 It is recommended to always define `PY_SSIZE_T_CLEAN` before including `Python.h`. See [語句解釋及變量編譯](arg.xhtml#arg-parsing) for a description of this macro. 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` 是向安裝程序指定的安裝目錄。 要包含頭文件，請將兩個目錄（如果不同）都放到你所用編譯器的包含搜索路徑中。請 *不要* 將父目錄放入搜索路徑然后使用 `#include <pythonX.Y/Python.h>`；這將使得多平臺編譯不可用，因為 `prefix` 下平臺無關的頭文件需要包含來自 `exec_prefix` 下特定平臺的頭文件。 C++ 用戶應該注意，盡管 API 是完全使用 C 來定義的，但頭文件正確地將入口點聲明為 `extern "C"`，因此 API 在 C++ 中使用此 API 不必再做任何特殊處理。 ## 有用的宏 Python 頭文件中定義了一些有用的宏。許多是在靠近它們被使用的地方定義的（例如 [`Py_RETURN_NONE`](none.xhtml#c.Py_RETURN_NONE "Py_RETURN_NONE")）。其他更為通用的則定義在這里。這里所顯示的并不是一個完整的列表。 `Py_UNREACHABLE`()這個可以在你有一個不打算被觸及的代碼路徑時使用。例如，當一個 `switch` 語句中所有可能的值都已被 `case` 子句覆蓋了，就可將其用在 `default:` 子句中。當你非常想在某個位置放一個 `assert(0)` 或 `abort()` 調用時也可以用這個。 3\.7 新版功能. `Py_ABS`(x)返回 `x` 的絕對值。 3\.3 新版功能. `Py_MIN`(x, y)返回 `x` 和 `y` 當中的最小值。 3\.3 新版功能. `Py_MAX`(x, y)返回 `x` 和 `y` 當中的最大值。 3\.3 新版功能. `Py_STRINGIFY`(x)將 `x` 轉換為 C 字符串。例如 `Py_STRINGIFY(123)` 返回 `"123"`。 3\.4 新版功能. `Py_MEMBER_SIZE`(type, member)返回結構 (`type`) `member` 的大小，以字節表示。 3\.6 新版功能. `Py_CHARMASK`(c)參數必須為 \[-128, 127\] 或 \[0, 255\] 范圍內的字符或整數類型。這個宏將 `c` 強制轉換為 `unsigned char` 返回。 `Py_GETENV`(s)類似 `getenv(s)` 但會在以下情況返回 *NULL* ：如果通過命令行傳入 [`-E`](../using/cmdline.xhtml#cmdoption-e) （即設置了 `Py_IgnoreEnvironmentFlag` ）。 `Py_UNUSED`(arg)這個可用于函數定義中未使用的參數以隱藏編譯器警告，例如 `PyObject* func(PyObject *Py_UNUSED(ignored))`。 3\.4 新版功能. ## 對象、類型和引用計數 大多數 Python/C API 函數都有一個或多個參數以及一個 [`PyObject*`](structures.xhtml#c.PyObject "PyObject") 類型的返回值。此類型是一個指針，指向表示一個任意 Python 對象的不透明數據類型。由于在大多數情況下（例如賦值、作用域規則和參數傳遞） Python 語言都會以同樣的方式處理所有 Python 對象類型，因此它們由一個單獨的 C 類型來表示是很適宜的。幾乎所有 Python 對象都生存在堆上：你絕不會聲明一個 [`PyObject`](structures.xhtml#c.PyObject "PyObject") 類型的自動或靜態變量，只有 [`PyObject*`](structures.xhtml#c.PyObject "PyObject") 類型的指針變量可以被聲明。唯一的例外是 type 對象；由于此種對象永遠不能被釋放，所以它們通常是靜態 [`PyTypeObject`](type.xhtml#c.PyTypeObject "PyTypeObject") 對象。 所有 Python 對象（甚至 Python 整數）都有一個 *type* 和一個 *reference count*。對象的類型確定它是什么類型的對象（例如整數、列表或用戶定義函數；還有更多，如 [標準類型層級結構](../reference/datamodel.xhtml#types) 中所述）。對于每個眾所周知的類型，都有一個宏來檢查對象是否屬于該類型；例如，當（且僅當） *a* 所指的對象是 Python 列表時 `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 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 an object's reference count becomes zero, the object is deallocated. If it contains references to other objects, their reference count is decremented. Those other objects may be deallocated in turn, if this decrement makes their reference count become zero, 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()`](refcounting.xhtml#c.Py_INCREF "Py_INCREF") to increment an object's reference count by one, and [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "Py_DECREF") to decrement it by one. The [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "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 decrementing the reference counts 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 increment an object's 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 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 incrementing its reference count. Some other operation might conceivably remove the object from the list, decrementing its reference count and possible 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()`](refcounting.xhtml#c.Py_DECREF "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 increment the reference count of the object they return. This leaves the caller with the responsibility to call [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "Py_DECREF") when they are done with the result; this soon becomes second nature. #### Reference Count Details 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 decref'ing it by calling [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "Py_DECREF") or [`Py_XDECREF()`](refcounting.xhtml#c.Py_XDECREF "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. Conversely, when a calling function passes in a reference to an object, there are two possibilities: the function *steals* a reference to the object, or it does not. *Stealing a reference* means that when you pass a reference to a function, that function assumes that it now owns that reference, and you are not responsible for it any longer. Few functions steal references; the two notable exceptions are [`PyList_SetItem()`](list.xhtml#c.PyList_SetItem "PyList_SetItem") and [`PyTuple_SetItem()`](tuple.xhtml#c.PyTuple_SetItem "PyTuple_SetItem"), which steal a reference to the item (but not to the tuple or list into which the item is put!). These functions were designed to steal a reference because of a common idiom for populating a tuple or list with newly created objects; for example, the code to create the tuple `(1, 2, "three")` could look like this (forgetting about error handling for the moment; a better way to code this is shown below): ``` 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")); ``` Here, [`PyLong_FromLong()`](long.xhtml#c.PyLong_FromLong "PyLong_FromLong") returns a new reference which is immediately stolen by [`PyTuple_SetItem()`](tuple.xhtml#c.PyTuple_SetItem "PyTuple_SetItem"). When you want to keep using an object although the reference to it will be stolen, use [`Py_INCREF()`](refcounting.xhtml#c.Py_INCREF "Py_INCREF") to grab another reference before calling the reference-stealing function. Incidentally, [`PyTuple_SetItem()`](tuple.xhtml#c.PyTuple_SetItem "PyTuple_SetItem") is the *only* way to set tuple items; [`PySequence_SetItem()`](sequence.xhtml#c.PySequence_SetItem "PySequence_SetItem") and [`PyObject_SetItem()`](object.xhtml#c.PyObject_SetItem "PyObject_SetItem") refuse to do this since tuples are an immutable data type. You should only use [`PyTuple_SetItem()`](tuple.xhtml#c.PyTuple_SetItem "PyTuple_SetItem") for tuples that you are creating yourself. Equivalent code for populating a list can be written using [`PyList_New()`](list.xhtml#c.PyList_New "PyList_New")and [`PyList_SetItem()`](list.xhtml#c.PyList_SetItem "PyList_SetItem"). However, in practice, you will rarely use these ways of creating and populating a tuple or list. There's a generic function, [`Py_BuildValue()`](arg.xhtml#c.Py_BuildValue "Py_BuildValue"), that can create most common objects from C values, directed by a *format string*. For example, the above two blocks of code could be replaced by the following (which also takes care of the error checking): ``` 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()`](object.xhtml#c.PyObject_SetItem "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 reference counts is much saner, since you don't have to increment a reference count so you can give a 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; } ``` The situation is slightly different for function return values. While passing a reference to most functions does not change your ownership responsibilities for that reference, many functions that return a reference to an object give you ownership of the reference. The reason is simple: in many cases, the returned object is created on the fly, and the reference you get is the only reference to the object. Therefore, the generic functions that return object references, like [`PyObject_GetItem()`](object.xhtml#c.PyObject_GetItem "PyObject_GetItem") and [`PySequence_GetItem()`](sequence.xhtml#c.PySequence_GetItem "PySequence_GetItem"), always return a new reference (the caller becomes the owner of the reference). It is important to realize that whether you own a reference returned by a function depends on which function you call only --- *the plumage* (the type of the object passed as an argument to the function) *doesn't enter into it!*Thus, if you extract an item from a list using [`PyList_GetItem()`](list.xhtml#c.PyList_GetItem "PyList_GetItem"), you don't own the reference --- but if you obtain the same item from the same list using [`PySequence_GetItem()`](sequence.xhtml#c.PySequence_GetItem "PySequence_GetItem") (which happens to take exactly the same arguments), you do own a reference to the returned object. Here is an example of how you could write a function that computes the sum of the items in a list of integers; once using [`PyList_GetItem()`](list.xhtml#c.PyList_GetItem "PyList_GetItem"), and once using [`PySequence_GetItem()`](sequence.xhtml#c.PySequence_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; } ``` ### 類型 There are few other data types that play a significant role in the Python/C API; most are simple C types such as `int`, `long`, `double` and `char*`. A few structure types are used to describe static tables used to list the functions exported by a module or the data attributes of a new object type, and another is used to describe the value of a complex number. These will be discussed together with the functions that use them. ## 異常 Python程序員只需要處理特定需要處理的錯誤異常；未處理的異常會自動傳遞給調用者，然后傳遞給調用者的調用者，依此類推，直到他們到達頂級解釋器，在那里將它們報告給用戶并伴隨堆棧回溯。 For C programmers, however, error checking always has to be explicit. All functions in the Python/C API can raise exceptions, unless an explicit claim is made otherwise in a function's documentation. In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns an error indicator. If not documented otherwise, this indicator is either *NULL* or `-1`, depending on the function's return type. A few functions return a Boolean true/false result, with false indicating an error. Very few functions return no explicit error indicator or have an ambiguous return value, and require explicit testing for errors with [`PyErr_Occurred()`](exceptions.xhtml#c.PyErr_Occurred "PyErr_Occurred"). These exceptions are always explicitly documented. Exception state is maintained in per-thread storage (this is equivalent to using global storage in an unthreaded application). A thread can be in one of two states: an exception has occurred, or not. The function [`PyErr_Occurred()`](exceptions.xhtml#c.PyErr_Occurred "PyErr_Occurred") can be used to check for this: it returns a borrowed reference to the exception type object when an exception has occurred, and *NULL* otherwise. There are a number of functions to set the exception state: [`PyErr_SetString()`](exceptions.xhtml#c.PyErr_SetString "PyErr_SetString") is the most common (though not the most general) function to set the exception state, and [`PyErr_Clear()`](exceptions.xhtml#c.PyErr_Clear "PyErr_Clear") clears the exception state. The full exception state consists of three objects (all of which can be *NULL*): the exception type, the corresponding exception value, and the traceback. These have the same meanings as the Python result of `sys.exc_info()`; however, they are not the same: the Python objects represent the last exception being handled by a Python [`try`](../reference/compound_stmts.xhtml#try) ... [`except`](../reference/compound_stmts.xhtml#except) statement, while the C level exception state only exists while an exception is being passed on between C functions until it reaches the Python bytecode interpreter's main loop, which takes care of transferring it to `sys.exc_info()` and friends. Note that starting with Python 1.5, the preferred, thread-safe way to access the exception state from Python code is to call the function [`sys.exc_info()`](../library/sys.xhtml#sys.exc_info "sys.exc_info"), which returns the per-thread exception state for Python code. Also, the semantics of both ways to access the exception state have changed so that a function which catches an exception will save and restore its thread's exception state so as to preserve the exception state of its caller. This prevents common bugs in exception handling code caused by an innocent-looking function overwriting the exception being handled; it also reduces the often unwanted lifetime extension for objects that are referenced by the stack frames in the traceback. As a general principle, a function that calls another function to perform some task should check whether the called function raised an exception, and if so, pass the exception state on to its caller. It should discard any object references that it owns, and return an error indicator, but it should *not* set another exception --- that would overwrite the exception that was just raised, and lose important information about the exact cause of the error. 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 ``` Here is the corresponding C code, in all its glory: ``` 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 */ } ``` This example represents an endorsed use of the `goto` statement in C! It illustrates the use of [`PyErr_ExceptionMatches()`](exceptions.xhtml#c.PyErr_ExceptionMatches "PyErr_ExceptionMatches") and [`PyErr_Clear()`](exceptions.xhtml#c.PyErr_Clear "PyErr_Clear") to handle specific exceptions, and the use of [`Py_XDECREF()`](refcounting.xhtml#c.Py_XDECREF "Py_XDECREF") to dispose of owned references that may be *NULL* (note the `'X'` in the name; [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "Py_DECREF") would crash when confronted with a *NULL* reference). It is important that the variables used to hold owned references are initialized to *NULL* for this to work; likewise, the proposed return value is initialized to `-1` (failure) and only set to success after the final call made is successful. ## 嵌入Python The one important task that only embedders (as opposed to extension writers) of the Python interpreter have to worry about is the initialization, and possibly the finalization, of the Python interpreter. Most functionality of the interpreter can only be used after the interpreter has been initialized. The basic initialization function is [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize"). This initializes the table of loaded modules, and creates the fundamental modules [`builtins`](../library/builtins.xhtml#module-builtins "builtins: The module that provides the built-in namespace."), [`__main__`](../library/__main__.xhtml#module-__main__ "__main__: The environment where the top-level script is run."), and [`sys`](../library/sys.xhtml#module-sys "sys: Access system-specific parameters and functions."). It also initializes the module search path (`sys.path`). [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize") does not set the "script argument list" (`sys.argv`). If this variable is needed by Python code that will be executed later, it must be set explicitly with a call to `PySys_SetArgvEx(argc, argv, updatepath)`after the call to [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize"). On most systems (in particular, on Unix and Windows, although the details are slightly different), [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize") calculates the module search path based upon its best guess for the location of the standard Python interpreter executable, assuming that the Python library is found in a fixed location relative to the Python interpreter executable. In particular, it looks for a directory named `lib/pythonX.Y` relative to the parent directory where the executable named `python` is found on the shell command search path (the environment variable `PATH`). For instance, if the Python executable is found in `/usr/local/bin/python`, it will assume that the libraries are in `/usr/local/lib/pythonX.Y`. (In fact, this particular path is also the "fallback" location, used when no executable file named `python` is found along `PATH`.) The user can override this behavior by setting the environment variable [`PYTHONHOME`](../using/cmdline.xhtml#envvar-PYTHONHOME), or insert additional directories in front of the standard path by setting [`PYTHONPATH`](../using/cmdline.xhtml#envvar-PYTHONPATH). The embedding application can steer the search by calling `Py_SetProgramName(file)` *before* calling [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize"). Note that [`PYTHONHOME`](../using/cmdline.xhtml#envvar-PYTHONHOME) still overrides this and [`PYTHONPATH`](../using/cmdline.xhtml#envvar-PYTHONPATH) is still inserted in front of the standard path. An application that requires total control has to provide its own implementation of [`Py_GetPath()`](init.xhtml#c.Py_GetPath "Py_GetPath"), [`Py_GetPrefix()`](init.xhtml#c.Py_GetPrefix "Py_GetPrefix"), [`Py_GetExecPrefix()`](init.xhtml#c.Py_GetExecPrefix "Py_GetExecPrefix"), and [`Py_GetProgramFullPath()`](init.xhtml#c.Py_GetProgramFullPath "Py_GetProgramFullPath") (all defined in `Modules/getpath.c`). Sometimes, it is desirable to "uninitialize" Python. For instance, the application may want to start over (make another call to [`Py_Initialize()`](init.xhtml#c.Py_Initialize "Py_Initialize")) or the application is simply done with its use of Python and wants to free memory allocated by Python. This can be accomplished by calling [`Py_FinalizeEx()`](init.xhtml#c.Py_FinalizeEx "Py_FinalizeEx"). The function [`Py_IsInitialized()`](init.xhtml#c.Py_IsInitialized "Py_IsInitialized") returns true if Python is currently in the initialized state. More information about these functions is given in a later chapter. Notice that [`Py_FinalizeEx()`](init.xhtml#c.Py_FinalizeEx "Py_FinalizeEx")does *not* free all memory allocated by the Python interpreter, e.g. memory allocated by extension modules currently cannot be released. ## 調試構建 Python can be built with several macros to enable extra checks of the interpreter and extension modules. These checks tend to add a large amount of overhead to the runtime so they are not enabled by default. A full list of the various types of debugging builds is in the file `Misc/SpecialBuilds.txt` in the Python source distribution. Builds are available that support tracing of reference counts, debugging the memory allocator, or low-level profiling of the main interpreter loop. Only the most frequently-used builds will be described in the remainder of this section. 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. 除了前面描述的引用計數調試之外，還執行以下額外檢查： - 額外檢查將添加到對象分配器。 - 額外的檢查將添加到解析器和編譯器中。 - Downcasts from wide types to narrow types are checked for loss of information. - 許多斷言被添加到字典和集合實現中。另外，集合對象需要 `test_c_api()` 方法。 - 輸入參數的完整性檢查被添加到框架創建中。 - 使用已知的無效模式初始化整型的存儲，以捕獲對未初始化數字的引用。 - 添加底層跟蹤和額外的異常檢查到虛擬機的運行時中。 - Extra checks are added to the memory arena implementation. - 添加額外調試到線程模塊。 這里可能沒有提到的額外的檢查。 Defining `Py_TRACE_REFS` enables reference tracing. When defined, a circular doubly linked list of active objects is maintained by adding two extra fields to every [`PyObject`](structures.xhtml#c.PyObject "PyObject"). Total allocations are tracked as well. Upon exit, all existing references are printed. (In interactive mode this happens after every statement run by the interpreter.) Implied by `Py_DEBUG`. 有關更多詳細信息，請參閱Python源代碼中的 `Misc/SpecialBuilds.txt` 。 ### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](stable.xhtml "穩定的應用程序二進制接口") | - [上一頁](index.xhtml "Python/C API 參考手冊") | -  - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python/C API 參考手冊](index.xhtml) ? - $('.inline-search').show(0); | ? [版權所有](../copyright.xhtml) 2001-2019, Python Software Foundation. Python 軟件基金會是一個非盈利組織。 [請捐助。](https://www.python.org/psf/donations/) 最后更新于 5月 21, 2019. [發現了問題](../bugs.xhtml)？ 使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 創建。