Add new PEP.
This commit is contained in:
Martin v. Löwis
parent
5d8326c547
commit
c6b64dd83b
|
|
@ -0,0 +1,254 @@
|
|||
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:
|
||||
Loading…
Reference in New Issue