30000 0 0 0 0  hnuma_hit 1104813216 numa_miss 0 numa_foreign 0 interleave_hit 13305 local_node 1104813216 other_node 0  h13:67 ,lm_JJhȮ2o 8_I|?.. highlightlang:: c .. _api-intro: ************ Introduction ************ The Application Programmer's Interface to Python gives C and C++ programmers access to the Python interpreter at a variety of levels. The API is equally usable from C++, but for brevity it is generally referred to as the Python/C API. There are two fundamentally different reasons for using the Python/C API. The first reason is to write *extension modules* for specific purposes; these are C modules that extend the Python interpreter. This is probably the most common use. The second reason is to use Python as a component in a larger application; this technique is generally referred to as :dfn:`embedding` Python in an application. Writing an extension module is a relatively well-understood process, where a "cookbook" approach works well. There are several tools that automate the process to some extent. While people have embedded Python in other applications since its early existence, the process of embedding Python is less straightforward than writing an extension. Many API functions are useful independent of whether you're embedding or extending Python; moreover, most applications that embed Python will need to provide a custom extension as well, so it's probably a good idea to become familiar with writing an extension before attempting to embed Python in a real application. .. _api-includes: Include Files ============= All function, type and macro definitions needed to use the Python/C API are included in your code by the following line:: #include "Python.h" This implies inclusion of the following standard headers: ````, ````, ````, ````, ```` and ```` (if available). .. note:: Since Python may define some pre-processor definitions which affect the standard headers on some systems, you *must* include :file:`Python.h` before any standard headers are included. All user visible names defined by Python.h (except those defined by the included standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning with ``_Py`` are for internal use by the Python implementation and should not be used by extension writers. Structure member names do not have a reserved prefix. **Important:** user code should never define names that begin with ``Py`` or ``_Py``. This confuses the reader, and jeopardizes the portability of the user code to future Python versions, which may define additional names beginning with one of these prefixes. The header files are typically installed with Python. On Unix, these are located in the directories :file:`{prefix}/include/pythonversion/` and :file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and :envvar:`exec_prefix` are defined by the corresponding parameters to Python's :program:`configure` script and *version* is ``sys.version[:3]``. On Windows, the headers are installed in :file:`{prefix}/include`, where :envvar:`prefix` is the installation directory specified to the installer. To include the headers, place both directories (if different) on your compiler's search path for includes. Do *not* place the parent directories on the search path and then use ``#include ``; this will break on multi-platform builds since the platform independent headers under :envvar:`prefix` include the platform specific headers from :envvar:`exec_prefix`. C++ users should note that though the API is defined entirely using C, the header files do properly declare the entry points to be ``extern "C"``, so there is no need to do anything special to use the API from C++. .. _api-objects: Objects, Types and Reference Counts =================================== .. index:: object: type Most Python/C API functions have one or more arguments as well as a return va