Giao thức đối tượng¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

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

Nhận strong reference về một hằng số.

Đặt ngoại lệ và trả về NULL nếu constant_id không hợp lệ.

constant_id phải là một trong những số nhận dạng không đổi sau:

Mã định danh không đổi	Giá trị	Đối tượng được trả về
Py_CONSTANT_NONE¶	`0`	`None`
Py_CONSTANT_FALSE¶	`1`	`False`
Py_CONSTANT_TRUE¶	`2`	`True`
Py_CONSTANT_ELLIPSIS¶	`3`	`Ellipsis`
Py_CONSTANT_NOT_IMPLEMENTED¶	`4`	`NotImplemented`
Py_CONSTANT_ZERO¶	`5`	`0`
Py_CONSTANT_ONE¶	`6`	`1`
Py_CONSTANT_EMPTY_STR¶	`7`	`''`
Py_CONSTANT_EMPTY_BYTES¶	`8`	`b''`
Py_CONSTANT_EMPTY_TUPLE¶	`9`	`()`

Các giá trị số chỉ được đưa ra cho các dự án không thể sử dụng định danh không đổi.

Added in version 3.13.

Trong CPython, tất cả các hằng số này đều là immortal.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

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

Tương tự như Py_GetConstant() nhưng trả về borrowed reference.

Chức năng này chủ yếu nhằm mục đích tương thích ngược: nên sử dụng Py_GetConstant() cho mã mới.

Tham chiếu được mượn từ trình thông dịch và có hiệu lực cho đến khi trình thông dịch hoàn tất.

Added in version 3.13.

PyObject *Py_NotImplemented¶: Singleton NotImplemented, được sử dụng để báo hiệu rằng một thao tác không được triển khai đối với tổ hợp loại đã cho.

Py_RETURN_NOTIMPLEMENTED¶: Xử lý đúng cách việc trả về Py_NotImplemented từ bên trong hàm C (nghĩa là tạo một strong reference mới cho NotImplemented và trả về nó).

Py_PRINT_RAW¶: Cờ được sử dụng với nhiều hàm in đối tượng (như PyObject_Print() và PyFile_WriteObject()). Nếu được thông qua, các hàm này sẽ sử dụng str() của đối tượng thay vì repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)¶: In một đối tượng o, trên file fp. Trả về -1 do lỗi. Đối số flags được sử dụng để kích hoạt các tùy chọn in nhất định. Tùy chọn duy nhất hiện được hỗ trợ là Py_PRINT_RAW; nếu được cung cấp, str() của đối tượng sẽ được viết thay vì repr().

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Trả về 1 nếu o có thuộc tính attr_name và 0 nếu không. Điều này tương đương với biểu thức Python hasattr(o, attr_name). Nếu thất bại, hãy trả lại -1.

Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Điều này giống với PyObject_HasAttrWithError(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶: Một phần của ABI ổn định.
Trả về 1 nếu o có thuộc tính attr_name và 0 nếu không. Chức năng này luôn thành công.

Ghi chú

Các ngoại lệ xảy ra khi lệnh này gọi các phương thức __getattr__() và __getattribute__() không được truyền bá mà thay vào đó được trao cho sys.unraisablehook(). Để xử lý lỗi thích hợp, hãy sử dụng PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() hoặc PyObject_GetAttr() thay thế.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: Một phần của ABI ổn định.
Điều này giống với PyObject_HasAttr(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Ghi chú

Các ngoại lệ xảy ra khi điều này gọi các phương thức __getattr__() và __getattribute__() hoặc trong khi tạo đối tượng str tạm thời đều bị bỏ qua âm thầm. Để xử lý lỗi thích hợp, hãy sử dụng PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() hoặc PyObject_GetAttrString() thay thế.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶

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

Truy xuất thuộc tính có tên attr_name từ đối tượng o. Trả về giá trị thuộc tính nếu thành công hoặc NULL nếu thất bại. Điều này tương đương với biểu thức Python o.attr_name.

Nếu thuộc tính bị thiếu không được coi là lỗi, bạn có thể sử dụng PyObject_GetOptionalAttr() để thay thế.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶

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

Điều này giống với PyObject_GetAttr(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Nếu thuộc tính bị thiếu không được coi là lỗi, bạn có thể sử dụng PyObject_GetOptionalAttrString() để thay thế.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

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

Biến thể của PyObject_GetAttr() không tăng AttributeError nếu không tìm thấy thuộc tính.

Nếu thuộc tính được tìm thấy, hãy trả về 1 và đặt *result thành strong reference mới cho thuộc tính. Nếu không tìm thấy thuộc tính, hãy trả về 0 và đặt *result thành NULL; AttributeError bị tắt tiếng. Nếu xuất hiện lỗi không phải AttributeError, hãy trả về -1 và đặt *result thành NULL.

Added in version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Điều này giống với PyObject_GetOptionalAttr(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Added in version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Hàm getter thuộc tính chung được đặt vào vị trí tp_getattro của đối tượng loại. Nó tìm kiếm một bộ mô tả trong từ điển của các lớp trong MRO của đối tượng cũng như một thuộc tính trong __dict__ của đối tượng (nếu có). Như đã nêu trong Triển khai mô tả, các bộ mô tả dữ liệu được ưu tiên hơn các thuộc tính phiên bản, trong khi các bộ mô tả không phải dữ liệu thì không. Nếu không, AttributeError sẽ xuất hiện.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶

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

Đặt giá trị của thuộc tính có tên attr_name, cho đối tượng o, thành giá trị v. Đưa ra một ngoại lệ và trả về -1 khi thất bại; trả về 0 khi thành công. Điều này tương đương với câu lệnh Python o.attr_name = v.

Nếu v là NULL, thuộc tính sẽ bị xóa. Hành vi này không được chấp nhận để sử dụng PyObject_DelAttr() nhưng hiện tại không có kế hoạch loại bỏ nó.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶

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

Điều này giống với PyObject_SetAttr(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Nếu v là NULL, thuộc tính sẽ bị xóa nhưng tính năng này không được dùng nữa để sử dụng PyObject_DelAttrString().

Số lượng tên thuộc tính khác nhau được truyền cho hàm này phải được giữ ở mức nhỏ, thường bằng cách sử dụng chuỗi được phân bổ tĩnh như attr_name. Đối với các tên thuộc tính không được biết 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.

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶: Một phần của ABI ổn định.
Hàm xóa và thiết lập thuộc tính chung được dùng để đặt vào khe tp_setattro của đối tượng loại. Nó tìm kiếm một bộ mô tả dữ liệu trong từ điển của các lớp trong MRO của đối tượng và nếu tìm thấy nó sẽ ưu tiên cài đặt hoặc xóa thuộc tính trong từ điển cá thể. Ngược lại, thuộc tính sẽ được đặt hoặc xóa trong __dict__ của đối tượng (nếu có). Nếu thành công, 0 được trả về, nếu không thì AttributeError được nâng lên và -1 được trả về.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Xóa thuộc tính có tên attr_name cho đối tượng o. Trả về -1 khi thất bại. Điều này tương đương với câu lệnh Python del o.attr_name.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶

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

Điều này giống với PyObject_DelAttr(), nhưng attr_name được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

Số lượng tên thuộc tính khác nhau được truyền cho hàm này phải được giữ ở mức nhỏ, thường bằng cách sử dụng chuỗi được phân bổ tĩnh như attr_name. Đối với các tên thuộc tính không được biết tại thời điểm biên dịch, hãy gọi trực tiếp PyUnicode_FromString() và PyObject_DelAttr(). Để 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 để tra cứu.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶

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.10.

Cách triển khai chung cho trình thu thập của bộ mô tả __dict__. Nó tạo ra từ điển nếu cần thiết.

Hàm này cũng có thể được gọi để lấy __dict__ của đối tượng o. Chuyển NULL cho context khi gọi nó. Vì hàm này có thể cần phân bổ bộ nhớ cho từ điển nên việc gọi PyObject_GetAttr() khi truy cập một thuộc tính trên đối tượng có thể hiệu quả hơn.

Nếu thất bại, trả về NULL với một bộ ngoại lệ.

Added in version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶: Một phần của ABI ổn định kể từ phiên bản 3.7.
Cách triển khai chung cho trình thiết lập bộ mô tả __dict__. Việc triển khai này không cho phép xóa từ điển.

Added in version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)¶

Trả về con trỏ tới __dict__ của đối tượng obj. Nếu không có __dict__, hãy trả về NULL mà không đặt ngoại lệ.

Hàm này có thể cần phân bổ bộ nhớ cho từ điển, do đó, việc gọi PyObject_GetAttr() khi truy cập một thuộc tính trên đối tượng có thể hiệu quả hơn.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
So sánh các giá trị của o1 và o2 bằng cách sử dụng thao tác được chỉ định bởi opid, phải là một trong các giá trị Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT hoặc Py_GE, tương ứng với <, <=, ==, !=, >, hoặc >= tương ứng. Điều này tương đương với biểu thức o1 op o2 trong Python, trong đó op là toán tử tương ứng với opid. Trả về giá trị so sánh nếu thành công hoặc NULL nếu thất bại.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶: Một phần của ABI ổn định.
So sánh các giá trị của o1 và o2 bằng cách sử dụng thao tác được chỉ định bởi opid, giống như PyObject_RichCompare(), nhưng trả về -1 do lỗi, 0 nếu kết quả sai, 1 nếu không.

Ghi chú

Nếu o1 và o2 là cùng một đối tượng, PyObject_RichCompareBool() sẽ luôn trả về 1 cho Py_EQ và 0 cho Py_NE.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶

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

Định dạng obj bằng format_spec. Điều này tương đương với biểu thức Python format(obj, format_spec).

format_spec có thể là NULL. Trong trường hợp này, lệnh gọi tương đương với format(obj). Trả về chuỗi được định dạng nếu thành công, NULL nếu thất bại.

PyObject *PyObject_Repr(PyObject *o)¶

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

Tính toán biểu diễn chuỗi của đối tượng o. Trả về biểu diễn chuỗi nếu thành công, NULL nếu thất bại. Điều này tương đương với biểu thức Python repr(o). Được gọi bằng hàm tích hợp repr().

Nếu đối số là NULL, trả về chuỗi '<NULL>'.

Thay đổi trong phiên bản 3.4: Hàm này hiện bao gồm một xác nhận gỡ lỗi để giúp đảm bảo rằng nó không âm thầm loại bỏ một ngoại lệ đang hoạt động.

PyObject *PyObject_ASCII(PyObject *o)¶

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

Với vai PyObject_Repr(), hãy tính toán biểu diễn chuỗi của đối tượng o, nhưng thoát khỏi các ký tự không phải ASCII trong chuỗi được trả về bởi PyObject_Repr() với các ký tự thoát \x, \u hoặc \U. Điều này tạo ra một chuỗi tương tự như chuỗi được trả về bởi PyObject_Repr() trong Python 2. Được gọi bằng hàm tích hợp ascii().

Nếu đối số là NULL, trả về chuỗi '<NULL>'.

PyObject *PyObject_Str(PyObject *o)¶

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

Tính toán biểu diễn chuỗi của đối tượng o. Trả về biểu diễn chuỗi nếu thành công, NULL nếu thất bại. Điều này tương đương với biểu thức Python str(o). Được gọi bằng hàm tích hợp str() và do đó, được gọi bằng hàm print().

Nếu đối số là NULL, trả về chuỗi '<NULL>'.

Thay đổi trong phiên bản 3.4: Hàm này hiện bao gồm một xác nhận gỡ lỗi để giúp đảm bảo rằng nó không âm thầm loại bỏ một ngoại lệ đang hoạt động.

PyObject *PyObject_Bytes(PyObject *o)¶

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

Tính toán biểu diễn byte của đối tượng o. NULL được trả về khi thất bại và đối tượng bytes được trả về khi thành công. Điều này tương đương với biểu thức bytes(o) trong Python, khi o không phải là số nguyên. Không giống như bytes(o), TypeError được nâng lên khi o là một số nguyên thay vì đối tượng byte được khởi tạo bằng 0.

Nếu đối số là NULL, trả về đối tượng bytes b'<NULL>'.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

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

Trả về 1 nếu lớp derived giống hệt hoặc dẫn xuất từ lớp cls, nếu không thì trả về 0. Trong trường hợp có lỗi, hãy trả về -1.

Nếu cls là một bộ, việc kiểm tra sẽ được thực hiện đối với mọi mục trong cls. Kết quả sẽ là 1 khi ít nhất một trong các lần kiểm tra trả về 1, nếu không sẽ là 0.

Nếu cls có phương thức __subclasscheck__(), nó sẽ được gọi để xác định trạng thái lớp con như được mô tả trong PEP 3119. Mặt khác, derived là lớp con của cls nếu nó là lớp con trực tiếp hoặc gián tiếp, tức là có trong cls.__mro__.

Thông thường chỉ các đối tượng lớp, tức là các thể hiện của type hoặc lớp dẫn xuất, mới được coi là lớp. Tuy nhiên, các đối tượng có thể ghi đè điều này bằng cách có thuộc tính __bases__ (phải là một bộ các lớp cơ sở).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶

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

Trả về 1 nếu inst là một phiên bản của lớp cls hoặc một lớp con của cls hoặc 0 nếu không. Nếu có lỗi, trả về -1 và đặt ngoại lệ.

Nếu cls là một bộ, việc kiểm tra sẽ được thực hiện đối với mọi mục trong cls. Kết quả sẽ là 1 khi ít nhất một trong các lần kiểm tra trả về 1, nếu không sẽ là 0.

Nếu cls có phương thức __instancecheck__(), nó sẽ được gọi để xác định trạng thái lớp con như được mô tả trong PEP 3119. Mặt khác, inst là một phiên bản của cls nếu lớp của nó là lớp con của cls.

Một cá thể inst có thể ghi đè những gì được coi là lớp của nó bằng cách có thuộc tính __class__.

Một đối tượng cls có thể ghi đè nếu nó được coi là một lớp và các lớp cơ sở của nó là gì, bằng cách có thuộc tính __bases__ (phải là một bộ các lớp cơ sở).

Py_hash_t PyObject_Hash(PyObject *o)¶: Một phần của ABI ổn định.
Tính toán và trả về giá trị băm của đối tượng o. Nếu thất bại, trả về -1. Điều này tương đương với biểu thức Python hash(o).

Thay đổi trong phiên bản 3.2: Kiểu trả về bây giờ là Py_hash_t. Đây là số nguyên có dấu có cùng kích thước với Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶: Một phần của ABI ổn định.
Đặt TypeError cho biết type(o) không phải là hashable và trả về -1. Hàm này được xử lý đặc biệt khi được lưu trữ trong khe tp_hash, cho phép một loại chỉ rõ rõ ràng cho trình thông dịch rằng nó không thể băm được.

int PyObject_IsTrue(PyObject *o)¶: Một phần của ABI ổn định.
Trả về 1 nếu đối tượng o được coi là đúng và 0 nếu ngược lại. Điều này tương đương với biểu thức Python not not o. Nếu thất bại, hãy trả lại -1.

int PyObject_Not(PyObject *o)¶: Một phần của ABI ổn định.
Trả về 0 nếu đối tượng o được coi là đúng và 1 nếu ngược lại. Điều này tương đương với biểu thức Python not o. Nếu thất bại, hãy trả lại -1.

PyObject *PyObject_Type(PyObject *o)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Khi o không phải là NULL, trả về một loại đối tượng tương ứng với loại đối tượng của đối tượng o. Nếu thất bại, tăng SystemError và trả về NULL. Điều này tương đương với biểu thức Python type(o). Hàm này tạo một strong reference mới cho giá trị trả về. Thực sự không có lý do gì để sử dụng hàm này thay vì hàm Py_TYPE(), hàm này trả về một con trỏ kiểu PyTypeObject*, trừ khi cần một strong reference mới.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶: Trả về giá trị khác 0 nếu đối tượng o thuộc loại type hoặc một loại con của type và 0 nếu ngược lại. Cả hai tham số phải không phải là NULL.

Py_ssize_t PyObject_Size(PyObject *o)¶
Py_ssize_t PyObject_Length(PyObject *o)¶: Một phần của ABI ổn định.
Trả về độ dài của đối tượng o. Nếu đối tượng o cung cấp trình tự và giao thức ánh xạ, thì độ dài chuỗi sẽ được trả về. Nếu có lỗi, -1 sẽ được trả về. Điều này tương đương với biểu thức Python len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶: Trả về độ dài ước tính cho đối tượng o. Trước tiên, hãy thử trả về độ dài thực của nó, sau đó ước tính bằng __length_hint__() và cuối cùng trả về giá trị mặc định. Khi có lỗi trả về -1. Điều này tương đương với biểu thức Python operator.length_hint(o, defaultvalue).

Added in version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về phần tử của o tương ứng với đối tượng key hoặc NULL khi bị lỗi. Điều này tương đương với biểu thức Python o[key].

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶: Một phần của ABI ổn định.
Ánh xạ đối tượng key tới giá trị v. Đưa ra một ngoại lệ và trả về -1 khi thất bại; trả về 0 khi thành công. Điều này tương đương với câu lệnh Python o[key] = v. Hàm does not này đánh cắp một tham chiếu đến v.

int PyObject_DelItem(PyObject *o, PyObject *key)¶: Một phần của ABI ổn định.
Xóa ánh xạ cho đối tượng key khỏi đối tượng o. Trả về -1 khi thất bại. Điều này tương đương với câu lệnh Python del o[key].

int PyObject_DelItemString(PyObject *o, const char *key)¶: Một phần của ABI ổn định.
Điều này giống với PyObject_DelItem(), nhưng key được chỉ định là chuỗi byte được mã hóa const char* UTF-8, thay vì PyObject*.

PyObject *PyObject_Dir(PyObject *o)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Điều này tương đương với biểu thức Python dir(o), trả về danh sách các chuỗi (có thể trống) phù hợp với đối số đối tượng hoặc NULL nếu có lỗi. Nếu đối số là NULL, thì đối số này giống như dir() của Python, trả về tên của người dân địa phương hiện tại; trong trường hợp này, nếu không có khung thực thi nào được kích hoạt thì NULL sẽ được trả về nhưng PyErr_Occurred() sẽ trả về false.

PyObject *PyObject_GetIter(PyObject *o)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Điều này tương đương với biểu thức Python iter(o). Nó trả về một trình vòng lặp mới cho đối số đối tượng hoặc chính đối tượng đó nếu đối tượng đã là một trình vòng lặp. Tăng TypeError và trả về NULL nếu đối tượng không thể lặp lại được.

PyObject *PyObject_SelfIter(PyObject *obj)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Điều này tương đương với phương thức __iter__(self): return self của Python. Nó dành cho các loại iterator, được sử dụng trong khe PyTypeObject.tp_iter.

PyObject *PyObject_GetAIter(PyObject *o)¶: 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.10.
Điều này tương đương với biểu thức Python aiter(o). Lấy một đối tượng AsyncIterable và trả về một AsyncIterator cho nó. Đây thường là một trình vòng lặp mới nhưng nếu đối số là AsyncIterator thì đối số này sẽ tự trả về. Tăng TypeError và trả về NULL nếu đối tượng không thể lặp lại được.

Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

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

Nhận một con trỏ tới dữ liệu dành riêng cho lớp con dành riêng cho cls.

Đối tượng o phải là một phiên bản của cls và cls phải được tạo bằng PyType_Spec.basicsize âm. Python không kiểm tra điều này.

Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

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

Trả về kích thước của không gian bộ nhớ phiên bản dành riêng cho cls, tức là trả về kích thước của bộ nhớ PyObject_GetTypeData().

Giá trị này có thể lớn hơn yêu cầu khi sử dụng -PyType_Spec.basicsize; việc sử dụng kích thước lớn hơn này là an toàn (ví dụ: với memset()).

Loại cls must đã được tạo bằng cách sử dụng PyType_Spec.basicsize âm. Python không kiểm tra điều này.

Nếu có lỗi, hãy đặt ngoại lệ và trả về giá trị âm.

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)¶

Nhận con trỏ tới dữ liệu từng mục cho một lớp có Py_TPFLAGS_ITEMS_AT_END.

Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL. TypeError được nâng lên nếu o không được đặt Py_TPFLAGS_ITEMS_AT_END.

Added in version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶

Truy cập từ điển được quản lý của obj.

Hàm này chỉ được gọi trong hàm duyệt thuộc loại có bộ cờ Py_TPFLAGS_MANAGED_DICT.

Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)¶

Xóa từ điển được quản lý của obj.

Hàm này chỉ được gọi trong một hàm rõ ràng thuộc loại có bộ cờ Py_TPFLAGS_MANAGED_DICT.

Added in version 3.13.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

Đâ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ỏ.

Bật deferred reference counting trên obj, nếu được bộ thực thi hỗ trợ. Trong bản dựng free-threaded, điều này cho phép trình thông dịch tránh việc điều chỉnh số tham chiếu đối với obj, điều này có thể cải thiện hiệu suất đa luồng. Sự cân bằng là obj sẽ chỉ được giải phóng bởi trình thu gom rác theo dõi chứ không phải khi trình thông dịch không còn bất kỳ tham chiếu nào đến nó nữa.

Hàm này trả về 1 nếu việc tính tham chiếu hoãn lại được bật trên obj và 0 nếu việc tính tham chiếu hoãn lại không được hỗ trợ hoặc nếu gợi ý bị trình thông dịch bỏ qua, chẳng hạn như khi việc tính tham chiếu hoãn lại đã được bật trên obj. Chức năng này an toàn theo luồng và không thể thất bại.

Chức năng này không thực hiện gì trên các bản dựng có bật GIL, vốn không hỗ trợ việc tính tham chiếu bị trì hoãn. Điều này cũng không có tác dụng gì nếu obj không phải là đối tượng được bộ thu gom rác theo dõi (xem gc.is_tracked() và PyObject_GC_IsTracked()).

Chức năng này dự định sẽ được sử dụng ngay sau khi obj được tạo, bởi mã tạo ra nó, chẳng hạn như trong khe tp_new của đối tượng.

Added in version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

Đâ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ỏ.

Kiểm tra xem obj có phải là đối tượng tạm thời duy nhất không. Trả về 1 nếu obj được biết đến là một đối tượng tạm thời duy nhất và 0 nếu ngược lại. Chức năng này không thể thất bại nhưng việc kiểm tra mang tính thận trọng và có thể trả về 0 trong một số trường hợp ngay cả khi obj là một đối tượng tạm thời duy nhất.

Nếu một đối tượng là tạm thời duy nhất, thì đảm bảo rằng mã hiện tại có tham chiếu duy nhất đến đối tượng. Đối với các đối số của hàm C, nên sử dụng đối số này thay vì kiểm tra xem số tham chiếu có phải là 1 hay không. Bắt đầu với Python 3.14, trình thông dịch nội bộ sẽ tránh một số sửa đổi về số tham chiếu khi tải các đối tượng lên ngăn toán hạng bằng các tham chiếu borrowing khi có thể, điều đó có nghĩa là bản thân số tham chiếu của 1 không đảm bảo rằng một đối số hàm được tham chiếu duy nhất.

Trong ví dụ bên dưới, my_func được gọi với một đối tượng tạm thời duy nhất làm đối số của nó

my_func([1, 2, 3])

Trong ví dụ bên dưới, my_func được gọi là not với một đối tượng tạm thời duy nhất làm đối số, ngay cả khi số lần đếm lại của nó là 1:

my_list = [1, 2, 3]
my_func(my_list)

Xem thêm chức năng Py_REFCNT().

Added in version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: Đâ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ỏ.

Hàm này trả về khác 0 nếu obj là immortal và 0 nếu ngược lại. Chức năng này không thể thất bại.

Ghi chú

Các đối tượng bất tử trong một phiên bản CPython không được đảm bảo sẽ bất tử trong một phiên bản khác.

Added in version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

Đâ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ỏ.

Tăng số lượng tham chiếu của obj nếu nó khác 0. Trả về 1 nếu số tham chiếu của đối tượng được tăng thành công. Nếu không, hàm này trả về 0.

PyUnstable_EnableTryIncRef() phải được gọi trước đó trên obj nếu không hàm này có thể trả về 0 một cách giả mạo trong free-threaded build.

Hàm này tương đương về mặt logic với mã C sau, ngoại trừ việc nó hoạt động nguyên tử trong free-threaded build:

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   trả về 1;
}
trả về 0;

Đây được coi là một khối xây dựng để quản lý các tham chiếu yếu mà không cần sử dụng Python weak reference object.

Thông thường, để sử dụng đúng chức năng này cần có sự hỗ trợ từ bộ giải phóng của obj (tp_dealloc). Ví dụ: bản phác thảo sau có thể được điều chỉnh để triển khai "bản đồ yếu" hoạt động giống như WeakValueDictionary cho một loại cụ thể:

Mutex PyMutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(giá trị);
    yếumap_type bản đồ yếu = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    yếumap_type bản đồ yếu = ...;
    PyMutex_Lock(&mutex);
    PyObject *result =weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` an toàn khi sử dụng
        PyMutex_Unlock(&mutex);
        trả về kết quả;
    }
    // nếu chúng ta đến đây, `result` đang bắt đầu được thu gom rác,
    // nhưng vẫn chưa bị xóa khỏi sơ đồ yếu
    PyMutex_Unlock(&mutex);
    trả về NULL;
}

// hàm tp_dealloc cho các giá trị sơ đồ yếu
trống rỗng
value_dealloc(PyObject *value)
{
    yếumap_type bản đồ yếu = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

Added in version 3.14.

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: Đâ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 phép sử dụng PyUnstable_TryIncRef() tiếp theo trên obj. Người gọi phải giữ strong reference đến obj khi gọi điều này.

Added in version 3.14.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

Đâ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ỏ.

Xác định xem op chỉ có một tài liệu tham khảo.

Trên các bản dựng hỗ trợ GIL, chức năng này tương đương với Py_REFCNT(op) == 1.

Trên free-threaded build, thao tác này sẽ kiểm tra xem reference count của op có bằng 1 hay không và kiểm tra thêm xem op chỉ được sử dụng bởi luồng này hay không. Py_REFCNT(op) == 1 là not an toàn theo luồng trên các bản dựng có luồng tự do; thích chức năng này hơn.

Người gọi phải giữ attached thread state, mặc dù thực tế là hàm này không gọi tới trình thông dịch Python. Chức năng này không thể thất bại.

Added in version 3.14.

Giao thức đối tượng¶

Chủ đề trước

Chủ đề tiếp

Trang này