Объектный протокол

PyObject* Py_NotImplemented

Синглтон NotImplemented, используемый для сигнализации о том, что операция не реализована для данной комбинации типов.

Py_RETURN_NOTIMPLEMENTED

Правильно обрабатывает возвращение Py_NotImplemented из функции C (т. е. увеличивает счётчик ссылок на NotImplemented и возвращает его).

int PyObject_Print(PyObject *o, FILE *fp, int flags)

Распечатывает объект o в файле fp. При ошибке возвращает -1. Аргумент flags используется для включения определенных параметров печати. В настоящее время поддерживается только один вариант — Py_PRINT_RAW; если задано, вместо repr() печатается str() объекта.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Возвращает 1, если у o есть атрибут attr_name, и 0 в противном случае. Это эквивалентно Python выражению hasattr(o, attr_name). Эта функция всегда успешна.

Обратите внимание, что вызываемые исключения при вызове методов __getattr__() и __getattribute__(), будут подавлены. Чтобы получить отчёт об ошибках, использовать вместо неё PyObject_GetAttr().

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

Возвращает 1, если у o есть атрибут attr_name, и 0 в противном случае. Это эквивалентно Python выражению hasattr(o, attr_name). Эта функция всегда успешна.

Обратите внимание, что вызываемые исключения при вызове методов __getattr__() и __getattribute__() и создании временного строкового объекта, будут подавлены. Чтобы получить отчёт об ошибках, используйте вместо неё PyObject_GetAttrString().

PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
Return value: New reference.

Получить атрибут с именем attr_name из объекта o. Возвращает значение атрибута в случае успеха или NULL в случае неудачи. Это эквивалент Python выражения o.attr_name.

PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
Return value: New reference.

Получить атрибут с именем attr_name из объекта o. Возвращает значение атрибута в случае успеха или NULL в случае неудачи. Это эквивалент Python выражения o.attr_name.

PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
Return value: New reference.

Универсальная функция получения атрибута, предназначенная для размещения в слоте tp_getattro типового объекта. Она ищет дескриптор в словаре классов в MRO объекта, а также атрибут в __dict__ объекта (при его наличии). Как указано в Реализация дескрипторов, у дескрипторов данных приоритет над атрибутами экземпляра, а дескрипторы, не являющиеся данными. В противном случае вызывается AttributeError.

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

Устанавливает значение атрибута с именем attr_name для объекта o на значение v. Вызывается исключение и возвращает -1 в случае ошибки; возвращает 0 в случае успеха. Это эквивалент Python оператора o.attr_name = v.

Если v — NULL, атрибут удаляется, однако функция устарела в пользу использования PyObject_DelAttr().

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

Задает для атрибута attr_name для объекта o значение v. Вызывается исключение и возвращает -1 в случае ошибки; возвращает 0 в случае успеха. Это эквивалент оператора Python o.attr_name = v.

Если v — NULL, атрибут удаляется, однако функция устарела в пользу использования PyObject_DelAttrString().

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

Универсальная функция установки и удаления атрибутов, предназначенная для размещения в слоте tp_setattro типового объекта. Она ищет дескриптор данных в словаре классов в MRO объекта и, если он найден, у него преимущество перед установкой или удалением атрибута в словаре экземпляра. В противном случае атрибут устанавливается или удаляется в __dict__ объекта (если присутствует). В случае успеха возвращается 0, в противном случае — AttributeError и возвращается -1.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

Удаляет атрибут с именем attr_name для объекта o. В случае ошибки возвращает -1. Это эквивалент оператора Python del o.attr_name.

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

Удаляет атрибут с именем attr_name для объекта o. В случае ошибки возвращает -1. Это эквивалент оператора Python del o.attr_name.

PyObject* PyObject_GenericGetDict(PyObject *o, void *context)
Return value: New reference.

Общая реализация получателя дескриптора __dict__. При необходимости она создаёт словарь.

Добавлено в версии 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

Общая реализация установщика дескриптора __dict__. Реализация не позволяет удалить словарь.

Добавлено в версии 3.3.

PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Return value: New reference.

Сравнивает значения o1 и o2, используя операцию, определённую opid, которая должна быть одним из Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT или Py_GE, соответствуя <, <=, ==, !=, > или >= соответственно. Это Python эквивалент выражения o1 op o2, где op — оператор, соответствующий opid. Возвращает значение сравнения при успехе или NULL при сбое.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

Сравнение значений o1 и o2, используя операцию, определённую opid, которая должна быть одной из Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT или Py_GE, соответствуя <, <=, ==, !=, > или >= соответственно. Возвращает -1 при ошибке, 0 если у результата ложное значение, 1 в противном случае. Это Python эквивалент выражения o1 op o2, где op — оператор, соответствующий opid.

Примечание

Если o1 и o2 — это один и тот же объект, PyObject_RichCompareBool() всегда будет возвращать 1 для Py_EQ и 0 для Py_NE.

PyObject* PyObject_Repr(PyObject *o)
Return value: New reference.

Вычисляет строковое представление объекта o. Возвращает строковое представление в случае успеха, NULL в случае неудачи. Это эквивалент Python выражения repr(o). Вызывается встроенной функцией repr().

Изменено в версии 3.4: Функция теперь включает утверждение отладки, чтобы гарантировать, что она не отбрасывает активное исключение без уведомления.

PyObject* PyObject_ASCII(PyObject *o)
Return value: New reference.

Как PyObject_Repr(), вычисляет строковое представление объекта o, но экранировать символы, отличные от ASCII, в строке, возвращаемой PyObject_Repr(), с помощью экранирований \x, \u или \U. Генерирует строку, аналогичную возвращаемой PyObject_Repr() в Python 2. Вызывается встроенной функцией ascii().

PyObject* PyObject_Str(PyObject *o)
Return value: New reference.

Вычисляет строковое представление объекта o. Возвращает строковое представление в случае успеха, NULL в случае неудачи. Это эквивалент Python выражения str(o). Вызывается встроенной функцией str() и, следовательно, функцией print().

Изменено в версии 3.4: Данная функция теперь включает утверждение отладки, чтобы гарантировать, что она не отбрасывает активное исключение без уведомления.

PyObject* PyObject_Bytes(PyObject *o)
Return value: New reference.

Вычисляет байтовое представление объекта o. В случае ошибки возвращается NULL, а в случае успеха — объект в байтах. Это эквивалентно выражению Python bytes(o), когда o не является целым числом. В отличие от bytes(o), вызывается TypeError, когда o является целым числом, а не байтовым объектом с нулевой инициализацией.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

Возвращает 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)

Возвращает 1, если inst является экземпляром класса cls или подклассом cls, или 0, если нет. В случае ошибки возвращает -1 и устанавливает исключение.

Если cls является кортежем, проверка будет выполняться для каждой записи в cls. Результатом будет 1, если хотя бы одна из проверок вернёт 1, в противном случае — 0.

Если у cls есть метод __instancecheck__(), он будет вызываться для определения статуса подкласса, как приведено в PEP 3119. В противном случае inst является экземпляром cls, если его класс является подклассом cls.

Экземпляр inst может переопределить то, что считается его классом, используя атрибут __class__.

Объект cls может переопределить, если он считается классом и каковы его базовые классы, с помощью атрибута __bases__ (который должен быть кортежем базовых классов).

int PyCallable_Check(PyObject *o)

Определяет, можно ли вызвать объект o. Возвращает 1, если объект вызываемый, и 0 в противном случае. Функция всегда успешна.

PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
Return value: New reference.

Вызвать вызываемый объект Python callable с аргументами, заданными кортежем args, и именованными аргументами, заданными словарём kwargs.

args не должен быть NULL, использовать пустой кортеж, если аргументы не нужны. Если именованные аргументы не нужны, kwargs может быть NULL.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

Это эквивалент Python выражения: callable(*args, **kwargs).

PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
Return value: New reference.

Вызвать вызываемый объект Python callable с аргументами, заданными кортежем args. Если аргументы не нужны, то args может быть NULL.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

Это эквивалент Python выражения: callable(*args).

PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
Return value: New reference.

Вызвать вызываемый объект Python callable с переменным количеством аргументов C. Аргументы C определяются с использованием строки формата стиля Py_BuildValue(). Формат может быть NULL, что указывает на отсутствие аргументов.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

Это эквивалент Python выражения: callable(*args).

Обратите внимание: если вы передаете только аргументы PyObject *, PyObject_CallFunctionObjArgs() будет более быстрой альтернативой.

Изменено в версии 3.4: Тип format был изменен с char *.

PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
Return value: New reference.

Вызвать метод с именем name объекта obj с переменным числом аргументов C. Аргументы C определяются строкой формата Py_BuildValue(), которая должна создавать кортеж.

Формат может быть NULL, что указывает на отсутствие аргументов.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

Это эквивалент Python выражения: obj.name(arg1, arg2, ...).

Обратите внимание, что если вы передаёте только аргументы PyObject*, PyObject_CallMethodObjArgs() является более быстрой альтернативой.

Изменено в версии 3.4: Типы name и format были изменены с char *.

PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
Return value: New reference.

Вызвать вызываемый объект Python callable с переменным числом аргументов PyObject*. Аргументы представлены как переменное количество параметров, за которыми следует NULL.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

Это эквивалент Python выражения: callable(arg1, arg2, ...).

PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
Return value: New reference.

Вызывает метод объекта Python obj, где имя метода предоставляется как строковый объект Python в name. Он вызывается с переменным числом аргументов PyObject*. Аргументы представлены как переменное количество параметров, за которыми следует NULL.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Вызвать вызываемый объект Python callable, если возможно, используя vectorcall.

args — это массив C с позиционными аргументами.

nargsf — это количество позиционных аргументов плюс необязательный флаг PY_VECTORCALL_ARGUMENTS_OFFSET (см. ниже). Чтобы получить фактическое количество аргументов, используйте PyVectorcall_NARGS(nargsf).

kwnames может быть NULL (без ключевых аргументов) или кортежем ключевых имён. В последнем случае значения ключевых аргументов сохраняются в args после позиционных аргументов. Количество ключевых аргументов не влияет на nargsf.

kwnames должен содержать только объекты типа str (не подкласс), и все ключи должны быть Уникальными.

Возвращает результат вызова в случае успеха или вызвать исключение и возвращает NULL в случае неудачи.

При этом используется протокол vectorcall, если вызываемый объект поддерживает его; в противном случае аргументы преобразуются для использования tp_call.

Примечание

Функция является временной и ожидается, что она станет общедоступной в Python 3.9 с другим именем и, возможно, с измененной семантикой. Если вы используете эту функцию, запланируйте обновление кода для Python 3.9.

Добавлено в версии 3.8.

PY_VECTORCALL_ARGUMENTS_OFFSET

Если задано в аргументе vectorcall nargsf, вызываемому разрешается временно изменять args[-1]. Другими словами, args указывает на аргумент 1 (не 0) в выделенном векторе. Перед возвратом вызываемый должен восстановить значение args[-1].

Когда они могут сделать это дешево (без дополнительного распределения), вызывающим рекомендуется использовать PY_VECTORCALL_ARGUMENTS_OFFSET. Это позволит вызываемым объектам, таким как связанные методы, делать свои последующие вызовы (которые включают добавленный аргумент self) с дешёвыми затратами.

Добавлено в версии 3.8.

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Для аргумента vectorcall nargsf возвращает фактическое количество аргументов. В настоящее время эквивалентно nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET.

Добавлено в версии 3.8.

PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

То же, что и _PyObject_Vectorcall(), за исключением того, что ключевые аргументы передаются как словарь в kwdict. Это может быть NULL, если нет ключевых аргументов.

Для вызываемых объектов, поддерживающих vectorcall, аргументы внутренне преобразуются в соответствии с соглашением vectorcall. Следовательно, функция добавляет некоторые накладные расходы по сравнению с _PyObject_Vectorcall(). Её следует использовать только в том случае, если у вызывающего уже есть готовый к использованию словарь.

Примечание

Функция является временной и ожидается, что она станет общедоступной в Python 3.9 с другим именем и, возможно, с измененной семантикой. Если вы используете эту функцию, запланируйте обновление кода для Python 3.9.

Добавлено в версии 3.8.

Py_hash_t PyObject_Hash(PyObject *o)

Вычисляет и возвращает хеш-значение объекта o. В случае неудачи возвращает -1. Это эквивалент Python выражения hash(o).

Изменено в версии 3.2: Тип возврата теперь Py_hash_t. Это целое число со знаком того же размера, что и Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Устанавливает TypeError, указывающий, что type(o) не хэшируется, и возвращает -1. Функция получает особую обработку при хранении в слоте tp_hash, позволяя типу явно указывать интерпретатору, что он не может быть хэширован.

int PyObject_IsTrue(PyObject *o)

Возвращает 1, если объект o считается истинным, и 0 в противном случае. Это эквивалентно Python выражению not not o. В случае неудачи возвращает -1.

int PyObject_Not(PyObject *o)

Возвращает 0, если объект o считается истинным, и 1 в противном случае. Это эквивалентно Python выражению not o. В случае неудачи возвращает -1.

PyObject* PyObject_Type(PyObject *o)
Return value: New reference.

Если o не является NULL, возвращает объект типа, соответствующий типу объекта o. В случае неудачи вызывает SystemError и возвращает NULL. Это эквивалентно Python выражению type(o). Функция увеличивает счётчик ссылок возвращаемого значения. На самом деле нет причин использовать эту функцию вместо общего выражения o->ob_type, которое возвращает указатель типа PyTypeObject*, за исключением случаев, когда требуется увеличенное количество ссылок.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

Возвращает истину, если у объекта o тип type или подтип type. Оба параметра не должны быть NULL.

Py_ssize_t PyObject_Size(PyObject *o)
Py_ssize_t PyObject_Length(PyObject *o)

Возвращает длину объекта o. Если объект o предоставляет протоколы последовательности и отображения, возвращается длина последовательности. В случае ошибки возвращается -1. Это эквивалент Python выражению len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)

Возвращает примерную длину объекта o. Сначала пытается отдать его фактическую длину, затем оценку с использованием __length_hint__() и, наконец, возвращает значение по умолчанию. При ошибке возвращает -1. Это эквивалент Python выражения operator.length_hint(o, default).

Добавлено в версии 3.4.

PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
Return value: New reference.

Возвращает элемент o, соответствующий объекту key или NULL в случае сбоя. Это эквивалент Python выражения o[key].

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

Сопоставляет объект key со значением v. Вызывает исключение и возвращает -1 в случае ошибки; возвращает 0 в случае успеха. Это эквивалент оператора o[key] = v. Функция не крадёт ссылку на v.

int PyObject_DelItem(PyObject *o, PyObject *key)

Удаляет отображение для объекта key из объекта o. В случае ошибки возвращает -1. Эквивалентно Python выражению del o[key].

PyObject* PyObject_Dir(PyObject *o)
Return value: New reference.

Эквивалентна Python выражению dir(o), возвращающему (возможно, пустой) список строк, соответствующих аргументу объекта, или NULL, если произошла ошибка. Если аргумент — NULL, это похоже на Python dir(), возвращающий имена текущих локальных жителей; в этом случае, если ни один рабочий фрейм не активен, возвращается NULL, но PyErr_Occurred() вернёт ложь.

PyObject* PyObject_GetIter(PyObject *o)
Return value: New reference.

Эквивалентна Python выражению iter(o). Он возвращает новый итератор для аргумента объекта или сам объект, если объект уже является итератором. Вызывает TypeError и возвращает NULL, если объект не может быть повторен.