Протокол объектов¶Object Protocol

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). Эта функция всегда завершается успешно.

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

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

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

int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)¶

Сравнивает значения o1 и o2 с помощью процедуры, предоставленной o1, если таковая существует, в противном случае – с помощью процедуры, предоставленной o2. Результат сравнения возвращается в result. В случае ошибки возвращает -1. Это эквивалент оператора Python result = cmp(o1, o2).

int PyObject_Compare(PyObject *o1, PyObject *o2)¶

Сравнивает значения o1 и o2 с помощью процедуры, предоставленной o1, если таковая существует, в противном случае – с помощью процедуры, предоставленной o2. В случае успеха возвращает результат сравнения. При ошибке возвращаемое значение не определено; используйте PyErr_Occurred() для обнаружения ошибки. Это эквивалент выражения Python cmp(o1, o2).

PyObject* PyObject_Repr(PyObject *o)¶

Возвращаемое значение: новая ссылка.

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

PyObject* PyObject_Str(PyObject *o)¶

Возвращаемое значение: новая ссылка.

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

PyObject* PyObject_Bytes(PyObject *o)¶

Вычисляет байтовое представление объекта o. В Python 2.x это просто псевдоним для PyObject_Str().

PyObject* PyObject_Unicode(PyObject *o)¶

Возвращаемое значение: новая ссылка.

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

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

Returns 1 if inst is an instance of the class cls or a subclass of cls, or 0 if not. On error, returns -1 and sets an exception. If cls is a type object rather than a class object, PyObject_IsInstance() returns 1 if inst is of type cls. If cls is a tuple, the check will be done against every entry in cls. The result will be 1 when at least one of the checks returns 1, otherwise it will be 0. If inst is not a class instance and cls is neither a type object, nor a class object, nor a tuple, inst must have a __class__ attribute – the class relationship of the value of that attribute with cls will be used to determine the result of this function.

Новое в версии 2.1.

Изменено в версии 2.2: Добавлена поддержка кортежа в качестве второго аргумента.

Определение подкласса выполняется довольно прямолинейно, но содержит нюанс, о котором разработчикам расширений системы классов стоит знать. Если A и B являются объектами классов, то B является подклассом A, если он наследует от A прямо или косвенно. Если хотя бы один из них не является объектом класса, используется более общий механизм для определения классовых отношений двух объектов. При проверке того, является ли B подклассом A, если A это B, PyObject_IsSubclass() возвращает true. Если A и B являются разными объектами, атрибут __bases__ объекта B's просматривается в глубину на предмет наличия A – считается, что наличие атрибута __bases__ достаточно для такого определения.

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

Возвращает 1, если класс derived идентичен классу cls или наследуется от него, иначе возвращает 0. В случае ошибки возвращает -1. Если cls является кортежем, проверка будет выполнена для каждого элемента cls. Результат будет 1, когда хотя бы одна из проверок возвращает 1, иначе 0. Если derived или cls не являются реальными объектами классов (или кортежем), эта функция использует описанный выше общий алгоритм.

Новое в версии 2.1.

Изменено в версии 2.3: Более старые версии Python не поддерживали кортеж в качестве второго аргумента.

int PyCallable_Check(PyObject *o)¶

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

PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)¶

Возвращаемое значение: новая ссылка.

Вызывает вызываемый объект Python callable_object с аргументами, заданными кортежем args, и именованными аргументами, заданными словарём kw. Если именованные аргументы не нужны, kw может быть NULL. args не должен быть NULL; используйте пустой кортеж, если аргументы не нужны. Возвращает результат вызова в случае успеха или NULL в случае ошибки. Это эквивалент выражения Python apply(callable_object, args, kw) или callable_object(*args, **kw).

Новое в версии 2.2.

PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)¶

Возвращаемое значение: новая ссылка.

Вызывает вызываемый объект Python callable_object с аргументами, заданными кортежем args. Если аргументы не нужны, args может быть NULL. Возвращает результат вызова в случае успеха или NULL в случае ошибки. Это эквивалент выражения Python apply(callable_object, args) или callable_object(*args).

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

Возвращаемое значение: новая ссылка.

Вызывает вызываемый объект Python callable с переменным числом C-аргументов. C-аргументы описываются с помощью строки формата в стиле Py_BuildValue(). Формат может быть NULL, что означает отсутствие аргументов. Возвращает результат вызова в случае успеха или NULL в случае ошибки. Это эквивалент выражения Python apply(callable, args) или callable(*args). Обратите внимание: если передаются только аргументы PyObject *, PyObject_CallFunctionObjArgs() является более быстрой альтернативой.

PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)¶

Возвращаемое значение: новая ссылка.

Вызывает метод с именем method объекта o с переменным числом аргументов C. Аргументы C описываются строкой формата Py_BuildValue(), которая должна порождать кортеж. Формат может быть NULL, что означает отсутствие аргументов. При успехе возвращает результат вызова, при неудаче – NULL. Это эквивалент выражения Python o.method(args). Обратите внимание: если передаются только аргументы PyObject *, то PyObject_CallMethodObjArgs() является более быстрой альтернативой.

PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)¶

Возвращаемое значение: новая ссылка.

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

Новое в версии 2.2.

PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)¶

Возвращаемое значение: новая ссылка.

Вызывает метод объекта o, имя которого задано как объект строки Python в name. Он вызывается с переменным числом аргументов PyObject*. Аргументы передаются как переменное число параметров, за которыми следует NULL. При успехе возвращает результат вызова, при неудаче – NULL.

Новое в версии 2.2.

long PyObject_Hash(PyObject *o)¶

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

long PyObject_HashNotImplemented(PyObject *o)¶

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

Новое в версии 2.6.

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.

Новое в версии 2.2.

Py_ssize_t PyObject_Length(PyObject *o)¶

Py_ssize_t PyObject_Size(PyObject *o)¶

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

Изменено в версии 2.5: Эти функции возвращали тип int. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

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.

int PyObject_DelItem(PyObject *o, PyObject *key)¶

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

int PyObject_AsFileDescriptor(PyObject *o)¶

Извлекает файловый дескриптор из объекта Python. Если объект является целым числом или длинным целым, возвращается его значение. Если нет, вызывается метод fileno() объекта, если он существует; метод должен вернуть целое или длинное целое, которое возвращается как значение файлового дескриптора. В случае ошибки возвращает -1.

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, если объект не может быть проитерирован.