Об’єктний протокол¶
-
PyObject *Py_GetConstant(unsigned int constant_id)¶
- Part of the Stable ABI since version 3.13.
Get a strong reference to a constant.
Set an exception and return
NULL
if constant_id is invalid.constant_id must be one of these constant identifiers:
Constant Identifier
Значення
Returned object
-
Py_CONSTANT_NONE¶
0
-
Py_CONSTANT_FALSE¶
1
-
Py_CONSTANT_TRUE¶
2
-
Py_CONSTANT_ELLIPSIS¶
3
-
Py_CONSTANT_NOT_IMPLEMENTED¶
4
-
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
()
Numeric values are only given for projects which cannot use the constant identifiers.
Added in version 3.13.
Деталі реалізації CPython: In CPython, all of these constants are immortal.
-
Py_CONSTANT_NONE¶
-
PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶
- Part of the Stable ABI since version 3.13.
Similar to
Py_GetConstant()
, but return a borrowed reference.This function is primarily intended for backwards compatibility: using
Py_GetConstant()
is recommended for new code.The reference is borrowed from the interpreter, and is valid until the interpreter finalization.
Added in version 3.13.
-
PyObject *Py_NotImplemented¶
Синглтон
NotImplemented
, який використовується для сигналу про те, що операція не реалізована для даної комбінації типів.
-
Py_RETURN_NOTIMPLEMENTED¶
Properly handle returning
Py_NotImplemented
from within a C function (that is, create a new strong reference toNotImplemented
and return it).
-
Py_PRINT_RAW¶
Flag to be used with multiple functions that print the object (like
PyObject_Print()
andPyFile_WriteObject()
). If passed, these function would use thestr()
of the object instead of therepr()
.
-
int PyObject_Print(PyObject *o, FILE *fp, int flags)¶
Print an object o, on file fp. Returns
-1
on error. The flags argument is used to enable certain printing options. The only option currently supported isPy_PRINT_RAW
; if given, thestr()
of the object is written instead of therepr()
.
-
int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶
- Part of the Stable ABI since version 3.13.
Returns
1
if o has the attribute attr_name, and0
otherwise. This is equivalent to the Python expressionhasattr(o, attr_name)
. On failure, return-1
.Added in version 3.13.
-
int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶
- Part of the Stable ABI since version 3.13.
This is the same as
PyObject_HasAttrWithError()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.Added in version 3.13.
-
int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶
- Part of the Stable ABI.
Returns
1
if o has the attribute attr_name, and0
otherwise. This function always succeeds.Примітка
Exceptions that occur when this calls
__getattr__()
and__getattribute__()
methods are silently ignored. For proper error handling, usePyObject_HasAttrWithError()
,PyObject_GetOptionalAttr()
orPyObject_GetAttr()
instead.
-
int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶
- Part of the Stable ABI.
This is the same as
PyObject_HasAttr()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.Примітка
Exceptions that occur when this calls
__getattr__()
and__getattribute__()
methods or while creating the temporarystr
object are silently ignored. For proper error handling, usePyObject_HasAttrStringWithError()
,PyObject_GetOptionalAttrString()
orPyObject_GetAttrString()
instead.
-
PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶
- Return value: New reference. Part of the Stable ABI.
Отримати атрибут з назвою attr_name з об’єкта o. Повертає значення атрибута в разі успіху або
NULL
у разі невдачі. Це еквівалент виразу Pythono.attr_name
.If the missing attribute should not be treated as a failure, you can use
PyObject_GetOptionalAttr()
instead.
-
PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶
- Return value: New reference. Part of the Stable ABI.
This is the same as
PyObject_GetAttr()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.If the missing attribute should not be treated as a failure, you can use
PyObject_GetOptionalAttrString()
instead.
-
int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶
- Part of the Stable ABI since version 3.13.
Variant of
PyObject_GetAttr()
which doesn’t raiseAttributeError
if the attribute is not found.If the attribute is found, return
1
and set *result to a new strong reference to the attribute. If the attribute is not found, return0
and set *result toNULL
; theAttributeError
is silenced. If an error other thanAttributeError
is raised, return-1
and set *result toNULL
.Added in version 3.13.
-
int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶
- Part of the Stable ABI since version 3.13.
This is the same as
PyObject_GetOptionalAttr()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.Added in version 3.13.
-
PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶
- Return value: New reference. Part of the Stable ABI.
Загальна функція отримання атрибутів, яка призначена для розміщення в слоті
tp_getattro
об’єкта типу. Він шукає дескриптор у словнику класів у MRO об’єкта, а також атрибут у__dict__
об’єкта (якщо є). Як зазначено в Реалізація дескрипторів, дескриптори даних мають перевагу над атрибутами екземплярів, тоді як дескриптори, що не є даними, ні. В іншому випадку виникає помилкаAttributeError
.
-
int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶
- Part of the Stable ABI.
Установіть значення атрибута attr_name для об’єкта o на значення v. Викликати виняток і повертати
-1
у разі помилки; повернути0
в разі успіху. Це еквівалент оператора Pythono.attr_name = v
.Якщо v має значення
NULL
, атрибут видаляється. Ця поведінка застаріла на користь використанняPyObject_DelAttr()
, але наразі немає планів її видалення.
-
int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶
- Part of the Stable ABI.
This is the same as
PyObject_SetAttr()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.Якщо v має значення
NULL
, атрибут видаляється, але ця функція застаріла на користь використанняPyObject_DelAttrString()
.The number of different attribute names passed to this function should be kept small, usually by using a statically allocated string as attr_name. For attribute names that aren’t known at compile time, prefer calling
PyUnicode_FromString()
andPyObject_SetAttr()
directly. For more details, seePyUnicode_InternFromString()
, which may be used internally to create a key object.
-
int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶
- Part of the Stable ABI.
Загальна функція встановлення та видалення атрибутів, яка призначена для розміщення в слоті
tp_setattro
об’єкта типу. Він шукає дескриптор даних у словнику класів у MRO об’єкта, і якщо його знайдено, він надає перевагу над налаштуванням або видаленням атрибута в словнику екземпляра. В іншому випадку атрибут встановлюється або видаляється в об’єкті__dict__
(якщо є). У разі успіху повертається0
, інакше виникаєAttributeError
і повертається-1
.
-
int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶
- Part of the Stable ABI since version 3.13.
Видалити атрибут з назвою attr_name для об’єкта o. Повертає
-1
у разі помилки. Це еквівалент оператора Pythondel o.attr_name
.
-
int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶
- Part of the Stable ABI since version 3.13.
This is the same as
PyObject_DelAttr()
, but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.The number of different attribute names passed to this function should be kept small, usually by using a statically allocated string as attr_name. For attribute names that aren’t known at compile time, prefer calling
PyUnicode_FromString()
andPyObject_DelAttr()
directly. For more details, seePyUnicode_InternFromString()
, which may be used internally to create a key object for lookup.
-
PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶
- Return value: New reference. Part of the Stable ABI since version 3.10.
Загальна реалізація засобу отримання дескриптора
__dict__
. Він створює словник, якщо це необхідно.This function may also be called to get the
__dict__
of the object o. PassNULL
for context when calling it. Since this function may need to allocate memory for the dictionary, it may be more efficient to callPyObject_GetAttr()
when accessing an attribute on the object.On failure, returns
NULL
with an exception set.Added in version 3.3.
-
int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶
- Part of the Stable ABI since version 3.7.
Загальна реалізація засобу налаштування дескриптора
__dict__
. Ця реалізація не дозволяє видаляти словник.Added in version 3.3.
-
PyObject **_PyObject_GetDictPtr(PyObject *obj)¶
Return a pointer to
__dict__
of the object obj. If there is no__dict__
, returnNULL
without setting an exception.This function may need to allocate memory for the dictionary, so it may be more efficient to call
PyObject_GetAttr()
when accessing an attribute on the object.
-
PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶
- Return value: New reference. Part of the Stable ABI.
Compare the values of o1 and o2 using the operation specified by opid, which must be one of
Py_LT
,Py_LE
,Py_EQ
,Py_NE
,Py_GT
, orPy_GE
, corresponding to<
,<=
,==
,!=
,>
, or>=
respectively. This is the equivalent of the Python expressiono1 op o2
, whereop
is the operator corresponding to opid. Returns the value of the comparison on success, orNULL
on failure.
-
int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶
- Part of the Stable ABI.
Compare the values of o1 and o2 using the operation specified by opid, like
PyObject_RichCompare()
, but returns-1
on error,0
if the result is false,1
otherwise.
Примітка
If o1 and o2 are the same object, PyObject_RichCompareBool()
will always return 1
for Py_EQ
and 0
for Py_NE
.
-
PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶
- Part of the Stable ABI.
Format obj using format_spec. This is equivalent to the Python expression
format(obj, format_spec)
.format_spec may be
NULL
. In this case the call is equivalent toformat(obj)
. Returns the formatted string on success,NULL
on failure.
-
PyObject *PyObject_Repr(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Обчислити рядкове представлення об’єкта o. Повертає рядкове представлення в разі успіху,
NULL
у разі невдачі. Це еквівалент виразу Pythonrepr(o)
. Викликається вбудованою функцієюrepr()
.Змінено в версії 3.4: Ця функція тепер включає твердження налагодження, щоб гарантувати, що вона не відкидає мовчки активний виняток.
-
PyObject *PyObject_ASCII(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Як
PyObject_Repr()
, обчислити рядкове представлення об’єкта o, але екранувати символи, відмінні від ASCII, у рядку, який повертаєPyObject_Repr()
, за допомогою\x
,\u
або\U
екранується. Це створює рядок, подібний до того, який повертаєPyObject_Repr()
у Python 2. Викликається вбудованою функцієюascii()
.
-
PyObject *PyObject_Str(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Обчислити рядкове представлення об’єкта o. Повертає рядкове представлення в разі успіху,
NULL
у разі невдачі. Це еквівалент виразу Pythonstr(o)
. Викликається вбудованою функцієюstr()
і, отже, функцієюprint()
.Змінено в версії 3.4: Ця функція тепер включає твердження налагодження, щоб гарантувати, що вона не відкидає мовчки активний виняток.
-
PyObject *PyObject_Bytes(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Обчисліть байтове представлення об’єкта o. У разі помилки повертається
NULL
, а в разі успіху — об’єкт bytes. Це еквівалентно виразу Pythonbytes(o)
, коли o не є цілим числом. На відміну відbytes(o)
, помилка TypeError виникає, коли o є цілим числом замість об’єкта bytes, ініціалізованого нулем.
-
int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶
- Part of the Stable ABI.
Повертає
1
, якщо клас derived ідентичний або походить від класу cls, інакше повертає0
. У разі помилки поверніть-1
.Якщо cls є кортежем, перевірятиметься кожен запис у cls. Результатом буде
1
, якщо хоча б одна з перевірок повертає1
, інакше він буде0
.If cls has a
__subclasscheck__()
method, it will be called to determine the subclass status as described in PEP 3119. Otherwise, derived is a subclass of cls if it is a direct or indirect subclass, i.e. contained incls.__mro__
.Normally only class objects, i.e. instances of
type
or a derived class, are considered classes. However, objects can override this by having a__bases__
attribute (which must be a tuple of base classes).
-
int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶
- Part of the Stable ABI.
Повертає
1
, якщо inst є екземпляром класу cls або підкласом cls, або0
, якщо ні. У разі помилки повертає-1
і встановлює виняток.Якщо cls є кортежем, перевірятиметься кожен запис у cls. Результатом буде
1
, якщо хоча б одна з перевірок повертає1
, інакше він буде0
.If cls has a
__instancecheck__()
method, it will be called to determine the subclass status as described in PEP 3119. Otherwise, inst is an instance of cls if its class is a subclass of cls.An instance inst can override what is considered its class by having a
__class__
attribute.An object cls can override if it is considered a class, and what its base classes are, by having a
__bases__
attribute (which must be a tuple of base classes).
-
Py_hash_t PyObject_Hash(PyObject *o)¶
- Part of the Stable ABI.
Обчислити та повернути хеш-значення об’єкта o. У разі помилки поверніть
-1
. Це еквівалент виразу Pythonhash(o)
.Змінено в версії 3.2: Тип повернення тепер Py_hash_t. Це ціле число зі знаком такого ж розміру, як
Py_ssize_t
.
-
Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶
- Part of the Stable ABI.
Set a
TypeError
indicating thattype(o)
is not hashable and return-1
. This function receives special treatment when stored in atp_hash
slot, allowing a type to explicitly indicate to the interpreter that it is not hashable.
-
int PyObject_IsTrue(PyObject *o)¶
- Part of the Stable ABI.
Повертає
1
, якщо об’єкт o вважається істинним, і0
в іншому випадку. Це еквівалентно виразу Pythonnot not o
. У разі помилки поверніть-1
.
-
int PyObject_Not(PyObject *o)¶
- Part of the Stable ABI.
Повертає
0
, якщо об’єкт o вважається істинним, і1
інакше. Це еквівалентно виразу Pythonnot o
. У разі помилки поверніть-1
.
-
PyObject *PyObject_Type(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
When o is non-
NULL
, returns a type object corresponding to the object type of object o. On failure, raisesSystemError
and returnsNULL
. This is equivalent to the Python expressiontype(o)
. This function creates a new strong reference to the return value. There’s really no reason to use this function instead of thePy_TYPE()
function, which returns a pointer of type PyTypeObject*, except when a new strong reference is needed.
-
int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶
Повертає відмінне від нуля значення, якщо об’єкт o має тип type або підтип type, і
0
інакше. Обидва параметри не мають бутиNULL
.
-
Py_ssize_t PyObject_Size(PyObject *o)¶
-
Py_ssize_t PyObject_Length(PyObject *o)¶
- Part of the Stable ABI.
Повертає довжину об’єкта o. Якщо об’єкт o надає протоколи послідовності та відображення, повертається довжина послідовності. У разі помилки повертається
-1
. Це еквівалент виразу Pythonlen(o)
.
-
Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶
Повертає приблизну довжину об’єкта o. Спочатку спробуйте повернути його фактичну довжину, потім оцінку за допомогою
__length_hint__()
і, нарешті, поверніть значення за замовчуванням. У разі помилки повертає-1
. Це еквівалент виразу Pythonoperator.length_hint(o, defaultvalue)
.Added in version 3.4.
-
PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶
- Return value: New reference. Part of the Stable ABI.
Повертає елемент o, що відповідає об’єкту key або
NULL
у разі помилки. Це еквівалент виразу Pythono[key]
.
-
int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶
- Part of the Stable ABI.
Зіставте об’єкт key на значення v. Викликати виняток і повертати
-1
у разі помилки; повернути0
в разі успіху. Це еквівалент оператора Pythono[key] = v
. Ця функція не викрадає посилання на v.
-
int PyObject_DelItem(PyObject *o, PyObject *key)¶
- Part of the Stable ABI.
Видаліть зіставлення для об’єкта key з об’єкта o. Повернути
-1
у разі помилки. Це еквівалентно оператору Pythondel o[key]
.
-
PyObject *PyObject_Dir(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Це еквівалентно виразу Python
dir(o)
, який повертає (можливо, порожній) список рядків, відповідних для аргументу об’єкта, абоNULL
, якщо була помилка. Якщо аргументNULL
, це схоже наdir()
Python, що повертає імена поточних локальних систем; у цьому випадку, якщо жоден кадр виконання не активний, повертаєтьсяNULL
, алеPyErr_Occurred()
повертатиме false.
-
PyObject *PyObject_GetIter(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Це еквівалентно виразу Python
iter(o)
. Він повертає новий ітератор для аргументу об’єкта або сам об’єкт, якщо об’єкт уже є ітератором. ВикликаєTypeError
і повертаєNULL
, якщо об’єкт не можна повторити.
-
PyObject *PyObject_GetAIter(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI since version 3.10.
Це еквівалент виразу Python
aiter(o)
. Бере об’єктAsyncIterable
і повертає для ньогоAsyncIterator
. Зазвичай це новий ітератор, але якщо аргументом єAsyncIterator
, він повертає сам себе. ВикликаєTypeError
і повертаєNULL
, якщо об’єкт не можна повторити.Added in version 3.10.
-
void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶
- Part of the Stable ABI since version 3.12.
Get a pointer to subclass-specific data reserved for cls.
The object o must be an instance of cls, and cls must have been created using negative
PyType_Spec.basicsize
. Python does not check this.On error, set an exception and return
NULL
.Added in version 3.12.
-
Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶
- Part of the Stable ABI since version 3.12.
Return the size of the instance memory space reserved for cls, i.e. the size of the memory
PyObject_GetTypeData()
returns.This may be larger than requested using
-PyType_Spec.basicsize
; it is safe to use this larger size (e.g. withmemset()
).The type cls must have been created using negative
PyType_Spec.basicsize
. Python does not check this.On error, set an exception and return a negative value.
Added in version 3.12.
-
void *PyObject_GetItemData(PyObject *o)¶
Get a pointer to per-item data for a class with
Py_TPFLAGS_ITEMS_AT_END
.On error, set an exception and return
NULL
.TypeError
is raised if o does not havePy_TPFLAGS_ITEMS_AT_END
set.Added in version 3.12.
-
int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶
Visit the managed dictionary of obj.
This function must only be called in a traverse function of the type which has the
Py_TPFLAGS_MANAGED_DICT
flag set.Added in version 3.13.
-
void PyObject_ClearManagedDict(PyObject *obj)¶
Clear the managed dictionary of obj.
This function must only be called in a traverse function of the type which has the
Py_TPFLAGS_MANAGED_DICT
flag set.Added in version 3.13.