255 lines
8.8 KiB
Plaintext
255 lines
8.8 KiB
Plaintext
PEP: 384
|
||
Title: Defining a Stable ABI
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Martin v. Löwis <martin@v.loewis.de>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 17-May-2009
|
||
Python-Version: 3.2
|
||
Post-History:
|
||
|
||
Abstract
|
||
========
|
||
|
||
Currently, each feature release introduces a new name for the
|
||
Python DLL on Windows, and may cause incompatibilities for extension
|
||
modules on Unix. This PEP proposes to define a stable set of API
|
||
functions which are guaranteed to be available for the lifetime
|
||
of Python 3, and which will also remain binary-compatible across
|
||
versions. Extension modules and applications embedding Python
|
||
can work with different feature releases as long as they restrict
|
||
themselves to this stable ABI.
|
||
|
||
Rationale
|
||
=========
|
||
|
||
The primary source of ABI incompatibility are changes to the lay-out
|
||
of in-memory structures. For example, the way in which string interning
|
||
works, or the data type used to represent the size of an object, have
|
||
changed during the life of Python 2.x. As a consequence, extension
|
||
modules making direct access to fields of strings, lists, or tuples,
|
||
would break if their code is loaded into a newer version of the
|
||
interpreter without recompilation: offsets of other fields may have
|
||
changed, making the extension modules access the wrong data.
|
||
|
||
In some cases, the incompatibilities only affect internal objects of
|
||
the interpreter, such as frame or code objects. For example, the way
|
||
line numbers are represented has changed in the 2.x lifetime, as has
|
||
the way in which local variables are stored (due to the introduction
|
||
of closures). Even though most applications probably never used these
|
||
objects, changing them had required to change the PYTHON_API_VERSION.
|
||
|
||
On Linux, changes to the ABI are often not much of a problem: the
|
||
system will provide a default Python installation, and many extension
|
||
modules are already provided pre-compiled for that version. If additional
|
||
modules are needed, or additional Python versions, users can typically
|
||
compile them themselves on the system, resulting in modules that use
|
||
the right ABI.
|
||
|
||
On Windows, multiple simultaneous installations of different Python
|
||
versions are common, and extension modules are compiled by their
|
||
authors, not by end users. To reduce the risk of ABI incompatibilities,
|
||
Python currently introduces a new DLL name pythonXY.dll for each
|
||
feature release, whether or not ABI incompatibilities actually exist.
|
||
|
||
With this PEP, it will be possible to reduce the dependency of binary
|
||
extension modules on a specific Python feature release, and applications
|
||
embedding Python can be made work with different releases.
|
||
|
||
Specification
|
||
=============
|
||
|
||
The ABI specification falls into two parts: an API specification,
|
||
specifying what function (groups) are available for use with the
|
||
ABI, and a linkage specification specifying what libraries to link
|
||
with. The actual ABI (layout of structures in memory, function
|
||
calling conventions) is not specified, but implied by the
|
||
compiler. As a recommendation, a specific ABI is recommended for
|
||
selected platforms.
|
||
|
||
During evolution of Python, new ABI functions will be added.
|
||
Applications using them will then have a requirement on a minimum
|
||
version of Python; this PEP provides no mechanism for such
|
||
applications to fall back when the Python library is too old.
|
||
|
||
Terminology
|
||
-----------
|
||
|
||
Applications and extension modules that want to use this ABI
|
||
are collectively referred to as "applications" from here on.
|
||
|
||
Header Files and Preprocessor Definitions
|
||
-----------------------------------------
|
||
|
||
Applications shall only include the header file Python.h (before
|
||
including any system headers), or, optionally, include pyconfig.h, and
|
||
then Python.h.
|
||
|
||
During the compilation of applications, the preprocessor macro
|
||
Py_LIMITED_API must be defined. Doing so will hide all definitions
|
||
that are not part of the ABI.
|
||
|
||
Structures
|
||
----------
|
||
|
||
Only the following structures and structure fields are accessible to
|
||
applications:
|
||
|
||
- PyObject (ob_refcnt, ob_type)
|
||
- PyVarObject (ob_base, ob_size)
|
||
- Py_buffer (buf, obj, len, itemsize, readonly, ndim, shape,
|
||
strides, suboffsets, smalltable, internal)
|
||
- PyMethodDef (ml_name, ml_meth, ml_flags, ml_doc)
|
||
- PyMemberDef (name, type, offset, flags, doc)
|
||
- PyGetSetDef (name, get, set, doc, closure)
|
||
|
||
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
|
||
|
||
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 an
|
||
easy creation of types (in particular, to be able to fill out
|
||
function pointers easily), the following structures and functions
|
||
are available::
|
||
|
||
typedef struct{
|
||
int slot; /* slot id, see below */
|
||
void *pfunc; /* function pointer */
|
||
} PyType_Slot;
|
||
|
||
struct{
|
||
const char* name;
|
||
const char* doc;
|
||
int basicsize;
|
||
int itemsize;
|
||
int flags;
|
||
PyType_Slot *slots; /* terminated by slot==0. */
|
||
} PyType_Spec;
|
||
|
||
PyObject* PyType_FromSpec(PyType_Spec*);
|
||
|
||
To specify a slot, a unique slot id must be provided. New Python
|
||
versions may introduce new slot ids, but slot ids will never be
|
||
recycled. Slots may get deprecated, but continue to be supported
|
||
throughout Python 3.x.
|
||
|
||
The slot ids are named like the field names of the structures that
|
||
hold the pointers in Python 3.1, with an added ``Py_`` prefix (i.e.
|
||
Py_tp_dealloc instead of just tp_dealloc):
|
||
|
||
- tp_dealloc, tp_print, 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_set, 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_power
|
||
nb_negative nb_positive nb_absolute nb_bool nb_invert nb_lshift
|
||
nb_rshift nb_and nb_xor nb_or nb_int nb_float nb_inplace_add
|
||
nb_inplace_subtract nb_inplace_multiply nb_inplace_remainder
|
||
nb_inplace_power nb_inplace_lshift nb_inplace_rshift nb_inplace_and
|
||
nb_inplace_xor nb_inplace_or nb_floor_divide nb_true_divide
|
||
nb_inplace_floor_divide nb_inplace_true_divide nb_index
|
||
- sq_length sq_concat sq_repeat sq_item sq_ass_item was_sq_ass_slice
|
||
sq_contains sq_inplace_concat sq_inplace_repeat
|
||
- mp_length mp_subscript mp_ass_subscript
|
||
- bf_getbuffer bf_releasebuffer
|
||
|
||
XXX Not supported yet: tp_weaklistoffset, tp_dictoffset
|
||
|
||
The following fields cannot be set during type definition:
|
||
- tp_dict tp_mro tp_cache tp_subclasses tp_weaklist
|
||
|
||
Functions and function-like Macros
|
||
----------------------------------
|
||
|
||
All functions starting with _Py are not available to applications.
|
||
Also, all functions that expect parameter types that are unavailable
|
||
to applications are excluded from the ABI, such as PyAST_FromNode
|
||
(which expects a ``node*``).
|
||
|
||
All other functions are available, unless excluded below.
|
||
|
||
Function-like macros (in particular, field access macros) remain
|
||
available to applications, but get replaced by function calls
|
||
(unless their definition only refers to features of the ABI, such
|
||
as the various _Check macros)
|
||
|
||
ABI function declarations will not change their parameters or return
|
||
types. If a change to the signature becomes necessary, a new function
|
||
will be introduced. If the new function is source-compatible (e.g. if
|
||
just the return type changes), an alias macro may get added to
|
||
redirect calls to the new function when the applications is
|
||
recompiled.
|
||
|
||
If continued provision of the old function is not possible, it may get
|
||
deprecated, then removed, in accordance with PEP 7, causing
|
||
applications that use that function to break.
|
||
|
||
Excluded Functions
|
||
------------------
|
||
|
||
Functions declared in the following header files are not part
|
||
of the ABI:
|
||
- cellobject.h
|
||
- classobject.h
|
||
- code.h
|
||
- frameobject.h
|
||
- funcobject.h
|
||
- genobject.h
|
||
- pyarena.h
|
||
- pydebug.h
|
||
- symtable.h
|
||
- token.h
|
||
- traceback.h
|
||
|
||
Global Variables
|
||
----------------
|
||
|
||
Global variables representing types and exceptions are available
|
||
to applications.
|
||
XXX provide a complete list.
|
||
|
||
XXX should restrict list of globals to truly "builtin" stuff,
|
||
excluding everything that can also be looked up through imports.
|
||
|
||
XXX may specify access to predefined types and exceptions through
|
||
the interpreter state, with appropriate Get macros.
|
||
|
||
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
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|