Finalize lists of types, functions, and variables.

pep-0384.txt

@@ -104,6 +104,11 @@ applications:
 - 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 @@ The following types are available, but opaque (i.e. incomplete):
 
 - PyThreadState
 - PyInterpreterState
+- struct _frame
+- struct symtable
+- struct _node
+- PyWeakReference
+- PyLongObject
+- PyTypeObject
 
 Type Objects
 ------------
@@ -166,15 +177,43 @@ Py_tp_dealloc instead of just tp_dealloc):
 - 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 @@ Excluded Functions
 
 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.
+to applications. In addition, selected global variables referenced
+in macros (such as Py_True and Py_False) are available.
 
-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.
+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 @@ library python3.lib will be available. This DLL will redirect all of
 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 @@ PYTHON_API_VERSION as conforming. If Python is compiled as a shared
 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/abitype.py
 
 Copyright
 =========