Đối tượng mô-đun¶

PyTypeObject PyModule_Type¶: Một phần của ABI ổn định.
Phiên bản PyTypeObject này đại diện cho loại mô-đun Python. Điều này được hiển thị với các chương trình Python dưới dạng types.ModuleType.

int PyModule_Check(PyObject *p)¶: Trả về true nếu p là đối tượng mô-đun hoặc kiểu con của đối tượng mô-đun. Chức năng này luôn thành công.

int PyModule_CheckExact(PyObject *p)¶: Trả về true nếu p là đối tượng mô-đun chứ không phải là kiểu con của PyModule_Type. Chức năng này luôn thành công.

PyObject *PyModule_NewObject(PyObject *name)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.

Trả về một đối tượng mô-đun mới với module.__name__ được đặt thành name. Các thuộc tính __name__, __doc__, __package__ và __loader__ của mô-đun được điền vào (tất cả trừ __name__ được đặt thành None). Người gọi có trách nhiệm thiết lập thuộc tính __file__.

Trả về NULL với lỗi ngoại lệ được đặt.

Added in version 3.3.

Thay đổi trong phiên bản 3.4: __package__ và __loader__ hiện được đặt thành None.

PyObject *PyModule_New(const char *name)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tương tự như PyModule_NewObject(), nhưng tên là chuỗi được mã hóa UTF-8 thay vì đối tượng Unicode.

PyObject *PyModule_GetDict(PyObject *module)¶

Giá trị trả về: Tham chiếu mượn. Một phần của ABI ổn định.

Trả về đối tượng từ điển triển khai không gian tên của module; đối tượng này giống với thuộc tính __dict__ của đối tượng mô-đun. Nếu module không phải là đối tượng mô-đun (hoặc kiểu con của đối tượng mô-đun), SystemError được nâng lên và NULL được trả về.

Các tiện ích mở rộng nên sử dụng các hàm PyModule_* và PyObject_* khác thay vì thao tác trực tiếp với __dict__ của mô-đun.

Tham chiếu trả về được mượn từ mô-đun; nó có hiệu lực cho đến khi mô-đun bị phá hủy.

PyObject *PyModule_GetNameObject(PyObject *module)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.
Trả về giá trị __name__ của module. Nếu mô-đun không cung cấp hoặc nếu nó không phải là một chuỗi thì SystemError sẽ được nâng lên và NULL sẽ được trả về.

Added in version 3.3.

const char *PyModule_GetName(PyObject *module)¶

Một phần của ABI ổn định.

Tương tự như PyModule_GetNameObject() nhưng trả về tên được mã hóa thành 'utf-8'.

Bộ đệm được trả về chỉ có hiệu lực cho đến khi mô-đun được đổi tên hoặc hủy. Lưu ý rằng mã Python có thể đổi tên mô-đun bằng cách đặt thuộc tính __name__ của nó.

void *PyModule_GetState(PyObject *module)¶: Một phần của ABI ổn định.
Trả về "trạng thái" của mô-đun, nghĩa là một con trỏ tới khối bộ nhớ được phân bổ tại thời điểm tạo mô-đun hoặc NULL. Xem PyModuleDef.m_size.

PyModuleDef *PyModule_GetDef(PyObject *module)¶

Một phần của ABI ổn định.

Trả về một con trỏ tới cấu trúc PyModuleDef mà mô-đun được tạo từ đó hoặc NULL nếu mô-đun không được tạo từ một định nghĩa.

Nếu có lỗi, hãy trả về NULL với một bộ ngoại lệ. Sử dụng PyErr_Occurred() để phân biệt trường hợp này với PyModuleDef bị thiếu.

PyObject *PyModule_GetFilenameObject(PyObject *module)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về tên của tệp mà module được tải bằng thuộc tính __file__ của module. Nếu điều này không được xác định hoặc nếu nó không phải là một chuỗi, hãy tăng SystemError và trả về NULL; mặt khác trả về một tham chiếu đến một đối tượng Unicode.

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)¶

Một phần của ABI ổn định.

Tương tự như PyModule_GetFilenameObject() nhưng trả về tên tệp được mã hóa thành 'utf-8'.

Bộ đệm được trả về chỉ hợp lệ cho đến khi thuộc tính __file__ của mô-đun được gán lại hoặc mô-đun bị hủy.

Sắp loại bỏ từ phiên bản 3.2: PyModule_GetFilename() tăng UnicodeEncodeError trên tên tệp không thể mã hóa, thay vào đó hãy sử dụng PyModule_GetFilenameObject().

Định nghĩa mô-đun¶

Các hàm trong phần trước hoạt động trên mọi đối tượng mô-đun, bao gồm cả các mô-đun được nhập từ mã Python.

Các mô-đun được xác định bằng C API thường sử dụng module definition, PyModuleDef -- một "mô tả" không đổi, được phân bổ tĩnh về cách tạo một mô-đun.

Định nghĩa này thường được sử dụng để xác định đối tượng mô-đun “chính” của tiện ích mở rộng (xem Xác định các mô-đun mở rộng để biết chi tiết). Nó cũng quen với create extension modules dynamically.

Không giống như PyModule_New(), định nghĩa này cho phép quản lý module state -- một phần bộ nhớ được phân bổ và xóa cùng với đối tượng mô-đun. Không giống như các thuộc tính Python của mô-đun, mã Python không thể thay thế hoặc xóa dữ liệu được lưu trữ ở trạng thái mô-đun.

type PyModuleDef¶

Một phần của ABI ổn định (bao gồm tất cả các thành viên).

Cấu trúc định nghĩa mô-đun chứa tất cả thông tin cần thiết để tạo một đối tượng mô-đun. Cấu trúc này phải được phân bổ tĩnh (hoặc được đảm bảo hợp lệ trong khi mọi mô-đun được tạo từ nó tồn tại). Thông thường, chỉ có một biến kiểu này cho mỗi mô-đun mở rộng.

PyModuleDef_Base m_base¶: Luôn khởi tạo thành viên này thành PyModuleDef_HEAD_INIT.

const char *m_name¶: Tên cho mô-đun mới.

const char *m_doc¶: Chuỗi tài liệu cho mô-đun; thường sử dụng biến chuỗi tài liệu được tạo bằng PyDoc_STRVAR.

Py_ssize_t m_size¶

Trạng thái mô-đun có thể được lưu giữ trong vùng bộ nhớ trên mỗi mô-đun có thể được truy xuất bằng PyModule_GetState(), thay vì ở dạng toàn cục tĩnh. Điều này làm cho các mô-đun trở nên an toàn khi sử dụng trong nhiều trình thông dịch phụ.

Vùng bộ nhớ này được phân bổ dựa trên m_size khi tạo mô-đun và được giải phóng khi đối tượng mô-đun được giải phóng, sau khi hàm m_free được gọi, nếu có.

Đặt nó thành giá trị không âm có nghĩa là mô-đun có thể được khởi tạo lại và chỉ định lượng bộ nhớ bổ sung mà nó yêu cầu cho trạng thái của nó.

Đặt m_size thành -1 có nghĩa là mô-đun không hỗ trợ trình thông dịch phụ vì nó có trạng thái chung. m_size âm chỉ được phép khi sử dụng legacy single-phase initialization hoặc khi creating modules dynamically.

Xem PEP 3121 để biết thêm chi tiết.

PyMethodDef *m_methods¶: Một con trỏ tới một bảng các hàm cấp mô-đun, được mô tả bằng các giá trị PyMethodDef. Có thể là NULL nếu không có chức năng nào.

PyModuleDef_Slot *m_slots¶

Một mảng các định nghĩa vị trí để khởi tạo nhiều pha, được kết thúc bằng mục nhập {0, NULL}. Khi sử dụng khởi tạo một pha cũ, m_slots phải là NULL.

Thay đổi trong phiên bản 3.5: Trước phiên bản 3.5, thành viên này luôn được đặt thành NULL và được xác định là:

inquiry m_reload¶

traverseproc m_traverse¶

Một hàm truyền tải để gọi trong quá trình truyền tải GC của đối tượng mô-đun hoặc NULL nếu không cần thiết.

Hàm này không được gọi nếu trạng thái mô-đun được yêu cầu nhưng chưa được phân bổ. Đây là trường hợp ngay sau khi mô-đun được tạo và trước khi mô-đun được thực thi (chức năng Py_mod_exec). Chính xác hơn, hàm này không được gọi nếu m_size lớn hơn 0 và trạng thái mô-đun (được trả về bởi PyModule_GetState()) là NULL.

Thay đổi trong phiên bản 3.9: Không còn được gọi trước khi trạng thái mô-đun được phân bổ.

inquiry m_clear¶

Một hàm rõ ràng để gọi trong quá trình xóa GC của đối tượng mô-đun hoặc NULL nếu không cần thiết.

Hàm này không được gọi nếu trạng thái mô-đun được yêu cầu nhưng chưa được phân bổ. Đây là trường hợp ngay sau khi mô-đun được tạo và trước khi mô-đun được thực thi (chức năng Py_mod_exec). Chính xác hơn, hàm này không được gọi nếu m_size lớn hơn 0 và trạng thái mô-đun (được trả về bởi PyModule_GetState()) là NULL.

Giống như PyTypeObject.tp_clear, hàm này không được gọi always trước khi mô-đun bị hủy phân bổ. Ví dụ: khi việc đếm tham chiếu đủ để xác định rằng một đối tượng không còn được sử dụng nữa, trình thu gom rác tuần hoàn không liên quan và m_free được gọi trực tiếp.

Thay đổi trong phiên bản 3.9: Không còn được gọi trước khi trạng thái mô-đun được phân bổ.

freefunc m_free¶

Một hàm để gọi trong quá trình phân bổ lại đối tượng mô-đun hoặc NULL nếu không cần thiết.

Hàm này không được gọi nếu trạng thái mô-đun được yêu cầu nhưng chưa được phân bổ. Đây là trường hợp ngay sau khi mô-đun được tạo và trước khi mô-đun được thực thi (chức năng Py_mod_exec). Chính xác hơn, hàm này không được gọi nếu m_size lớn hơn 0 và trạng thái mô-đun (được trả về bởi PyModule_GetState()) là NULL.

Thay đổi trong phiên bản 3.9: Không còn được gọi trước khi trạng thái mô-đun được phân bổ.

PyTypeObject PyModuleDef_Type¶: Một phần của ABI ổn định kể từ phiên bản 3.5.
Loại đối tượng PyModuleDef.

Khe cắm mô-đun¶

type PyModuleDef_Slot¶

Một phần của ABI ổn định (bao gồm tất cả các thành viên) kể từ phiên bản 3.5.

int slot¶: ID vị trí, được chọn từ các giá trị có sẵn được giải thích bên dưới.

void *value¶: Giá trị của vị trí, ý nghĩa của nó phụ thuộc vào ID vị trí.

Added in version 3.5.

Các loại vị trí có sẵn là:

Py_mod_create¶

Một phần của ABI ổn định kể từ phiên bản 3.5.

Chỉ định một hàm được gọi để tạo chính đối tượng mô-đun. Con trỏ value của khe này phải trỏ đến chức năng của chữ ký:

PyObject *create_module(PyObject *spec, PyModuleDef *def)¶

Hàm nhận được một phiên bản ModuleSpec, như được định nghĩa trong PEP 451 và định nghĩa mô-đun. Nó sẽ trả về một đối tượng mô-đun mới hoặc đặt lỗi và trả về NULL.

Chức năng này nên được giữ ở mức tối thiểu. Đặc biệt, nó không nên gọi mã Python tùy ý, vì việc cố gắng nhập lại cùng một mô-đun có thể dẫn đến một vòng lặp vô hạn.

Nhiều khe Py_mod_create có thể không được chỉ định trong một định nghĩa mô-đun.

Nếu Py_mod_create không được chỉ định, máy nhập sẽ tạo một đối tượng mô-đun bình thường bằng PyModule_New(). Tên được lấy từ spec, không phải định nghĩa, để cho phép các mô-đun mở rộng tự động điều chỉnh vị trí của chúng trong hệ thống phân cấp mô-đun và được nhập dưới các tên khác nhau thông qua các liên kết tượng trưng, tất cả trong khi chia sẻ một định nghĩa mô-đun duy nhất.

Không có yêu cầu đối tượng trả về phải là phiên bản của PyModule_Type. Bất kỳ loại nào cũng có thể được sử dụng, miễn là nó hỗ trợ cài đặt và nhận các thuộc tính liên quan đến nhập. Tuy nhiên, chỉ có thể trả về các phiên bản PyModule_Type nếu PyModuleDef không có NULL m_traverse, m_clear, m_free; khác không m_size; hoặc các khe khác ngoài Py_mod_create.

Added in version 3.5.

Py_mod_exec¶

Một phần của ABI ổn định kể từ phiên bản 3.5.

Chỉ định một hàm được gọi tới execute mô-đun. Điều này tương đương với việc thực thi mã của mô-đun Python: thông thường, hàm này thêm các lớp và hằng số vào mô-đun. Chữ ký của hàm là:

int exec_module(PyObject *module)¶

Nếu nhiều vị trí Py_mod_exec được chỉ định, chúng sẽ được xử lý theo thứ tự xuất hiện trong mảng m_slots.

Added in version 3.5.

Py_mod_multiple_interpreters¶

Một phần của ABI ổn định kể từ phiên bản 3.12.

Chỉ định một trong các giá trị sau:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶: Mô-đun này không hỗ trợ nhập vào trình thông dịch phụ.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶: Mô-đun này hỗ trợ nhập vào các trình thông dịch phụ, nhưng chỉ khi chúng chia sẻ GIL của trình thông dịch chính. (Xem Cách ly các mô-đun mở rộng.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶: Mô-đun này hỗ trợ nhập vào các trình thông dịch phụ, ngay cả khi chúng có GIL riêng. (Xem Cách ly các mô-đun mở rộng.)

Khe này xác định xem việc nhập mô-đun này vào trình thông dịch phụ có thất bại hay không.

Nhiều khe Py_mod_multiple_interpreters có thể không được chỉ định trong một định nghĩa mô-đun.

Nếu Py_mod_multiple_interpreters không được chỉ định, máy nhập sẽ mặc định là Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED.

Added in version 3.12.

Py_mod_gil¶

Một phần của ABI ổn định kể từ phiên bản 3.13.

Chỉ định một trong các giá trị sau:

Py_MOD_GIL_USED¶: Mô-đun này phụ thuộc vào sự hiện diện của khóa trình thông dịch chung (GIL) và có thể truy cập trạng thái chung mà không cần đồng bộ hóa.

Py_MOD_GIL_NOT_USED¶: Mô-đun này có thể chạy an toàn mà không cần GIL hoạt động.

Khe này bị bỏ qua bởi các bản dựng Python không được định cấu hình bằng --disable-gil. Mặt khác, nó sẽ xác định xem việc nhập mô-đun này có khiến GIL được bật tự động hay không. Xem CPython có luồng miễn phí để biết thêm chi tiết.

Nhiều khe Py_mod_gil có thể không được chỉ định trong một định nghĩa mô-đun.

Nếu Py_mod_gil không được chỉ định, máy nhập sẽ mặc định là Py_MOD_GIL_USED.

Added in version 3.13.

Tạo mô-đun mở rộng một cách linh hoạt¶

Các chức năng sau có thể được sử dụng để tạo mô-đun bên ngoài initialization function của tiện ích mở rộng. Chúng cũng được sử dụng trong single-phase initialization.

PyObject *PyModule_Create(PyModuleDef *def)¶: Giá trị trả về: Tham chiếu mới.
Tạo một đối tượng mô-đun mới, được định nghĩa trong def. Đây là macro gọi PyModule_Create2() với module_api_version được đặt thành PYTHON_API_VERSION hoặc PYTHON_ABI_VERSION nếu sử dụng limited API.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Tạo một đối tượng mô-đun mới, được định nghĩa trong def, giả sử phiên bản API module_api_version. Nếu phiên bản đó không khớp với phiên bản của trình thông dịch đang chạy thì RuntimeWarning sẽ được phát ra.

Trả về NULL với lỗi ngoại lệ được đặt.

Chức năng này không hỗ trợ khe cắm. Thành viên m_slots của def phải là NULL.

Ghi chú

Thay vào đó, hầu hết các ứng dụng của chức năng này nên sử dụng PyModule_Create(); chỉ sử dụng điều này nếu bạn chắc chắn rằng bạn cần nó.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: Giá trị trả về: Tham chiếu mới.
Macro này gọi PyModule_FromDefAndSpec2() với module_api_version được đặt thành PYTHON_API_VERSION hoặc PYTHON_ABI_VERSION nếu sử dụng limited API.

Added in version 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.

Tạo một đối tượng mô-đun mới, được định nghĩa trong def và ModuleSpec spec, giả sử phiên bản API module_api_version. Nếu phiên bản đó không khớp với phiên bản của trình thông dịch đang chạy thì RuntimeWarning sẽ được phát ra.

Trả về NULL với lỗi ngoại lệ được đặt.

Lưu ý rằng điều này không xử lý các khe thực thi (Py_mod_exec). Cả PyModule_FromDefAndSpec và PyModule_ExecDef đều phải được gọi để khởi tạo đầy đủ mô-đun.

Ghi chú

Thay vào đó, hầu hết các ứng dụng của chức năng này nên sử dụng PyModule_FromDefAndSpec(); chỉ sử dụng điều này nếu bạn chắc chắn rằng bạn cần nó.

Added in version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: Một phần của ABI ổn định kể từ phiên bản 3.7.
Xử lý mọi vị trí thực thi (Py_mod_exec) được cung cấp trong def.

Added in version 3.5.

PYTHON_API_VERSION¶

Phiên bản C API. Được xác định để tương thích ngược.

Hiện tại, hằng số này không được cập nhật trong các phiên bản Python mới và không hữu ích cho việc lập phiên bản. Điều này có thể thay đổi trong tương lai.

PYTHON_ABI_VERSION¶

Được xác định là 3 để tương thích ngược.

Hiện tại, hằng số này không được cập nhật trong các phiên bản Python mới và không hữu ích cho việc lập phiên bản. Điều này có thể thay đổi trong tương lai.

Chức năng hỗ trợ¶

Các chức năng sau đây được cung cấp để giúp khởi tạo trạng thái mô-đun. Chúng dành cho các khe thực thi của mô-đun (Py_mod_exec), chức năng khởi tạo cho single-phase initialization kế thừa hoặc mã tạo mô-đun động.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)¶

Một phần của ABI ổn định kể từ phiên bản 3.10.

Thêm một đối tượng vào module dưới dạng name. Đây là một chức năng tiện lợi có thể được sử dụng từ chức năng khởi tạo của mô-đun.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đưa ra một ngoại lệ và trả về -1.

Ví dụ sử dụng:

int tĩnh
add_spam(mô-đun PyObject *, giá trị int)
{
    PyObject *obj = PyLong_FromLong(giá trị);
    nếu (obj == NULL) {
        trả về -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    trả lại độ phân giải;
 }

Để thuận tiện, hàm này chấp nhận NULL value với một bộ ngoại lệ. Trong trường hợp này, hãy trả về -1 và chỉ giữ nguyên ngoại lệ đã nêu.

Ví dụ này cũng có thể được viết mà không cần kiểm tra rõ ràng xem obj có phải là NULL:

int tĩnh
add_spam(mô-đun PyObject *, giá trị int)
{
    PyObject *obj = PyLong_FromLong(giá trị);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    trả lại độ phân giải;
 }

Lưu ý rằng Py_XDECREF() nên được sử dụng thay vì Py_DECREF() trong trường hợp này, vì obj có thể là NULL.

Số lượng chuỗi name khác nhau được truyền cho hàm này phải được giữ ở mức nhỏ, thường chỉ bằng cách sử dụng các chuỗi được phân bổ tĩnh như name. Đối với những tên không được biết đến tại thời điểm biên dịch, hãy gọi trực tiếp PyUnicode_FromString() và PyObject_SetAttr(). Để biết thêm chi tiết, hãy xem PyUnicode_InternFromString(), có thể được sử dụng nội bộ để tạo đối tượng chính.

Added in version 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)¶

Một phần của ABI ổn định kể từ phiên bản 3.13.

Tương tự như PyModule_AddObjectRef(), nhưng "đánh cắp" một tham chiếu đến value. Nó có thể được gọi với kết quả của hàm trả về một tham chiếu mới mà không cần kiểm tra kết quả của nó hoặc thậm chí lưu nó vào một biến.

Ví dụ sử dụng:

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    lỗi đi đến;
}

Added in version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)¶

Một phần của ABI ổn định.

Tương tự như PyModule_AddObjectRef(), nhưng đánh cắp một tham chiếu đến value khi thành công (nếu nó trả về 0).

Nên sử dụng các hàm PyModule_Add() hoặc PyModule_AddObjectRef() mới vì rất dễ gây rò rỉ tham chiếu bằng cách sử dụng sai chức năng PyModule_AddObject().

Ghi chú

Không giống như các hàm lấy cắp tham chiếu khác, PyModule_AddObject() chỉ phát hành tham chiếu tới value on success.

Điều này có nghĩa là giá trị trả về của nó phải được kiểm tra và mã gọi phải Py_XDECREF() value do lỗi thủ công.

Ví dụ sử dụng:

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(mô-đun, "thư rác", obj) < 0) {
    // Nếu 'obj' không phải là NULL và PyModule_AddObject() không thành công,
    // Tham chiếu mạnh 'obj' phải được xóa bằng Py_XDECREF().
    // Nếu 'obj' là NULL, Py_XDECREF() sẽ không làm gì cả.
    Py_XDECREF(obj);
    lỗi đi đến;
}
// PyModule_AddObject() đã đánh cắp một tham chiếu tới obj:
// Py_XDECREF(obj) không cần thiết ở đây.

Sắp loại bỏ từ phiên bản 3.13: PyModule_AddObject() là soft deprecated.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶

Một phần của ABI ổn định.

Thêm một hằng số nguyên vào module dưới dạng name. Chức năng tiện lợi này có thể được sử dụng từ chức năng khởi tạo của mô-đun. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Đây là một chức năng tiện lợi gọi PyLong_FromLong() và PyModule_AddObjectRef(); xem tài liệu của họ để biết chi tiết.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶

Một phần của ABI ổn định.

Thêm hằng số chuỗi vào module dưới dạng name. Chức năng tiện lợi này có thể được sử dụng từ chức năng khởi tạo của mô-đun. Chuỗi value phải được kết thúc bằng NULL. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Đây là một chức năng tiện lợi gọi PyUnicode_InternFromString() và PyModule_AddObjectRef(); xem tài liệu của họ để biết chi tiết.

PyModule_AddIntMacro(module, macro)¶: Thêm hằng số int vào module. Tên và giá trị được lấy từ macro. Ví dụ: PyModule_AddIntMacro(module, AF_INET) thêm hằng số int AF_INET với giá trị AF_INET vào module. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

PyModule_AddStringMacro(module, macro)¶: Thêm hằng số chuỗi vào module.

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶: Một phần của ABI ổn định kể từ phiên bản 3.10.
Thêm một đối tượng loại vào module. Đối tượng loại được hoàn thiện bằng cách gọi nội bộ PyType_Ready(). Tên của đối tượng loại được lấy từ thành phần cuối cùng của tp_name sau dấu chấm. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Added in version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶

Một phần của ABI ổn định kể từ phiên bản 3.7.

Thêm các hàm từ mảng functions đã kết thúc NULL vào module. Tham khảo tài liệu PyMethodDef để biết chi tiết về từng mục nhập (do thiếu không gian tên mô-đun dùng chung, các "hàm" cấp mô-đun được triển khai trong C thường nhận mô-đun làm tham số đầu tiên, khiến chúng giống với các phương thức phiên bản trên các lớp Python).

Hàm này được gọi tự động khi tạo mô-đun từ PyModuleDef (chẳng hạn như khi sử dụng Khởi tạo nhiều pha, PyModule_Create hoặc PyModule_FromDefAndSpec). Một số tác giả mô-đun có thể thích xác định các hàm trong nhiều mảng PyMethodDef; trong trường hợp đó họ nên gọi trực tiếp hàm này.

Mảng functions phải được phân bổ tĩnh (hoặc được đảm bảo tồn tại lâu hơn đối tượng mô-đun).

Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)¶

Một phần của ABI ổn định kể từ phiên bản 3.7.

Đặt chuỗi tài liệu cho module thành docstring. Hàm này được gọi tự động khi tạo mô-đun từ PyModuleDef (chẳng hạn như khi sử dụng Khởi tạo nhiều pha, PyModule_Create hoặc PyModule_FromDefAndSpec).

Trả về 0 khi thành công. Trả về -1 với lỗi ngoại lệ được đặt.

Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶: Đây là API không ổn định. Nó có thể thay đổi mà không có cảnh báo trong các bản phát hành nhỏ.

Cho biết rằng module có hoặc không hỗ trợ chạy mà không có khóa trình thông dịch chung (GIL), sử dụng một trong các giá trị từ Py_mod_gil. Nó phải được gọi trong chức năng khởi tạo của module khi sử dụng Khởi tạo một pha kế thừa. Nếu chức năng này không được gọi trong quá trình khởi tạo mô-đun, máy nhập sẽ giả định rằng mô-đun không hỗ trợ chạy mà không có GIL. Chức năng này chỉ khả dụng trong các bản dựng Python được định cấu hình bằng --disable-gil. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Added in version 3.13.

Tra cứu mô-đun (khởi tạo một pha)¶

Sơ đồ khởi tạo single-phase initialization kế thừa tạo ra các mô-đun đơn lẻ có thể tra cứu trong ngữ cảnh của trình thông dịch hiện tại. Điều này cho phép truy xuất đối tượng mô-đun sau này chỉ với tham chiếu đến định nghĩa mô-đun.

Các chức năng này sẽ không hoạt động trên các mô-đun được tạo bằng cách khởi tạo nhiều giai đoạn, vì nhiều mô-đun như vậy có thể được tạo từ một định nghĩa duy nhất.

PyObject *PyState_FindModule(PyModuleDef *def)¶: Giá trị trả về: Tham chiếu mượn. Một phần của ABI ổn định.
Trả về đối tượng mô-đun được tạo từ def cho trình thông dịch hiện tại. Phương thức này yêu cầu đối tượng mô-đun đã được gắn trước vào trạng thái trình thông dịch với PyState_AddModule(). Trong trường hợp không tìm thấy đối tượng mô-đun tương ứng hoặc chưa được gắn vào trạng thái trình thông dịch, nó sẽ trả về NULL.

int PyState_AddModule(PyObject *module, PyModuleDef *def)¶

Một phần của ABI ổn định kể từ phiên bản 3.3.

Gắn đối tượng mô-đun được truyền vào hàm vào trạng thái trình thông dịch. Điều này cho phép đối tượng mô-đun có thể truy cập được thông qua PyState_FindModule().

Chỉ có hiệu lực trên các mô-đun được tạo bằng cách khởi tạo một pha.

Python tự động gọi PyState_AddModule sau khi nhập mô-đun sử dụng single-phase initialization, vì vậy việc gọi nó từ mã khởi tạo mô-đun là không cần thiết (nhưng vô hại). Chỉ cần một lệnh gọi rõ ràng nếu mã init của chính mô-đun sau đó gọi PyState_FindModule. Chức năng này chủ yếu nhằm mục đích triển khai các cơ chế nhập thay thế (bằng cách gọi trực tiếp hoặc bằng cách tham khảo cách triển khai của nó để biết chi tiết về các bản cập nhật trạng thái bắt buộc).

Nếu một mô-đun được gắn trước đó bằng cùng một def thì mô-đun đó sẽ được thay thế bằng module mới.

Người gọi phải có attached thread state.

Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)¶

Một phần của ABI ổn định kể từ phiên bản 3.3.

Xóa đối tượng mô-đun được tạo từ def khỏi trạng thái trình thông dịch. Trả về -1 với ngoại lệ được đặt là lỗi, 0 thành công.

Người gọi phải có attached thread state.

Added in version 3.3.

Đối tượng mô-đun¶

Định nghĩa mô-đun¶

Khe cắm mô-đun¶

Tạo mô-đun mở rộng một cách linh hoạt¶

Chức năng hỗ trợ¶

Tra cứu mô-đun (khởi tạo một pha)¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này