PyCapsule API for Python 2.6¶
The capsulethunk.h header implements the PyCapsule API
(with some limitations) in terms of PYCObject.
It is only necessary for compatibility with Python 2.6 (or 3.0).
Note
The capsulethunk.h header and this documentation was written by
Larry Hastings for the Python documentation. [1]
It is now maintained as part of the py3c project. [2]
CObject replaced with Capsule¶
The Capsule object was introduced in Python 3.1 and
2.7 to replace CObject. CObjects were useful,
but the CObject API was problematic: it didn’t permit
distinguishing between valid CObjects, which allowed mismatched CObjects to
crash the interpreter, and some of its APIs relied on undefined behavior in C.
(For further reading on the rationale behind Capsules, please see
CPython issue 5630.)
If you’re currently using CObjects, and you want to migrate to Python 3, you’ll need to switch to Capsules. See the PyCObject section in the porting guide for instructions.
CObject was deprecated in 3.1 and 2.7 and completely
removed in Python 3.2. So, if you need to support versions of
Python earlier than 2.7, or Python 3.0,
you’ll have to support both CObjects and Capsules.
The following example header file capsulethunk.h may
solve the problem for you. Simply write your code against the
Capsule API and include this header file after
Python.h. Your code will automatically use Capsules
in versions of Python with Capsules, and switch to CObjects
when Capsules are unavailable.
If you’re using py3c, you will need to explicitly
#include <py3c/capsulethunk.h>. The file is not included from py3c.h.
Since CObject provides no place to store the
capsule’s “name”, the simulated Capsule objects
created by capsulethunk.h behave slightly differently from real
Capsules. Specifically:
The name parameter passed in to
PyCapsule_New()is ignored.The name parameter passed in to
PyCapsule_IsValid()andPyCapsule_GetPointer()is ignored, and no error checking of the name is performed.
PyCapsule_GetName()always returns NULL.
PyCapsule_SetName()always raises an exception and returns failure. (Since there’s no way to store a name in a CObject, noisy failure ofPyCapsule_SetName()was deemed preferable to silent failure here.) If this is inconvenient, feel free to modify your local copy as you see fit.
You can find capsulethunk.h at
include/py3c/capsulethunk.h.
We also include it here for your convenience:
/* Copyright (c) 2011, Larry Hastings
* Copyright (c) 2015, py3c contributors
* Licensed under the MIT license; see py3c.h
*
* (Note: Relicensed from PSF: http://bugs.python.org/issue24937#msg250191 )
*/
#ifndef __CAPSULETHUNK_H
#define __CAPSULETHUNK_H
#if ( (PY_VERSION_HEX < 0x02070000) \
|| ((PY_VERSION_HEX >= 0x03000000) \
&& (PY_VERSION_HEX < 0x03010000)) )
#define __PyCapsule_GetField(capsule, field, error_value) \
( PyCapsule_CheckExact(capsule) \
? (((PyCObject *)capsule)->field) \
: (PyErr_SetString(PyExc_TypeError, "CObject required"), (error_value)) \
) \
#define __PyCapsule_SetField(capsule, field, value) \
( PyCapsule_CheckExact(capsule) \
? (((PyCObject *)capsule)->field = value), 0 \
: (PyErr_SetString(PyExc_TypeError, "CObject required"), 1) \
) \
#define PyCapsule_Type PyCObject_Type
#define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
#define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))
#define PyCapsule_New(pointer, name, destructor) \
(PyCObject_FromVoidPtr(pointer, (void (*)(void*)) (destructor)))
#define PyCapsule_GetPointer(capsule, name) \
(PyCObject_AsVoidPtr(capsule))
/* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
#define PyCapsule_SetPointer(capsule, pointer) \
__PyCapsule_SetField(capsule, cobject, pointer)
#define PyCapsule_GetDestructor(capsule) \
__PyCapsule_GetField(capsule, destructor, (void (*)(void*)) NULL)
#define PyCapsule_SetDestructor(capsule, dtor) \
__PyCapsule_SetField(capsule, destructor, (void (*)(void*)) dtor)
/*
* Sorry, there's simply no place
* to store a Capsule "name" in a CObject.
*/
#define PyCapsule_GetName(capsule) NULL
static int
PyCapsule_SetName(PyObject *capsule, const char *unused)
{
unused = unused;
PyErr_SetString(PyExc_NotImplementedError,
"can't use PyCapsule_SetName with CObjects");
return 1;
}
#define PyCapsule_GetContext(capsule) \
__PyCapsule_GetField(capsule, desc, (void*) NULL)
#define PyCapsule_SetContext(capsule, context) \
__PyCapsule_SetField(capsule, desc, context)
static void *
PyCapsule_Import(const char *name, int no_block)
{
PyObject *object = NULL;
void *return_value = NULL;
char *trace;
size_t name_length = (strlen(name) + 1) * sizeof(char);
char *name_dup = (char *)PyMem_MALLOC(name_length);
if (!name_dup) {
return NULL;
}
memcpy(name_dup, name, name_length);
trace = name_dup;
while (trace) {
char *dot = strchr(trace, '.');
if (dot) {
*dot++ = '\0';
}
if (object == NULL) {
if (no_block) {
object = PyImport_ImportModuleNoBlock(trace);
} else {
object = PyImport_ImportModule(trace);
if (!object) {
PyErr_Format(PyExc_ImportError,
"PyCapsule_Import could not "
"import module \"%s\"", trace);
}
}
} else {
PyObject *object2 = PyObject_GetAttrString(object, trace);
Py_DECREF(object);
object = object2;
}
if (!object) {
goto EXIT;
}
trace = dot;
}
if (PyCObject_Check(object)) {
PyCObject *cobject = (PyCObject *)object;
return_value = cobject->cobject;
} else {
PyErr_Format(PyExc_AttributeError,
"PyCapsule_Import \"%s\" is not valid",
name);
}
EXIT:
Py_XDECREF(object);
if (name_dup) {
PyMem_FREE(name_dup);
}
return return_value;
}
#endif /* #if PY_VERSION_HEX < 0x02070000 */
#endif /* __CAPSULETHUNK_H */
Footnotes