Terminology

Applications and extension modules that want to use this ABIare collectively referred to as “applications” from here on.

Header Files and Preprocessor Definitions

Applications shall only include the header file Python.h (beforeincluding any system headers), or, optionally, include pyconfig.h, andthen Python.h.

During the compilation of applications, the preprocessor macroPy_LIMITED_API must be defined. Doing so will hide all definitionsthat are not part of the ABI.

Structures

Only the following structures and structure fields are accessible toapplications:

• PyObject (ob_refcnt, ob_type)
• PyVarObject (ob_base, ob_size)
• PyMethodDef (ml_name, ml_meth, ml_flags, ml_doc)
• PyMemberDef (name, type, offset, flags, doc)
• PyGetSetDef (name, get, set, doc, closure)
• PyModuleDefBase (ob_base, m_init, m_index, m_copy)
• PyModuleDef (m_base, m_name, m_doc, m_size, m_methods, m_traverse,m_clear, m_free)
• PyStructSequence_Field (name, doc)
• PyStructSequence_Desc (name, doc, fields, sequence)
• PyType_Slot (see below)
• PyType_Spec (see below)

The accessor macros to these fields (Py_REFCNT, Py_TYPE, Py_SIZE)are also available to applications.

The following types are available, but opaque (i.e. incomplete):

• PyThreadState
• PyInterpreterState
• struct _frame
• struct symtable
• struct _node
• PyWeakReference
• PyLongObject
• PyTypeObject

Type Objects

The structure of type objects is not available to applications;declaration of “static” type objects is not possible anymore(for applications using this ABI).Instead, type objects get created dynamically. To allow aneasy creation of types (in particular, to be able to fill outfunction pointers easily), the following structures and functionsare available:

typedefstruct{intslot;/*slotid,seebelow*/void*pfunc;/*functionpointer*/}PyType_Slot;typedefstruct{constchar*name;intbasicsize;intitemsize;unsignedintflags;PyType_Slot*slots;/*terminatedbyslot==0.*/}PyType_Spec;PyObject*PyType_FromSpec(PyType_Spec*);

To specify a slot, a unique slot id must be provided. New Pythonversions may introduce new slot ids, but slot ids will never berecycled. Slots may get deprecated, but continue to be supportedthroughout Python 3.x.

The slot ids are named like the field names of the structures thathold the pointers in Python 3.1, with an addedPy_ prefix (i.e.Py_tp_dealloc instead of just tp_dealloc):

• tp_dealloc, tp_getattr, tp_setattr, tp_repr,tp_hash, tp_call, tp_str, tp_getattro, tp_setattro,tp_doc, tp_traverse, tp_clear, tp_richcompare, tp_iter,tp_iternext, tp_methods, tp_base, tp_descr_get, tp_descr_set,tp_init, tp_alloc, tp_new, tp_is_gc, tp_bases, tp_del
• nb_add nb_subtract nb_multiply nb_remainder nb_divmod nb_powernb_negative nb_positive nb_absolute nb_bool nb_invert nb_lshiftnb_rshift nb_and nb_xor nb_or nb_int nb_float nb_inplace_addnb_inplace_subtract nb_inplace_multiply nb_inplace_remaindernb_inplace_power nb_inplace_lshift nb_inplace_rshift nb_inplace_andnb_inplace_xor nb_inplace_or nb_floor_divide nb_true_dividenb_inplace_floor_divide nb_inplace_true_divide nb_index
• sq_length sq_concat sq_repeat sq_item sq_ass_itemsq_contains sq_inplace_concat sq_inplace_repeat
• mp_length mp_subscript mp_ass_subscript

The following fields cannot be set during type definition:- tp_dict tp_mro tp_cache tp_subclasses tp_weaklist tp_print- tp_weaklistoffset tp_dictoffset

typedefs

In addition to the typedefs for structs listed above, the followingtypedefs are available. Their inclusion in the ABI means that theunderlying type must not change on a platform (even though it maydiffer across platforms).

• Py_uintptr_t Py_intptr_t Py_ssize_t
• unaryfunc binaryfunc ternaryfunc inquiry lenfunc ssizeargfuncssizessizeargfunc ssizeobjargproc ssizessizeobjargproc objobjargprocobjobjproc visitproc traverseprocdestructor getattrfunc getattrofunc setattrfunc setattrofunc reprfunchashfunc richcmpfunc getiterfunc iternextfunc descrgetfuncdescrsetfunc initproc newfunc allocfunc
• PyCFunction PyCFunctionWithKeywords PyNoArgsFunctionPyCapsule_Destructor
• getter setter
• PyOS_sighandler_t
• PyGILState_STATE
• Py_UCS4

Most notably, Py_UNICODE is not available as a typedef,since the same Python version may use different definitionsof it on the same platform (depending on whether it uses narrowor wide code units). Applications that need to access the contentsof a Unicode string can convert it to wchar_t.

Functions and function-like Macros

By default, all functions are available, unless they are excludedbelow.Whether a function is documented or not does not matter.

Function-like macros (in particular, field access macros) remainavailable to applications, but get replaced by function calls(unless their definition only refers to features of the ABI, suchas the various _Check macros)

ABI function declarations will not change their parameters or returntypes. If a change to the signature becomes necessary, a new functionwill be introduced. If the new function is source-compatible (e.g. ifjust the return type changes), an alias macro may get added toredirect calls to the new function when the applications isrecompiled.

If continued provision of the old function is not possible, it may getdeprecated, then removed, causingapplications that use that function to break.

Excluded Functions

All functions starting with _Py are not available to applications.Also, all functions that expect parameter types that are unavailableto applications are excluded from the ABI, such as PyAST_FromNode(which expects anode*).

Functions declared in the following header files are not partof the ABI:

• bytes_methods.h
• cellobject.h
• classobject.h
• code.h
• compile.h
• datetime.h
• dtoa.h
• frameobject.h
• funcobject.h
• genobject.h
• longintrepr.h
• parsetok.h
• pyarena.h
• pyatomic.h
• pyctype.h
• pydebug.h
• pytime.h
• symtable.h
• token.h
• ucnhash.h

In addition, functions expectingFILE* are not part ofthe ABI, to avoid depending on a specific version of theMicrosoft C runtime DLL on Windows.

Module and type initializer and finalizer functions are not available(PyByteArray_Init, PyOS_FiniInterruptsand all functions ending in _Fini or _ClearFreeList).

Several functions dealing with interpreter implementationdetails are not available:

• PyInterpreterState_Head, PyInterpreterState_Next,PyInterpreterState_ThreadHead, PyThreadState_Next
• Py_SubversionRevision, Py_SubversionShortBranch

PyStructSequence_InitType is not available, as it requiresthe caller to provide a static type object.

Py_FatalError will be moved from pydebug.h into some otherheader file (e.g. pyerrors.h).

The exact list of functions being available is givenin the Windows module definition file for python3.dll[1].

Global Variables

Global variables representing types and exceptions are availableto applications. In addition, selected global variables referencedin macros (such as Py_True and Py_False) are available.

A complete list of global variable definitions is given in thepython3.def file[1]; those declared DATA denote variables.

Other Macros

All macros defining symbolic constants are available to applications;the numeric values will not change.

In addition, the following macros are available:

• Py_BEGIN_ALLOW_THREADS, Py_BLOCK_THREADS, Py_UNBLOCK_THREADS,Py_END_ALLOW_THREADS

The Buffer Interface

The buffer interface (type Py_buffer, type slots bf_getbuffer andbf_releasebuffer, etc) has been omitted from the ABI, since the stabilityof the Py_buffer structure is not clear at this time. Inclusion in theABI can be considered in future releases.

Signature Changes

A number of functions currently expect a specific struct, even thoughcallers typically have PyObject* available. These have been changedto expect PyObject* as the parameter; this will cause warnings inapplications that currently explicitly cast to the parameter type.These functions are PySlice_GetIndices, PySlice_GetIndicesEx,PyUnicode_AsWideChar, and PyEval_EvalCode.

Linkage

On Windows, applications shall link with python3.dll; an importlibrary python3.lib will be available. This DLL will redirect all ofits API functions through /export linker options to the fullinterpreter DLL, i.e. python3y.dll.

On Unix systems, the ABI is typically provided by the pythonexecutable itself. PyModule_Create is changed to pass3 as the APIversion if the extension module was compiled with Py_LIMITED_API; theversion check for the API version will accept either 3 or the currentPYTHON_API_VERSION as conforming. If Python is compiled as a sharedlibrary, it is installed as both libpython3.so, and libpython3.y.so;applications conforming to this PEP should then link to the former(extension modules can continue to link with no libpython shared object,but rather rely on runtime linking).The ABI version is symbolically available asPYTHON_ABI_VERSION.

Also on Unix, thePEP 3149 tag abi<PYTHON_ABI_VERSION> is acceptedin file names of extension modules. No checking is performed thatfiles named in this way are actually restricted to the limited API,and no support for building such files will be added to distutilsdue to the distutils code freeze.