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

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; если он указан, записывается 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)¶

Обратите внимание, что исключения, возникающие при вызове методов __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)¶

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

Примечание

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

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 есть метод __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 в 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(). Её следует использовать только если вызывающая сторона уже имеет готовый к использованию словарь.

Примечание

Новое в версии 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)¶: Возвращает true, если объект 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, это похоже на dir() в Python, возвращает имена текущих локальных переменных; в этом случае, если нет активного фрейма выполнения, возвращается NULL, но PyErr_Occurred() вернёт false.

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