Author: martin.v.loewis Date: Mon Nov 29 00:38:22 2010 New Revision: 86853 Log: Finalize lists of types, functions, and variables. Modified: peps/trunk/pep-0384.txt Modified: peps/trunk/pep-0384.txt ============================================================================== --- peps/trunk/pep-0384.txt (original) +++ peps/trunk/pep-0384.txt Mon Nov 29 00:38:22 2010 @@ -104,6 +104,11 @@ - 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) +- 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. @@ -112,6 +117,12 @@ - PyThreadState - PyInterpreterState +- struct _frame +- struct symtable +- struct _node +- PyWeakReference +- PyLongObject +- PyTypeObject Type Objects ------------ @@ -166,15 +177,43 @@ - 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 tp_print +- tp_weaklistoffset tp_dictoffset + +typedefs +-------- + +In addition to the typedefs for structs listed above, the following +typedefs are available. Their inclusion in the ABI means that the +underlying type must not change on a platform (even though it may +differ across platforms). + +- Py_uintptr_t Py_intptr_t Py_ssize_t +- unaryfunc binaryfunc ternaryfunc inquiry lenfunc ssizeargfunc +ssizessizeargfunc ssizeobjargproc ssizessizeobjargproc objobjargproc +getbufferproc releasebufferproc objobjproc visitproc traverseproc +destructor getattrfunc getattrofunc setattrfunc setattrofunc reprfunc +hashfunc richcmpfunc getiterfunc iternextfunc descrgetfunc +descrsetfunc initproc newfunc allocfunc +- PyCFunction PyCFunctionWithKeywords PyNoArgsFunction + PyCapsule_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 definitions +of it on the same platform (depending on whether it uses narrow +or wide code units). Applications that need to access the contents +of a Unicode string can convert it to wchar_t. Functions and function-like Macros ---------------------------------- -All functions starting with _Py are not available to applications. +All functions starting with _Py are not available to applications +(see exceptions below). 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*``). @@ -202,37 +241,58 @@ Functions declared in the following header files are not part of 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 -- parsetok.h +- ucnhash.h In addition, functions expecting ``FILE*`` are not part of the ABI, to avoid depending on a specific version of the Microsoft C runtime DLL on Windows. +Module and type initalizer functions are not available +(PyByteArray_Init, PyByteArray_Fini, PyBytes_Fini, + PyCFunction_Fini, PyDict_Fini, PyFloat_ClearFreeList, + PyFloat_Fini, PyFrame_Fini, PyList_Fini, PyMethod_Fini, + PyOS_FiniInterrupts, PySet_Fini, PyTuple_Fini). + +Several functions dealing with interpreter implementation +details are not available: +- PyInterpreterState_Head, PyInterpreterState_Next, + PyInterpreterState_ThreadHead, PyThreadState_Next +- Py_SubversionRevision, Py_SubversionShortBranch + Py_FatalError will be moved from pydebug.h into some other header file (e.g. pyerrors.h). +The exact list of functions being available is given +in the Windows module definition file for python3.dll [1]_. + 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. +to applications. In addition, selected global variables referenced +in macros (such as Py_True and Py_False) are available. -XXX may specify access to predefined types and exceptions through -the interpreter state, with appropriate Get macros. +A complete list of global variable definitions is given in the +python3.def file [1]_; those declared DATA denote variables. Other Macros ------------ @@ -263,10 +323,6 @@ its API functions through /export linker options to the full interpreter DLL, i.e. python3y.dll. -XXX is it possible to redirect global variables in the same way? -If not, python3.dll would have to copy them, and we should verify -that all available global variables are read-only. - On Unix systems, the ABI is typically provided by the python executable itself. PyModule_Create is changed to pass ``3`` as the API version if the extension module was compiled with Py_LIMITED_API; the @@ -275,16 +331,23 @@ library, it is installed as both libpython3.so, and libpython3.y.so; applications conforming to this PEP should then link to the former. -XXX is it possible to make the soname libpython.so.3, and still -have some applications link to libpython3.y.so? - Implementation Strategy ======================= -This PEP will be implemented in a branch, allowing users to check +This PEP will be implemented in a branch [2]_, allowing users to check whether their modules conform to the ABI. To avoid users having to rewrite their type definitions, a script to convert C source code -containing type definitions will be provided. +containing type definitions will be provided [3]_. + +References +========== + +.. [1] "python3 module definition file": + http://svn.python.org/projects/python/branches/pep-0384/PC/python3.def +.. [2] "PEP 384 branch": + http://svn.python.org/projects/python/branches/pep-0384/ +.. [3] "ABI type conversion script": + http://svn.python.org/projects/python/branches/pep-0384/Tools/scripts/abityp... Copyright =========