Протокол объекта

PyObject* Py_NotImplemented

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

Py_RETURN_NOTIMPLEMENTED

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

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

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

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)

Значение возврата: Новая ссылка.

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

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

Значение возврата: Новая ссылка.

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

PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)

Значение возврата: Новая ссылка.

Функция-получатель атрибутов по умолчанию, предназначенная для размещения в слоте 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)

Значение возврата: Новая ссылка.

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

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

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

Реализация по умолчанию для установки __dict__ дескриптора. Эта реализация не позволяет удалять словарь.

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

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

Значение возврата: Новая ссылка.

Сравнить значения 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.

PyObject* PyObject_Repr(PyObject *o)

Значение возврата: Новая ссылка.

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

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

PyObject* PyObject_ASCII(PyObject *o)

Значение возврата: Новый ссылка.

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

PyObject* PyObject_Str(PyObject *o)

Значение возврата: Новый ссылка.

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

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

PyObject* PyObject_Bytes(PyObject *o)

Значение возврата: Новый ссылка.

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

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)

Значение возврата: Новый ссылка.

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

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

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

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

PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)

Значение возврата: Новый ссылка.

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

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

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

PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)

Значение возврата: Новый ссылка.

Вызывает вызываемый объект 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, ...)

Значение возврата: Новый ссылка.

Вызывает метод с именем 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, ...)

Значение возврата: Новый ссылка.

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

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

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

PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

Значение возврата: Новый ссылка.

Вызывает метод объекта Python obj, где имя метода задаётся как объект Python string в 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

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

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

Введено в версии 3.8.

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Принимая во внимание аргумент nargsf вызова vectorcall, возвращает фактическое количество аргументов. В настоящее время эквивалентно 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)

Значение возврата: Новая ссылка.

Если 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)

Значение возврата: Новая ссылка.

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

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

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

int PyObject_DelItem(PyObject *o, PyObject *key)

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

PyObject* PyObject_Dir(PyObject *o)

Значение возврата: Новая ссылка.

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

PyObject* PyObject_GetIter(PyObject *o)

Значение возврата: Новая ссылка.

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