# 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.

  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 a `va_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 of `PyString_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()` and `PyStr_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: identity
  Python 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 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 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 a `va_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)

type 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):

  > > m_slots
  > > m_traverse
  > > m_clear
  > > m_free

  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.

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` or `Py_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()` instead

  A 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 `py2: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`

Quick-and-dirty substitute for the removed `py2: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 `py3:PyMem_RawMalloc()`. Replacement for `malloc`.

PyMem_RawRealloc(void* ptr, size_t n)

  Backport of `py3:PyMem_RawRealloc()`. Replacement for `realloc`.

PyMem_RawFree(void* ptr)

  Backport of `py3:PyMem_Free()`. Replacement for `free`.

PyMem_RawCalloc(size_t n, size_t s)

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

### Unused Arguments

Py_UNUSED(arg)

  Use this for unused arguments in a function definition to silence compiler warnings, e.g. `PyObject* func(PyObject *Py_UNUSED(ignored))`.

  Backport of `py3:Py_UNUSED` from Python 3.4+.