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

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 если результат имеет значение false, 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 возвращается при сбое, а объект bytes - при успешном. 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_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

Return value: New reference.

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

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

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

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

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

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

Return value: New reference.

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

Return value: New reference.

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

PyObject* PyObject_GetIter(PyObject *o)

Return value: New reference.

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