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 asstr
.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.
Python 2:PyString_CheckExact
Python 3:PyUnicode_CheckExact
-
PyObject*
PyStr_FromString
(const char *u)¶ Create a PyStr from a UTF-8 encoded null-terminated character buffer.
Python 2:PyString_FromString
Python 3:PyUnicode_FromString
-
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()
.Python 2:PyString_FromStringAndSize
Python 3:PyUnicode_FromStringAndSize
-
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.Python 2:PyString_FromFormat
Python 3:PyUnicode_FromFormat
-
PyObject*
PyStr_FromFormatV
(const char *format, va_list vargs)¶ As
PyStr_FromFormat()
, but takes ava_list
.Python 2:PyString_FromFormatV
Python 3:PyUnicode_FromFormatV
-
const char*
PyStr_AsString
(PyObject *s)¶ Return a null-terminated representation of the contents of s. The buffer is owned by s and must not 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 2:PyString_AsString
Python 3:PyUnicode_AsUTF8
(!)
-
PyObject*
PyStr_Concat
(PyObject *left, PyObject *right)¶ Concatenates two strings giving a new string.
Python 2: implemented in terms ofPyString_Concat
Python 3:PyUnicode_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
Python 3:PyUnicode_Format
-
void
PyStr_InternInPlace
(PyObject **string)¶ Intern string, in place.
Python 2:PyString_InternInPlace
Python 3:PyUnicode_InternInPlace
-
PyObject*
PyStr_InternFromString
(const char *v)¶ Create an interned string from a buffer. Combines
PyStr_FromString()
andPyStr_InternInPlace()
.In Python 3, v must be UTF-8 encoded.
Python 2:PyString_InternFromString
Python 3:PyUnicode_InternFromString
-
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
Python 3:PyUnicode_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.
Python 2:PyString_AsString
Python 3:PyUnicode_AsUTF8
-
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: identityPython 3:PyUnicode_AsUTF8String
-
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.
Python 2: (*size =PyString_Size(str)
,PyString_AsString(str)
)Python 3:PyUnicode_AsUTF8AndSize
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 asstr
, and in Python 3 asbytes
.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 2:PyString_CheckExact
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 2:PyString_FromString
Python 3:(provided)
-
PyObject*
PPyBytes_FromStringAndSize
(const char *v, Py_ssize_t len)¶ Create a PyBytes from a C buffer and size.
Python 2:PyString_FromStringAndSize
Python 3:(provided)
-
PyObject*
PyBytes_FromFormat
(const char *format, ...)¶ Create a PyBytes from a C printf-style format string and arguments.
Python 2:PyString_FromFormat
Python 3:(provided)
-
PyObject*
PyBytes_FromFormatV
(const char *format, va_list args)¶ As
PyBytes_FromFormat()
, but takes ava_list
.Python 2:PyString_FromFormatV
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 2:PyString_GET_SIZE
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 2:PyString_AsString
Python 3:(provided)
-
char *
PyBytes_AS_STRING
(PyObject *o)¶ As
PyBytes_AsString()
but without error checking.Python 2:PyString_AS_STRING
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 2:PyString_AsStringAndSize
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 2:PyString_ConcatAndDel
Python 3:(provided)
-
int
_PyBytes_Resize
(PyObject **string, Py_ssize_t newsize)¶ Used for efficiently build bytes objects; see the Python docs.
Python 2:_PyString_Resize
Python 3:(provided)
PyInt¶
These functions allow extensions to make the distinction 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)
Python 3:PyLong_CheckExact
-
PyObject*
PyInt_FromString
(char *str, char **pend, int base)¶ Convert a string to PyInt. See the Python docs.
Python 2:(provided)
Python 3:PyLong_FromString
-
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)
Python 3:PyLong_FromSsize_t
-
PyObject*
PyInt_FromSize_t
(Py_size_t i)¶ Convert a Py_size_t int to PyInt.
Python 2:(provided)
Python 3:PyLong_FromSize_t
-
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.
Python 2:(provided)
Python 3:PyLong_AsUnsignedLongLongMask
-
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)
Python 3:PyLong_AsSsize_t
PyFloat¶
-
PyObject*
PyFloat_FromString
(PyObject *str)¶ Create a
PyFloatObject
object. The signature follows the Python 3 API, even on Python 2.Python 2:PyFloat_FromString(str, NULL)
Python 3:PyFloat_FromString(str)
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
¶ Name of the new module
-
char *
m_doc
¶ Documentation string, or NULL
-
Py_ssize_t
m_size
¶ Set this to -1. (Or if your module supports
subinterpreters
, use 0)
-
PyMethodDef
m_methods
¶ Pointer to a table of module-level functions
Four more members are provided. Under Python 2, set them to NULL. (In a global
static
structure, you can leave them out unless you want to avoid warnings about unitialized members):Python 3:
(provided)
-
int
-
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.
-
Py_UNREACHABLE
¶ Use instead of assert() or abort() in unreachable code, such as handling undefined comparison operations.
Backported from
Python 3.7
for older versions.
-
PyObject*
PY_RETURN_RICHCOMPARE
(val1, val2, int op)¶ Compares two arguments orderable by C comparison operators (such as C ints or floats), and returns
Py_True
orPy_False
based on the result, properly increasing the reference count.The third argument specifies the requested operation, as for a
rich comparison function
.Backported from
Python 3.7
for older versions.
-
PyObject*
PY3C_RICHCMP
(val1, val2, int op)¶ Deprecated since version 1.0: Use
PY_RETURN_RICHCOMPARE()
insteadA helper for rich comparisons that py3c provided before such a helper was, with slightly changed name and semantics, included in Python itself.
There are no plans to remove
PY3C_RICHCMP
from py3c, but before your project gets rid of py3c, all calls need to switch to what’s provided by CPython.To switch, instead of:
return PY3C_RICHCMP(a, b, op)
write:
PY_RETURN_RICHCOMPARE(a, b, op)
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)¶ - Python 2.6:
PyCObject_Check(capsule)
2.7 and 3.x:(provided)
-
PyCapsule_New
(void *pointer, const char *name, PyCapsule_Destructor destructor)¶ - Python 2.6:
PyCObject_FromVoidPtr(pointer, destructor)
2.7 and 3.x:(provided)
-
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 destructor2.7 and 3.x:
(provided)
-
PyCapsule_SetDestructor
(PyObject *capsule, PyCapsule_Destructor destructor)¶ - Python 2.6: uses CPython internals to replace a CObject’s destructor2.7 and 3.x:
(provided)
-
PyCapsule_GetName
(PyObject *capsule)¶ - Python 2.6: NULL2.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” field2.7 and 3.x:
(provided)
-
PyCapsule_SetContext
(PyObject *capsule, PyCapsule_Destructor destructor)¶ - Python 2.6: uses CPython internals to replace CObject “desc” field2.7 and 3.x:
(provided)
-
PyCapsule_Import
(const char *name, int no_block)¶ - Python 2.6: backported2.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 formalloc
.
-
PyMem_RawRealloc
(void* ptr, size_t n)¶ Backport of
PyMem_RawRealloc()
. Replacement forrealloc
.
-
PyMem_RawFree
(void* ptr)¶ Backport of
PyMem_Free()
. Replacement forfree
.
-
PyMem_RawCalloc
(size_t n, size_t s)¶ Backport of
PyMem_Calloc()
from Python 3.5+. Replacement forcalloc
.