index.rst

HPy: a better API for Python

HPy provides a new API for extending Python in C.

There are several advantages to writing C extensions in HPy:

• Speed: it runs much faster on PyPy, GraalPy, and at native speed on CPython
• Deployment: it is possible to compile a single binary which runs unmodified on all supported Python implementations and versions -- think "stable ABI" on steroids
• Simplicity: it is simpler and more manageable than the Python.h API, both for the users and the Pythons implementing it
• Debugging: it provides an improved debugging experience. Debug mode can be turned on at runtime without the need to recompile the extension or the Python running it. HPy design is more suitable for automated checks.

The official Python/C API, also informally known as #include <Python.h>, is specific to the current implementation of CPython: it exposes a lot of internal details which makes it hard to:

• implement it for other Python implementations (e.g. PyPy, GraalPy, Jython, ...)
• experiment with new approaches inside CPython itself, for example:
  • use a tracing garbage collection instead of reference counting
  • remove the global interpreter lock (GIL) to take full advantage of multicore architectures
  • use tagged pointers to reduce memory footprint

Where to go next:

• Show me the code:

  • Quickstart<quickstart>
  • Simple documented HPy extension example<simple example>
  • Tutorial: porting Python/C API extension to HPy<porting-example/index>

• Details:

  • HPy overview: motivation, goals, current status<overview>
  • HPy API concepts introduction<api>
  • Python/C API to HPy Porting guide<porting-guide>
  • HPy API reference<api-reference/index>

Full table of contents:

quickstart overview api porting-guide porting-example/index debug-mode trace-mode api-reference/index contributing/index misc/index changelog

Indices and tables

• genindex
• modindex
• search