Протокол объекта¶
-
PyObject *Py_GetConstant(unsigned int constant_id)¶
- Часть Стабильный ABI с версии 3.13.
Приведите strong reference к константе.
Установите исключение и верните
NULL
, если constant_id недействителен.constant_id должен быть одним из этих идентификаторов констант:
Постоянный идентификатор
Значение
Возвращаемый объект
-
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
()
Числовые значения приводятся только для проектов, которые не могут использовать постоянные идентификаторы.
Added in version 3.13.
Детали реализации CPython: В CPython все эти константы имеют значение immortal.
-
Py_CONSTANT_NONE¶
-
PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶
- Часть Стабильный ABI с версии 3.13.
Аналогично
Py_GetConstant()
, но возвращает borrowed reference.Эта функция предназначена в первую очередь для обратной совместимости: для нового кода рекомендуется использовать
Py_GetConstant()
.Ссылка заимствуется из интерпретатора и действует до завершения работы интерпретатора. … versionadded:: 3.13
-
PyObject *Py_NotImplemented¶
Синглтон
NotImplemented
, используемый для сигнализации о том, что операция не реализована для данной комбинации типов.
-
Py_RETURN_NOTIMPLEMENTED¶
Правильно обрабатывайте возврат
Py_NotImplemented
внутри функции C (то есть создавайте новые strong reference -NotImplemented
и возвращайте их).
-
Py_PRINT_RAW¶
Флаг для использования с несколькими функциями, печатающими объект (например,
PyObject_Print()
иPyFile_WriteObject()
). Если флаг передан, эти функции будут использоватьstr()
объекта вместоrepr()
.
-
int PyObject_Print(PyObject *o, FILE *fp, int flags)¶
Печать объекта o в файл fp. При ошибке возвращает
-1
. Аргумент flags используется для включения определенных опций печати. В настоящее время поддерживается только параметрPy_PRINT_RAW
; если он задан, то вместоrepr()
записываетсяstr()
объекта.
-
int PyObject_HasAttrWithError(PyObject *o, const char *attr_name)¶
- Часть Стабильный ABI с версии 3.13.
Возвращает
1
, если o имеет атрибут attr_name, и0
в противном случае. Это эквивалентно выражениюhasattr(o, attr_name)
в Python. В случае неудачи возвращается-1
.Added in version 3.13.
-
int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶
- Часть Стабильный ABI с версии 3.13.
Это то же самое, что и
PyObject_HasAttrWithError()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.Added in version 3.13.
-
int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶
- Часть Стабильный ABI.
Возвращает
1
, если o имеет атрибут attr_name, и0
в противном случае. Эта функция всегда успешна.Примечание
Исключения, возникающие при вызове методов
__getattr__()
и__getattribute__()
, молча игнорируются. Для правильной обработки ошибок используйте вместо них методыPyObject_HasAttrWithError()
,PyObject_GetOptionalAttr()
илиPyObject_GetAttr()
.
-
int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶
- Часть Стабильный ABI.
Это то же самое, что и
PyObject_HasAttr()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.Примечание
Исключения, возникающие при вызове методов
__getattr__()
и__getattribute__()
или при создании временного объектаstr
, молча игнорируются. Для правильной обработки ошибок используйте вместо этогоPyObject_HasAttrStringWithError()
,PyObject_GetOptionalAttrString()
илиPyObject_GetAttrString()
.
-
PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Получение атрибута с именем attr_name из объекта o. Возвращает значение атрибута в случае успеха или
NULL
в случае неудачи. Это эквивалентно выражениюo.attr_name
в Python.Если отсутствующий атрибут не должен рассматриваться как сбой, вместо него можно использовать
PyObject_GetOptionalAttr()
.
-
PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Это то же самое, что и
PyObject_GetAttr()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.Если отсутствующий атрибут не должен рассматриваться как сбой, вместо него можно использовать
PyObject_GetOptionalAttrString()
.
-
int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶
- Часть Стабильный ABI с версии 3.13.
Вариант
PyObject_GetAttr()
, который не поднимаетAttributeError
, если атрибут не найден.Если атрибут найден, верните
1
и установите *результат в новый strong reference для атрибута. Если атрибут не найден, верните0
и установите *результат вNULL
;AttributeError
затихает. Если возникла ошибка, отличная отAttributeError
, верните-1
и установите *результат вNULL
.Added in version 3.13.
-
int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶
- Часть Стабильный ABI с версии 3.13.
Это то же самое, что и
PyObject_GetOptionalAttr()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.Added in version 3.13.
-
PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Общая функция получения атрибутов, предназначенная для размещения в слоте
tp_getattro
объекта типа. Она ищет дескриптор в словаре классов в MRO объекта, а также атрибут в__dict__
объекта (если он есть). Как указано в Реализация дескрипторов, дескрипторы данных имеют предпочтение перед атрибутами экземпляра, а дескрипторы, не содержащие данных, - нет. В противном случае возникает ошибкаAttributeError
.
-
int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶
- Часть Стабильный ABI.
Установите значение атрибута с именем attr_name для объекта o в значение v. Вызывает исключение и возвращает
-1
при неудаче; возвращает0
при успехе. Это эквивалентно выражениюo.attr_name = v
в языке Python.Если v равно
NULL
, атрибут удаляется. Это поведение устарело в пользу использованияPyObject_DelAttr()
, но в настоящее время его не планируется удалять.
-
int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶
- Часть Стабильный ABI.
Это то же самое, что и
PyObject_SetAttr()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.Если v равно
NULL
, атрибут будет удален, но эта функция устарела в пользу использованияPyObject_DelAttrString()
.
-
int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶
- Часть Стабильный ABI.
Общая функция установки и удаления атрибутов, предназначенная для размещения в слоте
tp_setattro
объекта типа. Она ищет дескриптор данных в словаре классов в MRO объекта, и если находит, то отдает предпочтение установке или удалению атрибута в словаре экземпляров. В противном случае атрибут устанавливается или удаляется в__dict__
объекта (если он есть). В случае успеха возвращается0
, в противном случае возникает ошибкаAttributeError
и возвращается-1
.
-
int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶
- Часть Стабильный ABI с версии 3.13.
Удаление атрибута с именем attr_name для объекта o. Возвращает
-1
при неудаче. Это эквивалентно выражениюdel o.attr_name
в языке Python.
-
int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶
- Часть Стабильный ABI с версии 3.13.
Это то же самое, что и
PyObject_DelAttr()
, но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.
-
PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.10.
Общая реализация для геттера дескриптора
__dict__
. При необходимости он создает словарь.Эта функция также может быть вызвана для получения
__dict__
объекта o. При вызове передавайтеNULL
для контекста. Поскольку этой функции может потребоваться выделение памяти для словаря, более эффективным будет вызовPyObject_GetAttr()
при обращении к атрибуту объекта.В случае неудачи возвращается
NULL
с набором исключений.Added in version 3.3.
-
int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶
- Часть Стабильный ABI с версии 3.7.
Общая реализация для сеттера дескриптора
__dict__
. Эта реализация не позволяет удалять словарь.Added in version 3.3.
-
PyObject **_PyObject_GetDictPtr(PyObject *obj)¶
Возвращает указатель на
__dict__
объекта obj. Если нет__dict__
, вернитеNULL
, не устанавливая исключения.Этой функции может потребоваться выделение памяти для словаря, поэтому при обращении к атрибуту объекта эффективнее вызывать
PyObject_GetAttr()
.
-
PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Сравните значения o1 и o2, используя операцию, указанную opid, которая должна быть одной из
Py_LT
,Py_LE
,Py_EQ
,Py_NE
,Py_GT
илиPy_GE
, соответствующих<
,<=
,==
,!=
,>
или>=
соответственно. Это эквивалентно выражению Pythono1 op o2
, гдеop
- оператор, соответствующий opid. Возвращает значение сравнения в случае успеха илиNULL
в случае неудачи.
-
int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶
- Часть Стабильный ABI.
Сравнивает значения o1 и o2 с помощью операции, указанной opid, как
PyObject_RichCompare()
, но возвращает-1
при ошибке,0
, если результат ложный,1
в противном случае.
Примечание
Если o1 и o2 - один и тот же объект, PyObject_RichCompareBool()
всегда будет возвращать 1
для Py_EQ
и 0
для Py_NE
.
-
PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶
- Часть Стабильный ABI.
Отформатируйте obj с помощью format_spec. Это эквивалентно выражению Python
format(obj, format_spec)
.format_spec может иметь значение
NULL
. В этом случае вызов эквивалентенformat(obj)
. Возвращает отформатированную строку при успехе,NULL
при неудаче.
-
PyObject *PyObject_Repr(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Вычислите строковое представление объекта o. При успехе возвращает строковое представление, при неудаче -
NULL
. Это эквивалентно выражениюrepr(o)
в Python. Вызывается встроенной функциейrepr()
.Изменено в версии 3.4: Эта функция теперь включает отладочное утверждение, чтобы гарантировать, что она не будет молча отбрасывать активное исключение.
-
PyObject *PyObject_ASCII(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Как и
PyObject_Repr()
, вычислите строковое представление объекта o, но экранируйте символы, не относящиеся к ASCII, в строке, возвращаемойPyObject_Repr()
, с помощью\x
,\u
или\U
эскейпов. Получается строка, аналогичная той, что возвращаетPyObject_Repr()
в Python 2. Вызывается встроенной функциейascii()
.
-
PyObject *PyObject_Str(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Вычислите строковое представление объекта o. При успехе возвращает строковое представление, при неудаче -
NULL
. Это эквивалентно выражениюstr(o)
в Python. Вызывается встроенной функциейstr()
и, следовательно, функциейprint()
.Изменено в версии 3.4: Эта функция теперь включает отладочное утверждение, чтобы гарантировать, что она не будет молча отбрасывать активное исключение.
-
PyObject *PyObject_Bytes(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Вычислить байтовое представление объекта o. В случае неудачи возвращается
NULL
, а в случае успеха - байтовый объект. Это эквивалентно выражению Pythonbytes(o)
, когда o не является целым числом. В отличие отbytes(o)
, когда o является целым числом, а не нуль-инициализированным объектом bytes, возникает ошибка типа TypeError.
-
int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶
- Часть Стабильный ABI.
Верните
1
, если класс derived идентичен или производен от класса cls, в противном случае верните0
. В случае ошибки возвращается-1
.Если cls - кортеж, то проверка будет выполнена для каждой записи в cls. Результатом будет
1
, если хотя бы одна из проверок вернет1
, иначе -0
.Если у cls есть метод
__subclasscheck__()
, он будет вызван для определения статуса подкласса, как описано в PEP 3119. В противном случае derived является подклассом cls, если он является прямым или косвенным подклассом, т. е. содержится вcls.__mro__
.Обычно классами считаются только объекты классов, то есть экземпляры
type
или производного класса. Однако объекты могут отменить это, имея атрибут__bases__
(который должен быть кортежем базовых классов).
-
int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶
- Часть Стабильный ABI.
Возвращает
1
, если inst является экземпляром класса cls или подкласса cls, или0
, если нет. При ошибке возвращается-1
и устанавливается исключение.Если cls - кортеж, то проверка будет выполнена для каждой записи в cls. Результатом будет
1
, если хотя бы одна из проверок вернет1
, иначе -0
.Если у cls есть метод
__instancecheck__()
, он будет вызван для определения статуса подкласса, как описано в PEP 3119. В противном случае inst является экземпляром cls, если его класс является подклассом cls.Экземпляр inst может переопределить то, что считается его классом, имея атрибут
__class__
.Объект cls может переопределить, считается ли он классом и каковы его базовые классы, с помощью атрибута
__bases__
(который должен представлять собой кортеж базовых классов).
-
Py_hash_t PyObject_Hash(PyObject *o)¶
- Часть Стабильный ABI.
Вычислите и верните хэш-значение объекта o. В случае неудачи возвращается
-1
. Это эквивалентно выражениюhash(o)
в Python.Изменено в версии 3.2: Возвращаемый тип теперь Py_hash_t. Это знаковое целое число того же размера, что и
Py_ssize_t
.
-
Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶
- Часть Стабильный ABI.
Установите
TypeError
, указывающий на то, чтоtype(o)
не является hashable, и верните-1
. Эта функция получает особое обращение, когда хранится в слотеtp_hash
, позволяя типу явно указать интерпретатору, что он не является хэшируемым.
-
int PyObject_IsTrue(PyObject *o)¶
- Часть Стабильный ABI.
Возвращает
1
, если объект o считается истинным, и0
в противном случае. Это эквивалентно выражениюnot not o
в Python. В случае неудачи возвращается-1
.
-
int PyObject_Not(PyObject *o)¶
- Часть Стабильный ABI.
Возвращает
0
, если объект o считается истинным, и1
в противном случае. Это эквивалентно выражениюnot o
в Python. В случае неудачи возвращается-1
.
-
PyObject *PyObject_Type(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Если o не``NULL``, возвращает объект типа, соответствующего типу объекта o. В случае неудачи вызывает
SystemError
и возвращаетNULL
. Это эквивалентно выражениюtype(o)
в Python. Эта функция создает новый strong reference для возвращаемого значения. На самом деле нет причин использовать эту функцию вместо функцииPy_TYPE()
, которая возвращает указатель типа PyTypeObject*, за исключением случаев, когда требуется новый strong reference.
-
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)¶
- Часть Стабильный ABI.
Возвращает длину объекта o. Если объект o предоставляет протоколы последовательности и отображения, возвращается длина последовательности. При ошибке возвращается
-1
. Это эквивалентно выражениюlen(o)
в Python.
-
Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶
Возвращает оценочную длину для объекта o. Сначала попробуйте вернуть его фактическую длину, затем оценочную, используя
__length_hint__()
, и, наконец, верните значение по умолчанию. При ошибке возвращается-1
. Это эквивалентно выражениюoperator.length_hint(o, defaultvalue)
в Python.Added in version 3.4.
-
PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает элемент o, соответствующий объекту key, или
NULL
при неудаче. Это эквивалентно выражениюo[key]
в Python.
-
int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶
- Часть Стабильный ABI.
Сопоставьте объект key со значением v. При неудаче вызывает исключение и возвращает
-1
; при успехе возвращает0
. Это эквивалентно выражениюo[key] = v
в Python. Эта функция не крадет ссылку на v.
-
int PyObject_DelItem(PyObject *o, PyObject *key)¶
- Часть Стабильный ABI.
Удалить отображение для объекта key из объекта o. При неудаче возвращается
-1
. Это эквивалентно выражениюdel o[key]
в языке Python.
-
PyObject *PyObject_Dir(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Это эквивалентно выражению Python
dir(o)
, возвращающему (возможно, пустой) список строк, соответствующих аргументу object, илиNULL
, если произошла ошибка. Если аргумент равенNULL
, то это похоже на выражение Pythondir()
, возвращающее имена текущих локалей; в этом случае, если ни один кадр выполнения не активен, возвращаетсяNULL
, аPyErr_Occurred()
вернет false.
-
PyObject *PyObject_GetIter(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Это эквивалентно выражению
iter(o)
в Python. Возвращает новый итератор для аргумента object или сам объект, если объект уже является итератором. ВызываетTypeError
и возвращаетNULL
, если объект не может быть итератором.
-
PyObject *PyObject_GetAIter(PyObject *o)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.10.
Это эквивалентно выражению
aiter(o)
в Python. Принимает объектAsyncIterable
и возвращает для негоAsyncIterator
. Обычно это новый итератор, но если аргументом являетсяAsyncIterator
, он возвращает сам себя. ВызываетTypeError
и возвращаетNULL
, если объект не может быть итерирован.Added in version 3.10.
-
void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶
- Часть Стабильный ABI с версии 3.12.
Получает указатель на данные, специфичные для подкласса, зарезервированные для cls.
Объект o должен быть экземпляром cls, а cls должен быть создан с помощью отрицательного
PyType_Spec.basicsize
. Python не проверяет это.При ошибке установите исключение и верните
NULL
.Added in version 3.12.
-
Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶
- Часть Стабильный ABI с версии 3.12.
Возвращает размер пространства памяти экземпляра, зарезервированного для cls, то есть размер возвращаемой памяти
PyObject_GetTypeData()
.Этот размер может быть больше, чем при использовании
-PyType_Spec.basicsize
; безопасно использовать этот больший размер (например, с помощьюmemset()
).Тип cls должен быть создан с помощью отрицательного
PyType_Spec.basicsize
. Python не проверяет это.При ошибке создайте исключение и верните отрицательное значение.
Added in version 3.12.
-
void *PyObject_GetItemData(PyObject *o)¶
Получите указатель на данные по каждому элементу для класса с
Py_TPFLAGS_ITEMS_AT_END
.При ошибке устанавливается исключение и возвращается
NULL
.TypeError
поднимается, если у o не установленPy_TPFLAGS_ITEMS_AT_END
.Added in version 3.12.
-
int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶
Посетите управляемый словарь obj.
Эта функция должна вызываться только в функции траверса того типа, у которого установлен флаг
Py_TPFLAGS_MANAGED_DICT
.Added in version 3.13.
-
void PyObject_ClearManagedDict(PyObject *obj)¶
Очистить управляемый словарь obj.
Эта функция должна вызываться только в функции траверса того типа, у которого установлен флаг
Py_TPFLAGS_MANAGED_DICT
.Added in version 3.13.