Writing extension modules for pypy

This document tries to explain how to interface the PyPy python interpreterwith any external library.

Right now, there are the following possibilities of providingthird-party modules for the PyPy python interpreter (in order, from mostdirectly useful to most messy to use with PyPy):

• Write them in pure Python and use CFFI.
• Write them in pure Python and use ctypes.
• Write them in C++ and bind them through cppyy using Cling.
• Write them as RPython mixed modules.

CFFI

CFFI is the recommended way. It is a way to write pure Python codethat accesses C libraries. The idea is to support either ABI- orAPI-level access to C — so that you can sanely access C librarieswithout depending on details like the exact field order in the Cstructures or the numerical value of all the constants. It works onboth CPython (as a separate python -mpip install cffi) and on PyPy, where itis included by default.

PyPy’s JIT does a quite reasonable job on the Python code that call Cfunctions or manipulate C pointers with CFFI. (As of PyPy 2.2.1, itcould still be improved, but is already good.)

See the documentation here.

CTypes

The goal of the ctypes module of PyPy is to be as compatible as possiblewith the CPython ctypes version. It works for large examples, suchas pyglet. PyPy’s implementation is not strictly 100% compatible withCPython, but close enough for most cases.More (but older) information is available here.Also, ctypes’ performance is not as good as CFFI’s.

PyPy implements ctypes as pure Python code around two built-in modulescalled _rawffi and _rawffi.alt, which give a very low-level binding tothe C library libffi. Nowadays it is not recommended to use directlythese two modules.

cppyy

For C++, cppyy is an automated bindings generator available for bothPyPy and CPython.cppyy relies on declarations from C++ header files to dynamicallyconstruct Python equivalent classes, functions, variables, etc.It is designed for use by large scale programs and supports modern C++.With PyPy, it leverages the built-in _cppyy module, allowing the JIT toremove most of the cross-language overhead.

To install, run <pypy> -mpip install cppyy.Further details are available in the full documentation.

RPython Mixed Modules

This is the internal way to write built-in extension modules in PyPy.It cannot be used by any 3rd-party module: the extension modules arebuilt-in, not independently loadable DLLs.

This is reserved for special cases: it gives direct access to e.g. thedetails of the JIT, allowing us to tweak its interaction with user code.This is how the numpy module is being developed.