Cấu trúc đối tượng chung

Có một số lượng lớn các cấu trúc được sử dụng trong định nghĩa các loại đối tượng cho Python. Phần này mô tả các cấu trúc này và cách chúng được sử dụng.

Các loại đối tượng cơ bản và macro

Cuối cùng, tất cả các đối tượng Python đều chia sẻ một số lượng nhỏ các trường ở đầu biểu diễn của đối tượng trong bộ nhớ. Chúng được biểu thị bằng các loại PyObject và PyVarObject, lần lượt được xác định bằng cách mở rộng một số macro cũng được sử dụng, dù trực tiếp hay gián tiếp, trong định nghĩa của tất cả các đối tượng Python khác. Các macro bổ sung có thể được tìm thấy trong reference counting.

type PyObject
Một phần của API có giới hạn. (Chỉ một số thành viên là thành viên của ABI ổn định.)

Tất cả các loại đối tượng đều là phần mở rộng của loại này. Đây là loại chứa thông tin Python cần để coi con trỏ tới một đối tượng là một đối tượng. Trong bản dựng "phát hành" thông thường, nó chỉ chứa số tham chiếu của đối tượng và một con trỏ tới đối tượng loại tương ứng. Không có gì thực sự được khai báo là PyObject, nhưng mọi con trỏ tới đối tượng Python đều có thể được chuyển thành PyObject*.

Các thành viên không được truy cập trực tiếp; thay vào đó hãy sử dụng các macro như Py_REFCNT và Py_TYPE.

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

Số tham chiếu của đối tượng được trả về bởi Py_REFCNT. Không sử dụng trường này trực tiếp; thay vào đó hãy sử dụng các hàm và macro như Py_REFCNT, Py_INCREF() và Py_DecRef().

Loại trường có thể khác với Py_ssize_t, tùy thuộc vào cấu hình và nền tảng bản dựng.

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

Kiểu của đối tượng. Không sử dụng trường này trực tiếp; thay vào đó hãy sử dụng Py_TYPE và Py_SET_TYPE().

type PyVarObject
Một phần của API có giới hạn. (Chỉ một số thành viên là thành viên của ABI ổn định.)

Một phần mở rộng của PyObject có thêm trường ob_size. Điều này dành cho các đối tượng có một số khái niệm về length.

Như với PyObject, các thành viên không được truy cập trực tiếp; thay vào đó hãy sử dụng các macro như Py_SIZE, Py_REFCNT và Py_TYPE.

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

Trường kích thước, nội dung của nó phải được coi là chi tiết triển khai nội bộ của đối tượng.

Không sử dụng trường này trực tiếp; thay vào đó hãy sử dụng Py_SIZE.

Các hàm tạo đối tượng như PyObject_NewVar() thường sẽ đặt trường này theo kích thước được yêu cầu (số lượng mục). Sau khi tạo, các giá trị tùy ý có thể được lưu trữ trong ob_size bằng Py_SET_SIZE.

Để có được độ dài được hiển thị công khai của một đối tượng, được trả về bởi hàm len() của Python, thay vào đó hãy sử dụng PyObject_Length().

PyObject_HEAD

Đây là macro được sử dụng khi khai báo các kiểu mới đại diện cho các đối tượng không có độ dài thay đổi. Macro PyObject_HEAD mở rộng thành:

PyObject ob_base;

Xem tài liệu của PyObject ở trên.

PyObject_VAR_HEAD

Đây là macro được sử dụng khi khai báo các kiểu mới đại diện cho các đối tượng có độ dài thay đổi tùy theo từng trường hợp. Macro PyObject_VAR_HEAD mở rộng thành:

PyVarObject ob_base;

Xem tài liệu của PyVarObject ở trên.

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

Lớp cơ sở của tất cả các đối tượng khác, giống như object trong Python.

int Py_Is(PyObject *x, PyObject *y)
Một phần của ABI ổn định kể từ phiên bản 3.10.

Kiểm tra xem đối tượng x có phải là đối tượng y hay không, giống như x is y trong Python.

Added in version 3.10.

int Py_IsNone(PyObject *x)
Một phần của ABI ổn định kể từ phiên bản 3.10.

Kiểm tra xem một đối tượng có phải là None singleton hay không, giống như x is None trong Python.

Added in version 3.10.

int Py_IsTrue(PyObject *x)
Một phần của ABI ổn định kể từ phiên bản 3.10.

Kiểm tra xem một đối tượng có phải là True singleton hay không, giống như x is True trong Python.

Added in version 3.10.

int Py_IsFalse(PyObject *x)
Một phần của ABI ổn định kể từ phiên bản 3.10.

Kiểm tra xem một đối tượng có phải là False singleton hay không, giống như x is False trong Python.

Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)
Giá trị trả về: Tham chiếu mượn. Một phần của ABI ổn định kể từ phiên bản 3.14.

Lấy loại đối tượng Python o.

Tham chiếu trả về là borrowed từ o. Không phát hành nó với Py_DECREF() hoặc tương tự.

Thay đổi trong phiên bản 3.11: Py_TYPE() được thay đổi thành hàm tĩnh nội tuyến. Loại tham số không còn là const PyObject* nữa.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Trả về khác 0 nếu loại đối tượng o là type. Trả về 0 nếu không. Tương đương với: Py_TYPE(o) == type.

Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Đặt loại đối tượng o thành type mà không cần kiểm tra hoặc đếm tham chiếu.

Đây là một hoạt động ở mức độ rất thấp. Thay vào đó, hãy xem xét đặt thuộc tính Python __class__ bằng PyObject_SetAttrString() hoặc tương tự.

Lưu ý rằng việc chỉ định loại không tương thích có thể dẫn đến hành vi không xác định.

Nếu type là heap type, người gọi phải tạo một tham chiếu mới cho nó. Tương tự, nếu loại o cũ là loại heap, thì người gọi phải giải phóng một tham chiếu đến loại đó.

Added in version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)

Lấy trường ob_size của o.

Thay đổi trong phiên bản 3.11: Py_SIZE() được thay đổi thành hàm tĩnh nội tuyến. Loại tham số không còn là const PyVarObject* nữa.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Đặt trường ob_size của o thành size.

Added in version 3.9.

PyObject_HEAD_INIT(type)

Đây là macro mở rộng thành các giá trị khởi tạo cho loại PyObject mới. Macro này mở rộng tới:

_PyObject_EXTRA_INIT
1, gõ,
PyVarObject_HEAD_INIT(type, size)

Đây là macro mở rộng thành các giá trị khởi tạo cho loại PyVarObject mới, bao gồm trường ob_size. Macro này mở rộng tới:

_PyObject_EXTRA_INIT
1, loại, kích thước,

Thực hiện các hàm và phương thức

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

Loại hàm được sử dụng để triển khai hầu hết các lệnh gọi Python trong C. Các hàm thuộc loại này nhận hai tham số PyObject* và trả về một giá trị như vậy. Nếu giá trị trả về là NULL, một ngoại lệ sẽ được đặt. Nếu không phải là NULL, giá trị trả về sẽ được hiểu là giá trị trả về của hàm như được hiển thị trong Python. Hàm phải trả về một tham chiếu mới.

Chữ ký hàm là:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);
type PyCFunctionWithKeywords
Một phần của ABI ổn định.

Loại hàm được sử dụng để triển khai các lệnh gọi Python trong C có chữ ký METH_VARARGS | METH_KEYWORDS. Chữ ký hàm là:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);
type PyCFunctionFast
Một phần của ABI ổn định kể từ phiên bản 3.13.

Loại hàm được sử dụng để triển khai các lệnh gọi Python trong C có chữ ký METH_FASTCALL. Chữ ký hàm là:

PyObject *PyCFunctionFast(PyObject *self,
                          PyObject *const *args,
                          Py_ssize_t lảng vảng);
type PyCFunctionFastWithKeywords
Một phần của ABI ổn định kể từ phiên bản 3.13.

Loại hàm được sử dụng để triển khai các lệnh gọi Python trong C có chữ ký METH_FASTCALL | METH_KEYWORDS. Chữ ký hàm là:

PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                      PyObject *const *args,
                                      Py_ssize_t càu nhàu,
                                      PyObject *kwname);
type PyCMethod

Loại hàm được sử dụng để triển khai các lệnh gọi Python trong C có chữ ký METH_METHOD | METH_FASTCALL | METH_KEYWORDS. Chữ ký hàm là:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *định nghĩa_class,
                    PyObject *const *args,
                    Py_ssize_t càu nhàu,
                    PyObject *kwname)

Added in version 3.9.

type PyMethodDef
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 được sử dụng để mô tả một phương thức thuộc loại mở rộng. Cấu trúc này có bốn trường:

const char *ml_name

Tên của phương pháp.

PyCFunction ml_meth

Con trỏ tới việc thực hiện C.

int ml_flags

Cờ bit cho biết cuộc gọi sẽ được xây dựng như thế nào.

const char *ml_doc

Trỏ tới nội dung của chuỗi doc.

Zz000zz là con trỏ hàm C. Các hàm có thể có nhiều loại khác nhau nhưng chúng luôn trả về PyObject*. Nếu hàm không thuộc PyCFunction, trình biên dịch sẽ yêu cầu truyền vào bảng phương thức. Mặc dù PyCFunction định nghĩa tham số đầu tiên là PyObject*, thông thường việc triển khai phương thức sử dụng loại C cụ thể của đối tượng self.

Trường ml_flags là một trường bit có thể bao gồm các cờ sau. Các cờ riêng lẻ biểu thị quy ước gọi hoặc quy ước ràng buộc.

Có những quy ước gọi như sau:

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

Đây là quy ước gọi điển hình, trong đó các phương thức có kiểu PyCFunction. Hàm mong đợi hai giá trị PyObject*. Đối tượng đầu tiên là đối tượng self dành cho các phương thức; đối với các chức năng mô-đun, nó là đối tượng mô-đun. Tham số thứ hai (thường được gọi là args) là một đối tượng tuple đại diện cho tất cả các đối số. Tham số này thường được xử lý bằng PyArg_ParseTuple() hoặc PyArg_UnpackTuple().

METH_KEYWORDS

Chỉ có thể được sử dụng trong một số kết hợp nhất định với các cờ khác: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS và METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS

Các phương thức có cờ này phải thuộc loại PyCFunctionWithKeywords. Hàm mong đợi ba tham số: self, args, kwargs trong đó kwargs là từ điển của tất cả các đối số từ khóa hoặc có thể là NULL nếu không có đối số từ khóa. Các tham số thường được xử lý bằng PyArg_ParseTupleAndKeywords().

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

Quy ước gọi nhanh chỉ hỗ trợ các đối số vị trí. Các phương thức có kiểu PyCFunctionFast. Tham số đầu tiên là self, tham số thứ hai là mảng C gồm các giá trị PyObject* biểu thị các đối số và tham số thứ ba là số lượng đối số (độ dài của mảng).

Added in version 3.7.

Thay đổi trong phiên bản 3.10: METH_FASTCALL hiện là một phần của stable ABI.

METH_FASTCALL | METH_KEYWORDS

Phần mở rộng của METH_FASTCALL cũng hỗ trợ các đối số từ khóa, với các phương thức kiểu PyCFunctionFastWithKeywords. Đối số từ khóa được truyền theo cách tương tự như trong vectorcall protocol: có thêm tham số PyObject* thứ tư là một bộ dữ liệu biểu thị tên của đối số từ khóa (được đảm bảo là chuỗi) hoặc có thể là NULL nếu không có từ khóa. Các giá trị của đối số từ khóa được lưu trữ trong mảng args, sau các đối số vị trí.

Added in version 3.7.

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

Chỉ có thể sử dụng kết hợp với các cờ khác: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

Phần mở rộng của METH_FASTCALL | METH_KEYWORDS hỗ trợ defining class, tức là lớp chứa phương thức được đề cập. Lớp xác định có thể là siêu lớp của Py_TYPE(self).

Phương thức này cần phải thuộc loại PyCMethod, giống như đối với METH_FASTCALL | METH_KEYWORDS với đối số defining_class được thêm sau self.

Added in version 3.9.

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

Các phương thức không có tham số không cần kiểm tra xem các đối số có được đưa ra hay không nếu chúng được liệt kê với cờ METH_NOARGS. Chúng cần phải thuộc loại PyCFunction. Tham số đầu tiên thường được đặt tên là self và sẽ giữ một tham chiếu đến phiên bản mô-đun hoặc đối tượng. Trong mọi trường hợp, tham số thứ hai sẽ là NULL.

Hàm phải có 2 tham số. Vì tham số thứ hai không được sử dụng nên Py_UNUSED có thể được sử dụng để ngăn cảnh báo trình biên dịch.

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

Các phương thức có một đối số đối tượng duy nhất có thể được liệt kê bằng cờ METH_O, thay vì gọi PyArg_ParseTuple() bằng đối số "O". Chúng có loại PyCFunction, với tham số self và tham số PyObject* đại diện cho một đối số.

Hai hằng số này không được sử dụng để biểu thị quy ước gọi mà là sự ràng buộc khi được sử dụng với các phương thức của lớp. Chúng có thể không được sử dụng cho các chức năng được xác định cho các mô-đun. Nhiều nhất một trong các cờ này có thể được đặt cho bất kỳ phương thức nào.

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

Phương thức này sẽ được truyền đối tượng kiểu làm tham số đầu tiên chứ không phải là một thể hiện của kiểu. Điều này được sử dụng để tạo class methods, tương tự như những gì được tạo khi sử dụng chức năng tích hợp classmethod().

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

Phương thức này sẽ được truyền NULL làm tham số đầu tiên chứ không phải là một phiên bản của loại. Điều này được sử dụng để tạo static methods, tương tự như những gì được tạo khi sử dụng chức năng tích hợp staticmethod().

Một hằng số khác kiểm soát xem một phương thức có được tải thay cho định nghĩa khác có cùng tên phương thức hay không.

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

Phương thức này sẽ được tải thay cho các định nghĩa hiện có. Nếu không có METH_COEXIST, mặc định là bỏ qua các định nghĩa lặp lại. Vì trình bao bọc vị trí được tải trước bảng phương thức, nên sự tồn tại của vị trí sq_contains chẳng hạn sẽ tạo ra một phương thức được bao bọc có tên __contains__() và ngăn cản việc tải PyCFunction tương ứng có cùng tên. Với cờ được xác định, PyCFunction sẽ được tải thay cho đối tượng trình bao bọc và sẽ cùng tồn tại với vị trí. Điều này hữu ích vì lệnh gọi tới PyCFunctions được tối ưu hóa nhiều hơn so với lệnh gọi đối tượng trình bao bọc.

PyTypeObject PyCMethod_Type

Đối tượng kiểu tương ứng với các đối tượng phương thức Python C. Điều này có sẵn dưới dạng types.BuiltinMethodType trong lớp Python.

int PyCMethod_Check(PyObject *op)

Trả về true nếu op là một phiên bản của loại PyCMethod_Type hoặc một kiểu con của nó. Chức năng này luôn thành công.

int PyCMethod_CheckExact(PyObject *op)

Điều này giống với PyCMethod_Check() nhưng không tính đến các kiểu con.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
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.9.

Biến ml thành đối tượng callable của Python. Người gọi phải đảm bảo rằng ml tồn tại lâu hơn callable. Thông thường, ml được định nghĩa là một biến tĩnh.

Tham số self sẽ được chuyển dưới dạng đối số self cho hàm C trong ml->ml_meth khi được gọi. self có thể là NULL.

Thuộc tính __module__ của đối tượng callable có thể được đặt từ đối số module đã cho. module phải là một chuỗi Python, chuỗi này sẽ được dùng làm tên của mô-đun chứa hàm được xác định. Nếu không có, chuỗi này có thể được đặt thành None hoặc NULL.

Xem thêm

function.__module__

Tham số cls sẽ được chuyển dưới dạng đối số defining_class cho hàm C. Phải được đặt nếu METH_METHOD được đặt trên ml->ml_flags.

Added in version 3.9.

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

Đối tượng loại tương ứng với các đối tượng hàm Python C. Điều này có sẵn dưới dạng types.BuiltinFunctionType trong lớp Python.

int PyCFunction_Check(PyObject *op)

Trả về true nếu op là một phiên bản của loại PyCFunction_Type hoặc một kiểu con của nó. Chức năng này luôn thành công.

int PyCFunction_CheckExact(PyObject *op)

Điều này giống với PyCFunction_Check() nhưng không tính đến các kiểu con.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Tương đương với PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)
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.4.

Tương đương với PyCMethod_New(ml, self, NULL, NULL).

int PyCFunction_GetFlags(PyObject *func)
Một phần của ABI ổn định.

Nhận cờ của hàm trên func khi chúng được chuyển tới ml_flags.

Nếu func không phải là đối tượng hàm C thì điều này không thành công với một ngoại lệ. func không được là NULL.

Hàm này trả về các cờ của hàm khi thành công và -1 với một ngoại lệ được đặt thành lỗi.

int PyCFunction_GET_FLAGS(PyObject *func)

Điều này giống như PyCFunction_GetFlags() nhưng không có lỗi hoặc kiểm tra loại.

PyCFunction PyCFunction_GetFunction(PyObject *func)
Một phần của ABI ổn định.

Lấy con trỏ hàm trên func khi nó được truyền tới ml_meth.

Nếu func không phải là đối tượng hàm C thì điều này không thành công với một ngoại lệ. func không được là NULL.

Hàm này trả về con trỏ hàm khi thành công và NULL với ngoại lệ được đặt nếu thất bại.

int PyCFunction_GET_FUNCTION(PyObject *func)

Điều này giống như PyCFunction_GetFunction() nhưng không có lỗi hoặc kiểm tra loại.

PyObject *PyCFunction_GetSelf(PyObject *func)
Một phần của ABI ổn định.

Lấy đối tượng "tự" trên func. Đây là đối tượng sẽ được chuyển đến đối số đầu tiên của PyCFunction. Đối với các đối tượng hàm C được tạo thông qua PyMethodDef trên PyModuleDef, đây là đối tượng mô-đun kết quả.

Nếu func không phải là đối tượng hàm C thì điều này không thành công với một ngoại lệ. func không được là NULL.

Hàm này trả về borrowed reference cho đối tượng "self" nếu thành công và NULL với ngoại lệ được đặt nếu thất bại.

PyObject *PyCFunction_GET_SELF(PyObject *func)

Điều này giống như PyCFunction_GetSelf() nhưng không có lỗi hoặc kiểm tra loại.

Truy cập thuộc tính của các loại tiện ích mở rộng

type PyMemberDef
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 mô tả một thuộc tính của một kiểu tương ứng với thành viên cấu trúc C. Khi xác định một lớp, hãy đặt một mảng kết thúc bằng NULL của các cấu trúc này vào khe tp_members.

Các trường của nó theo thứ tự:

const char *name

Tên của thành viên. Giá trị NULL đánh dấu sự kết thúc của mảng PyMemberDef[].

Chuỗi phải ở dạng tĩnh, không có bản sao nào được tạo ra từ nó.

int type

Kiểu thành viên trong cấu trúc C. Xem Các loại thành viên để biết các giá trị có thể.

Py_ssize_t offset

Phần bù tính bằng byte mà thành viên nằm trên cấu trúc đối tượng của loại.

int flags

Không hoặc nhiều hơn Cờ thành viên, được kết hợp bằng cách sử dụng bitwise OR.

const char *doc

Chuỗi tài liệu hoặc NULL. Chuỗi phải ở dạng tĩnh, không có bản sao nào được tạo ra từ nó. Thông thường, nó được xác định bằng PyDoc_STR.

Theo mặc định (khi flags là 0), các thành viên cho phép cả quyền truy cập đọc và ghi. Sử dụng cờ Py_READONLY để truy cập chỉ đọc. Một số loại nhất định, như Py_T_STRING, ngụ ý Py_READONLY. Chỉ có thể xóa thành viên Py_T_OBJECT_EX (và T_OBJECT cũ).

Đối với các loại được phân bổ heap (được tạo bằng PyType_FromSpec() hoặc tương tự), PyMemberDef có thể chứa định nghĩa cho thành viên đặc biệt "__vectorcalloffset__", tương ứng với tp_vectorcall_offset trong các đối tượng loại. Thành viên này phải được xác định bằng Py_T_PYSSIZET và Py_READONLY hoặc Py_READONLY | Py_RELATIVE_OFFSET. Ví dụ:

tĩnh PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL} /* Lính gác */
};

(Bạn có thể cần #include <stddef.h> để có offsetof().)

Các phần bù cũ tp_dictoffset và tp_weaklistoffset có thể được xác định tương tự bằng cách sử dụng các thành viên "__dictoffset__" và "__weaklistoffset__", nhưng thay vào đó, các tiện ích mở rộng được khuyến khích sử dụng Py_TPFLAGS_MANAGED_DICT và Py_TPFLAGS_MANAGED_WEAKREF.

Thay đổi trong phiên bản 3.12: PyMemberDef luôn có sẵn. Trước đây nó yêu cầu phải có "structmember.h".

Thay đổi trong phiên bản 3.14: Py_RELATIVE_OFFSET hiện được phép cho "__vectorcalloffset__", "__dictoffset__" và "__weaklistoffset__".

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
Một phần của ABI ổn định.

Lấy thuộc tính của đối tượng tại địa chỉ obj_addr. Thuộc tính được mô tả bởi PyMemberDef m. Trả về NULL do lỗi.

Thay đổi trong phiên bản 3.12: PyMember_GetOne luôn có sẵn. Trước đây nó yêu cầu phải có "structmember.h".

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
Một phần của ABI ổn định.

Đặt thuộc tính thuộc đối tượng tại địa chỉ obj_addr thành đối tượng o. Thuộc tính cần đặt được mô tả bởi PyMemberDef m. Trả về 0 nếu thành công và giá trị âm nếu thất bại.

Thay đổi trong phiên bản 3.12: PyMember_SetOne luôn có sẵn. Trước đây nó yêu cầu phải có "structmember.h".

Cờ thành viên

Các cờ sau có thể được sử dụng với PyMemberDef.flags:

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

Không thể ghi được.

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

Phát ra object.__getattr__ audit event trước khi đọc.

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

Cho biết rằng offset của mục nhập PyMemberDef này biểu thị phần chênh lệch so với dữ liệu dành riêng cho lớp con, thay vì từ PyObject.

Chỉ có thể được sử dụng như một phần của Py_tp_members slot khi tạo lớp bằng basicsize âm. Đó là bắt buộc trong trường hợp đó. Khi đặt tp_members từ vị trí trong quá trình tạo lớp, Python sẽ xóa cờ và đặt PyMemberDef.offset thành phần bù từ cấu trúc PyObject.

Thay đổi trong phiên bản 3.10: Các macro RESTRICTED, READ_RESTRICTED và WRITE_RESTRICTED có sẵn với #include "structmember.h" không được dùng nữa. READ_RESTRICTED và RESTRICTED tương đương với Py_AUDIT_READ; WRITE_RESTRICTED không làm gì cả.

Thay đổi trong phiên bản 3.12: Macro READONLY đã được đổi tên thành Py_READONLY. Macro PY_AUDIT_READ đã được đổi tên bằng tiền tố Py_. Những cái tên mới bây giờ luôn có sẵn. Trước đây, những thứ này yêu cầu #include "structmember.h". Tiêu đề vẫn có sẵn và nó cung cấp tên cũ.

Các loại thành viên

PyMemberDef.type có thể là một trong các macro sau tương ứng với các loại C khác nhau. Khi thành viên được truy cập bằng Python, nó sẽ được chuyển đổi sang loại Python tương đương. Khi được đặt từ Python, nó sẽ được chuyển đổi về loại C. Nếu điều đó là không thể, một ngoại lệ như TypeError hoặc ValueError sẽ xuất hiện.

Trừ khi được đánh dấu (D), các thuộc tính được xác định theo cách này không thể bị xóa bằng cách sử dụng ví dụ: del hoặc delattr().

Tên vĩ mô

loại C

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

char

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

short

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

int

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

long

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

long long

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

unsigned char

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

unsigned int

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

unsigned short

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

unsigned long

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

unsigned long long

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

Py_ssize_t

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

float

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

double

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

char (viết là 0 hoặc 1)

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

const char* (*)

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

const char[] (*)

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

char (0-127)

:py:class:`str`(**)
Py_T_OBJECT_EX
Một phần của ABI ổn định kể từ phiên bản 3.12.

PyObject*

object (D)

(*): Chuỗi C được mã hóa UTF8, kết thúc bằng 0. Với Py_T_STRING biểu diễn C là một con trỏ; với Py_T_STRING_INPLACE chuỗi được lưu trữ trực tiếp trong cấu trúc.

(**): Chuỗi có độ dài 1. Chỉ chấp nhận ASCII.

(RO): Ngụ ý Py_READONLY.

(D): Có thể xóa, trong trường hợp đó con trỏ được đặt thành NULL. Đọc con trỏ NULL sẽ tăng AttributeError.

Added in version 3.12: Trong các phiên bản trước, macro chỉ có sẵn với #include "structmember.h" và được đặt tên mà không có tiền tố Py_ (ví dụ: T_INT). Tiêu đề vẫn có sẵn và chứa các tên cũ, cùng với các loại không được dùng nữa:

T_OBJECT

Giống như Py_T_OBJECT_EX, nhưng NULL được chuyển đổi thành None. Điều này dẫn đến hành vi đáng ngạc nhiên trong Python: việc xóa thuộc tính sẽ đặt nó thành None một cách hiệu quả.

T_NONE

Luôn là None. Phải được sử dụng với Py_READONLY.

Xác định Getters và Setters

type PyGetSetDef
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 để xác định quyền truy cập giống như thuộc tính cho một loại. Xem thêm mô tả về khe PyTypeObject.tp_getset.

const char *name

tên thuộc tính

getter get

Hàm C để lấy thuộc tính.

setter set

Hàm C tùy chọn để đặt hoặc xóa thuộc tính. Nếu NULL, thuộc tính chỉ đọc.

const char *doc

chuỗi tài liệu tùy chọn

void *closure

Con trỏ dữ liệu người dùng tùy chọn, cung cấp dữ liệu bổ sung cho getter và setter.

typedef PyObject *(*getter)(PyObject*, void*)
Một phần của ABI ổn định.

Hàm get lấy một tham số PyObject* (ví dụ) và một con trỏ dữ liệu người dùng (closure được liên kết):

Nó sẽ trả về một tham chiếu mới về thành công hoặc NULL với một ngoại lệ được đặt khi thất bại.

typedef int (*setter)(PyObject*, PyObject*, void*)
Một phần của ABI ổn định.

Các hàm set có hai tham số PyObject* (thể hiện và giá trị được đặt) và một con trỏ dữ liệu người dùng (closure được liên kết):

Trong trường hợp thuộc tính cần bị xóa thì tham số thứ hai là NULL. Nên trả về 0 nếu thành công hoặc -1 với ngoại lệ được đặt nếu thất bại.