Extending and Embedding the Python Interpreter

This document describes how to write modules in C or C++ to extend the Pythoninterpreter with new modules. Those modules can do what Python code does –define functions, object types and methods – but also interact with nativelibraries or achieve better performance by avoiding the overhead of aninterpreter. The document also describes howto embed the Python interpreter in another application, for use as an extensionlanguage. Finally, it shows how to compile and link extension modules so thatthey can be loaded dynamically (at run time) into the interpreter, if theunderlying operating system supports this feature.

This document assumes basic knowledge about C and Python. For an informalintroduction to Python, seeThe Python Tutorial.The Python Language Referencegives a more formal definition of the language.The Python Standard Library documentsthe existing object types, functions and modules (both built-in and written inPython) that give the language its wide application range.

For a detailed description of the whole Python/C API, see the separatePython/C API Reference Manual.

To support extensions, Python’s C API (Application Programmers Interface)defines a set of functions, macros and variables that provide access to mostaspects of the Python run-time system. The Python API is incorporated in a Csource file by including the header"Python.h".

Note

The C extension interface is specific to CPython, and extension modules donot work on other Python implementations. In many cases, it is possible toavoid writing C extensions and preserve portability to other implementations.For example, if your use case is calling C library functions or system calls,you should consider using thectypes module or thecffi library rather than writingcustom C code.These modules let you write Python code to interface with C code and are moreportable between implementations of Python than writing and compiling a Cextension module.

Recommended third party tools

This document only covers the basic tools for creating extensions providedas part of this version of CPython. Somethird party tools offer both simpler and more sophisticated approaches to creatingC and C++ extensions for Python.

While this document is aimed at extension authors, it should also be helpful tothe authors of such tools.For example, the tutorial module can serve as a simple test case for a buildtool or sample expected output of a code generator.

C API Tutorial

This tutorial describes how to write a simple module in C or C++,using the Python C API – that is, using the basic tools providedas part of this version of CPython.

  1. Your first C API extension module

Guides for intermediate topics

This section of the guide covers creating C and C++ extensions withoutassistance from third party tools. It is intended primarily for creatorsof those tools, rather than being a recommended way to create your ownC extensions.

Embedding the CPython runtime in a larger application

Sometimes, rather than creating an extension that runs inside the Pythoninterpreter as the main application, it is desirable to instead embedthe CPython runtime inside a larger application. This section coverssome of the details involved in doing that successfully.