Документация Python неофициальный перевод

КапсулыCapsules

Обратитесь к Предоставление C API для модуля расширения для получения дополнительной информации об использовании этих объектов.

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

type PyCapsule

Этот подтип PyObject представляет непрозрачное значение, полезное для C модулей расширения, которым нужно передавать непрозрачное значение (в виде void* указателя) через код Python другому C-коду. Он часто используется, чтобы сделать указатель на C-функцию, определенную в одном модуле, доступным для других модулей, так что обычный механизм импорта может использоваться для доступа к C API, определенным в динамически загружаемых модулях.

PyTypeObject PyCapsule_Type
Часть Stable ABI.

Объект типа, соответствующий объектам-капсулам. Это тот же объект что и types.CapsuleType на уровне Python.

type PyCapsule_Destructor
Часть Stable ABI.

Тип колбэка-деструктора для капсулы. Определяется как:

typedef void (*PyCapsule_Destructor)(PyObject *);

См. PyCapsule_New() для описания семантики колбэков PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p)
Потокобезопасность: атомарно.

Возвращает истину, если аргумент является PyCapsule. Эта функция всегда выполняется успешно.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.

Создаёт PyCapsule, инкапсулирующий указатель. Аргумент указатель не может быть NULL.

При ошибке устанавливает исключение и возвращает NULL.

Строка имя может быть либо NULL, либо указателем на допустимую C-строку. Если не NULL, эта строка должна пережить капсулу. (Хотя разрешается освободить её внутри деструктора.)

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

Если эта капсула будет храниться как атрибут модуля, имя следует указать как modulename.attributename. Это позволит другим модулям импортировать капсулу с помощью PyCapsule_Import().

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Извлекает указатель, хранящийся в капсуле. При ошибке устанавливает исключение и возвращает NULL.

Параметр имя должен точно совпадать с именем, хранящимся в капсуле. Если имя, хранящееся в капсуле, равно NULL, то переданное имя также должно быть NULL. Python использует C-функцию strcmp() для сравнения имён капсул.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

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

Капсула может иметь деструктор NULL. Это делает код возврата NULL несколько неоднозначным; используйте PyCapsule_IsValid() или PyErr_Occurred() для устранения неоднозначности.

void *PyCapsule_GetContext(PyObject *capsule)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Возвращает текущий контекст, хранящийся в капсуле. В случае ошибки устанавливает исключение и возвращает NULL.

Капсула может иметь контекст NULL. Это делает код возврата NULL несколько неоднозначным; используйте PyCapsule_IsValid() или PyErr_Occurred() для устранения неоднозначности.

const char *PyCapsule_GetName(PyObject *capsule)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

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

Капсула может иметь имя NULL. Это делает код возврата NULL несколько неоднозначным; используйте PyCapsule_IsValid() или PyErr_Occurred() для устранения неоднозначности.

void *PyCapsule_Import(const char *name, int no_block)
Часть Stable ABI. Потокобезопасность: Безопасен для вызова из нескольких потоков только с внешней синхронизацией.

Импортирует указатель на C-объект из атрибута капсулы в модуле. Параметр name должен указывать полное имя атрибута, например module.attribute. Имя name, хранящееся в капсуле, должно точно совпадать с этой строкой.

Эта функция разбивает name по символу ., импортирует первый элемент, а затем обрабатывает остальные элементы с помощью поиска атрибутов.

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

Примечание

Если name указывает на атрибут какого-либо подмодуля или подпакета, этот подмодуль или подпакет должен быть предварительно импортирован другими средствами (например, с помощью PyImport_ImportModule()), чтобы поиск атрибутов прошёл успешно.

Изменено в версии 3.3: no_block больше не действует.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Определяет, является ли capsule допустимой капсулой. Допустимая капсула не является NULL, проходит PyCapsule_CheckExact(), содержит ненулевой NULL указатель, и её внутреннее имя совпадает с параметром name. (См. PyCapsule_GetPointer() для информации о том, как сравниваются имена капсул.)

Другими словами, если PyCapsule_IsValid() возвращает истинное значение, вызовы любых функций доступа (любой функции, начинающейся с PyCapsule_Get) гарантированно завершаются успешно.

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

int PyCapsule_SetContext(PyObject *capsule, void *context)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Устанавливает указатель контекста внутри capsule в значение context.

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Устанавливает деструктор внутри capsule в значение destructor.

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

int PyCapsule_SetName(PyObject *capsule, const char *name)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Устанавливает имя внутри capsule в значение name. Если не NULL, имя должно пережить капсулу. Если предыдущее name, хранящееся в капсуле, не было NULL, попытка его освобождения не предпринимается.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Часть Стабильного ABI. Потокобезопасность: Безопасен для вызова без внешней синхронизации для разных объектов.

Устанавливает указатель void внутри capsule на pointer. Указатель не может быть NULL.

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