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 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 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 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)
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
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)
-
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.
-
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 toPy_True
orPy_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)
Capsules¶
#include <py3c/capsulethunk.h> // (*NOT* included in <py3c.h>)
This header is copied from the Python documentation. The following text is adapted from its official docs:
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.
capsulethunk.h
simulates Capsules using CObjects. However,
CObject
provides no place to store the capsule’s “name”.
As a result 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
in the Python source distribution
as Doc/includes/capsulethunk.h.
We also include it as py3c/capsulethunk.h
for your convenience: