# Capsules

<div class="index">

pair: object; Capsule

</div>

Refer to `using-capsules` for more information on using these objects.

<div class="versionadded">

3.1

</div>

> This subtype of `PyObject` represents an opaque value, useful for C extension modules which need to pass an opaque value (as a `void*` pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

> The type object corresponding to capsule objects. This is the same object as `types.CapsuleType` in the Python layer.

> The type of a destructor callback for a capsule. Defined as:
>
> ``` c
> typedef void (*PyCapsule_Destructor)(PyObject *);
> ```
>
> See `PyCapsule_New` for the semantics of PyCapsule_Destructor callbacks.

> Return true if its argument is a `PyCapsule`. This function always succeeds.

> Create a `PyCapsule` encapsulating the *pointer*. The *pointer* argument may not be `NULL`.
>
> On failure, set an exception and return `NULL`.
>
> The *name* string may either be `NULL` or a pointer to a valid C string. If non-`NULL`, this string must outlive the capsule. (Though it is permitted to free it inside the *destructor*.)
>
> If the *destructor* argument is not `NULL`, it will be called with the capsule as its argument when it is destroyed.
>
> If this capsule will be stored as an attribute of a module, the *name* should be specified as `modulename.attributename`. This will enable other modules to import the capsule using `PyCapsule_Import`.

> Retrieve the *pointer* stored in the capsule. On failure, set an exception and return `NULL`.
>
> The *name* parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is `NULL`, the *name* passed in must also be `NULL`. Python uses the C function `!strcmp` to compare capsule names.

> Return the current destructor stored in the capsule. On failure, set an exception and return `NULL`.
>
> It is legal for a capsule to have a `NULL` destructor. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid` or `PyErr_Occurred` to disambiguate.

> Return the current context stored in the capsule. On failure, set an exception and return `NULL`.
>
> It is legal for a capsule to have a `NULL` context. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid` or `PyErr_Occurred` to disambiguate.

> Return the current name stored in the capsule. On failure, set an exception and return `NULL`.
>
> It is legal for a capsule to have a `NULL` name. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid` or `PyErr_Occurred` to disambiguate.

> Import a pointer to a C object from a capsule attribute in a module. The *name* parameter should specify the full name to the attribute, as in `package.module.attribute`. Modules are imported if needed, other components are looked up as attributes. The *name* stored in the capsule must match this string exactly.
>
> Return the capsule's internal *pointer* on success. On failure, set an exception and return `NULL`.
>
> <div class="versionchanged">
>
> 3.3 *no_block* has no effect anymore.
>
> </div>
>
> <div class="versionchanged">
>
> 3.16 Submodules are now imported if needed.
>
> </div>

> Determines whether or not *capsule* is a valid capsule. A valid capsule is non-`NULL`, passes `PyCapsule_CheckExact`, has a non-`NULL` pointer stored in it, and its internal name matches the *name* parameter. (See `PyCapsule_GetPointer` for information on how capsule names are compared.)
>
> In other words, if `PyCapsule_IsValid` returns a true value, calls to any of the accessors (any function starting with `PyCapsule_Get`) are guaranteed to succeed.
>
> Return a nonzero value if the object is valid and matches the name passed in. Return `0` otherwise. This function will not fail.

> Set the context pointer inside *capsule* to *context*.
>
> Return `0` on success. Return nonzero and set an exception on failure.

> Set the destructor inside *capsule* to *destructor*.
>
> Return `0` on success. Return nonzero and set an exception on failure.

> Set the name inside *capsule* to *name*. If non-`NULL`, the name must outlive the capsule. If the previous *name* stored in the capsule was not `NULL`, no attempt is made to free it.
>
> Return `0` on success. Return nonzero and set an exception on failure.

> Set the void pointer inside *capsule* to *pointer*. The pointer may not be `NULL`.
>
> Return `0` on success. Return nonzero and set an exception on failure.