py3c reference

Compatibility Layer

#include <py3c/compat.h>  // (included in <py3c.h>)
IS_PY3

Defined as 1 when building for Python 3; 0 otherwise.

PyStr

These functions are the intersection of PyString in Python 2, and PyUnicode in Python 3, with a few helpers thrown it.

All follow the Python 3 API, except PyStr is substituted for PyUnicode.

PyStr_Type

A PyTypeObject instance representing a human-readable string. Exposed in Python as str.

Python 2: PyString_Type
Python 3: (provided)
int PyStr_Check(PyObject *o)

Check that o is an instance of PyStr or a subtype.

Python 2: PyString_Check
Python 3: PyUnicode_Check
int PyStr_CheckExact(PyObject *o)

Check that o is an instance of PyStr, but not a subtype.

PyObject* PyStr_FromString(const char *u)

Create a PyStr from a UTF-8 encoded null-terminated character buffer.

PyObject* PyStr_FromStringAndSize(const char *u, Py_ssize_t len)

Create a PyStr from a UTF-8 encoded character buffer, and corresponding size in bytes.

Note that human-readable strings should not contain null bytes; but if the size is known, this is more efficient than PyStr_FromString().

PyObject* PyStr_FromFormat(const char *format, ...)

Create a PyStr from a C printf-style format string and arguments.

Note that formatting directives that were added in Python 3 (%li, %lli, zi, %A, %U, %V, %S, %R) will not work in Python 2.

PyObject* PyStr_FromFormatV(const char *format, va_list vargs)

As PyStr_FromFormat(), but takes a va_list.

const char* PyStr_AsString(PyObject *s)

Return a null-terminated representation of the contents of s. The buffer is owned by s and must bot be modified, deallocated, or used after s is deallocated.

Uses the UTF-8 encoding on Python 3.

If given an Unicode string on Python 2, uses Python’s default encoding.

Python 3: PyUnicode_AsUTF8 (!)
PyObject* PyStr_Concat(PyObject *left, PyObject *right)

Concatenates two strings giving a new string.

Python 2: implemented in terms of PyString_Concat
PyObject* PyStr_Format(PyObject *format, PyObject *args)

Format a string; analogous to the Python expression format % args. The args must be a tuple or dict.

Python 2: PyString_Format
void PyStr_InternInPlace(PyObject **string)

Intern string, in place.

PyObject* PyStr_InternFromString(const char *v)

Create an interned string from a buffer. Combines PyStr_FromString() and PyStr_InternInPlace().

In Python 3, v must be UTF-8 encoded.

PyObject* PyStr_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

Create a new string by decoding size bytes from s, using the specified encoding.

Python 2: PyString_Decode
char* PyStr_AsUTF8(PyObject *str)

Encode a string using UTF-8 and return the result as a char*. Under Python 3, the result is UTF-8 encoded.

PyObject* PyStr_AsUTF8String(PyObject *str)

Encode a string using UTF-8 and return the result as PyBytes.

In Python 2, (where PyStr is bytes in UTF-8 encoding already), this is a no-op.

Python 2: identity
char *PyStr_AsUTF8AndSize(PyObject *str, Py_ssize_t *size)

Return the UTF-8-encoded representation of the string, and set size to the number of bytes in this representation. The size may not be NULL.

In Python 2, the string is assumed to be UTF8-encoded.

On error, size may or may not be set.

PyBytes

These functions are the intersection of PyString in Python 2, and PyBytes in Python 3.

All follow the Python 3 API.

PyBytes_Type

A PyTypeObject instance representing a string of binary data. Exposed in Python 2 as str, and in Python 3 as bytes.

Python 2: PyString_Type
Python 3: (provided)
int PyBytes_Check(PyObject *o)

Check that o is an instance of PyBytes or a subtype.

Python 2: PyString_Check
Python 3: (provided)
int PyBytes_CheckExact(PyObject *o)

Check that o is an instance of PyBytes, but not a subtype.

Python 3: (provided)
PyObject* PyBytes_FromString(const char *v)

Create a PyBytes from a NULL-terminated C buffer.

Note that binary data might contain null bytes; consider using PyBytes_FromStringAndSize() instead.

Python 3: (provided)
PyObject* PPyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

Create a PyBytes from a C buffer and size.

PyObject* PyBytes_FromFormat(const char *format, ...)

Create a PyBytes from a C printf-style format string and arguments.

Python 3: (provided)
PyObject* PyBytes_FromFormatV(const char *format, va_list args)

As PyBytes_FromFormat(), but takes a va_list.

Python 3: (provided)
Py_ssize_t PyBytes_Size(PyObject *o)

Return the number of bytes in a PyBytes object.

Python 2: PyString_Size
Python 3: (provided)
Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

As PyBytes_Size() but without error checking.

Python 3: (provided)
char *PyBytes_AsString(PyObject *o)

Return the buffer in a PyBytes object. The data must not be modifiet or deallocated, or used after a reference to o is no longer held.

Python 3: (provided)
char *PyBytes_AS_STRING(PyObject *o)

As PyBytes_AsString() but without error checking.

Python 3: (provided)
int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

Get the buffer and size stored in a PyBytes object.

Python 3: (provided)
void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Concatenate newpart to bytes, returning a new object in bytes, and discarding the old.

Python 2: PyString_Concat
Python 3: (provided)
void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

As PyBytes_AsString() but decreases reference count of newpart.

Python 3: (provided)
int _PyBytes_Resize(PyObject **string, Py_ssize_t newsize)

Used for efficiently build bytes objects; see the Python docs.

Python 3: (provided)

PyInt

These functions allow extensions to make the diistinction between ints and longs on Python 2.

All follow the Python 2 API.

PyInt_Type

A PyTypeObject instance representing an integer that fits in a C long.

Python 2: (provided)
Python 3: PyLong_Type
int PyInt_Check(PyObject *o)

Check that o is an instance of PyInt or a subtype.

Python 2: (provided)
Python 3: PyLong_Check
int PyInt_CheckExact(PyObject *o)

Check that o is an instance of PyInt, but not a subtype.

Python 2: (provided)
PyObject* PyInt_FromString(char *str, char **pend, int base)

Convert a string to PyInt. See the Python docs.

Python 2: (provided)
PyObject* PyInt_FromLong(long i)

Convert a C long int to PyInt.

Python 2: (provided)
Python 3: PyLong_FromLong
PyObject* PyInt_FromSsize_t(Py_ssize_t i)

Convert a Py_ssize_t int to PyInt.

Python 2: (provided)
PyObject* PyInt_FromSize_t(Py_size_t i)

Convert a Py_size_t int to PyInt.

Python 2: (provided)
long PyInt_AsLong(PyObject *o)

Convert a PyInt to a C long.

Python 2: (provided)
Python 3: PyLong_AsLong
long PyInt_AS_LONG(PyObject *o)

As PyInt_AsLong(), but with no error checking.

Python 2: (provided)
Python 3: PyLong_AS_LONG
unsigned long PyInt_AsUnsignedLongLongMask(PyObject *o)

Convert a Python object to int, and return its value as an unsigned long.

Py_ssize_t PyInt_AsSsize_t(PyObject *o)

Convert a Python object to int, and return its value as a Py_ssize_t.

Python 2: (provided)

PyFloat

PyObject* PyFloat_FromString(PyObject *str)

Create a PyFloatObject object. The signature follows the Python 3 API, even on Python 2.

Module Initialization

MODULE_INIT_FUNC(<name>)

Use this macro as the header for the module initialization function.

Python 2:

static PyObject *PyInit_<name>(void);
void init<name>(void);
void init<name>(void) { PyInit_<name>(); }
static PyObject *PyInit_<name>(void)

Python 3:

PyMODINIT_FUNC PyInit_<name>(void);
PyMODINIT_FUNC PyInit_<name>(void)
PyModuleDef

Python 2:

int m_base

Always set this to PyModuleDef_HEAD_INIT

char *m_name
char *m_doc
Py_ssize_t m_size

Set this to -1. (Or if your module supports subinterpreters, use 0)

PyMethodDef m_methods

Python 3: (provided)

PyModuleDef_HEAD_INIT
Python 2: 0
Python 3: (provided)
PyObject* PyModule_Create(PyModuleDef def)
Python 2: Py_InitModule3(def->m_name, def->m_methods, def->m_doc)
Python 3: (provided)

Comparison Helpers

#include <py3c/comparison.h>  // (included in <py3c.h>)
Py_RETURN_NOTIMPLEMENTED

Backported from Python 3.4 for older versions.

PyObject* PY3C_RICHCMP(val1, val2, int op)

Compares two arguments orderable by C comparison operators (such as C ints or floats). The third argument specifies the requested operation, as for a rich comparison function. Evaluates to a new reference to Py_True or Py_False, depending on the result of the comparison.

((op) == Py_EQ) ? PyBool_FromLong((val1) == (val2)) : \
((op) == Py_NE) ? PyBool_FromLong((val1) != (val2)) : \
((op) == Py_LT) ? PyBool_FromLong((val1) < (val2)) : \
((op) == Py_GT) ? PyBool_FromLong((val1) > (val2)) : \
((op) == Py_LE) ? PyBool_FromLong((val1) <= (val2)) : \
((op) == Py_GE) ? PyBool_FromLong((val1) >= (val2)) : \
(Py_INCREF(Py_NotImplemented), Py_NotImplemented)

Types

#include <py3c/tpflags.h>  /* (*NOT* included in <py3c.h>) */

Removed type flags are defined as 0 in Python 3, which is only useful in type definitions.

In particular, these macros are not suitable for PyType_HasFeature() in Python 3.

Py_TPFLAGS_HAVE_GETCHARBUFFER
Py_TPFLAGS_HAVE_SEQUENCE_IN
Py_TPFLAGS_HAVE_INPLACEOPS
Py_TPFLAGS_CHECKTYPES
Py_TPFLAGS_HAVE_RICHCOMPARE
Py_TPFLAGS_HAVE_WEAKREFS
Py_TPFLAGS_HAVE_ITER
Py_TPFLAGS_HAVE_CLASS
Py_TPFLAGS_HAVE_INDEX
Py_TPFLAGS_HAVE_NEWBUFFER
Python 2: (provided), e.g. Py_TPFLAGS_HAVE_WEAKREFS
Python 3: 0

Capsules

#include <py3c/capsulethunk.h>  // (*NOT* included in <py3c.h>)

This file provides a PyCapsule API compatibility layer for Python 2.6.

Capsules are simulated in terms of PyCObject. The PyCapsule API for Python 2.6 chapter lists the limitations of this solution.

PyCapsule_Type
Python 2.6: PyCObject_Type
2.7 and 3.x: (provided)
PyCapsule_CheckExact(PyObject *p)
Python 2.6: PyCObject_Check
2.7 and 3.x: (provided)
PyCapsule_IsValid(PyObject *capsule, const char *name)
2.7 and 3.x: (provided)
PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
PyCapsule_GetPointer(PyObject *capsule, const char *name)
Python 2.6: PyCObject_AsVoidPtr(capsule) – name is not checked!
2.7 and 3.x: (provided)
PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Python 2.6: uses CPython internals; effect similar to PyCObject_SetVoidPtr()
2.7 and 3.x: (provided)
PyCapsule_GetDestructor(PyObject *capsule)
Python 2.6: uses CPython internals to get the a CObject’s destructor
2.7 and 3.x: (provided)
PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Python 2.6: uses CPython internals to replace a CObject’s destructor
2.7 and 3.x: (provided)
PyCapsule_GetName(PyObject *capsule)
Python 2.6: NULL
2.7 and 3.x: (provided)
PyCapsule_SetName(PyObject *capsule)
Python 2.6: Always raises NotImplementedError
2.7 and 3.x: (provided)
PyCapsule_GetContext(PyObject *capsule)
Python 2.6: uses CPython internals to get the CObject “desc” field
2.7 and 3.x: (provided)
PyCapsule_SetContext(PyObject *capsule, PyCapsule_Destructor destructor)
Python 2.6: uses CPython internals to replace CObject “desc” field
2.7 and 3.x: (provided)
PyCapsule_Import(const char *name, int no_block)
Python 2.6: backported
2.7 and 3.x: (provided)

Files

#include <py3c/fileshim.h>  // (*NOT* included in <py3c.h>)
py3c_PyFile_AsFileWithMode(PyObject *py_file, const char *mode)

Quick-and-dirty substitute for the removed PyFile_AsFile(). Read the file shim chapter before using.

Shims for New Conveniences in Python 3.4+

#include <py3c/py3shims.h>  // (included in <py3c.h>)

Raw Memory Allocation

Python 3.4 adds several functions to manage “raw” memory in a way that the Python allocator is aware of it. These are safe replacements for stdlib’s malloc, realloc and free. For convenience, py3c provides backports of these to earlier Python versions.

The backports provided here simply use the C standard library functions, except they return unique pointers when zero bytes are requested.

PyMem_RawMalloc(size_t n)

Backport of PyMem_RawMalloc(). Replacement for malloc.

PyMem_RawRealloc(void* ptr, size_t n)

Backport of PyMem_RawRealloc(). Replacement for realloc.

PyMem_RawFree(void* ptr)

Backport of PyMem_Free(). Replacement for free.

PyMem_RawCalloc(size_t n, size_t s)

Backport of PyMem_Calloc() from Python 3.5+. Replacement for calloc.