Close #24458: PEP 489 documentation

Patch by Petr Viktorin.

Doc/c-api/init.rst

@@ -873,6 +873,8 @@ been created.
       instead.
 
 
+.. _sub-interpreter-support:
+
 Sub-interpreter support
 =======================
 

Doc/extending/building.rst

 .. highlightlang:: c
 
-
 .. _building:
 
-********************************************
-Building C and C++ Extensions with distutils
-********************************************
+*****************************
+Building C and C++ Extensions
+*****************************
 
-.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
+``.pyd`` on Windows), which exports an *initialization function*.
+
+To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
+and must be named after the module name, with an appropriate extension.
+When using distutils, the correct filename is generated automatically.
+
+The initialization function has the signature:
+
+.. c:function:: PyObject* PyInit_modulename(void)
+
+It returns either a fully-initialized module, or a :c:type:`PyModuleDef`
+instance. See :ref:`initializing-modules` for details.
+
+.. highlightlang:: python
 
+For modules with ASCII-only names, the function must be named
+``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
+module. When using :ref:`multi-phase-initialization`, non-ASCII module names
+are allowed. In this case, the initialization function name is
+``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
+*punycode* encoding with hyphens replaced by underscores. In Python::
 
-Starting in Python 1.4, Python provides, on Unix, a special make file for
-building make files for building dynamically-linked extensions and custom
-interpreters.  Starting with Python 2.0, this mechanism (known as related to
-Makefile.pre.in, and Setup files) is no longer supported. Building custom
-interpreters was rarely used, and extension modules can be built using
-distutils.
+    def initfunc_name(name):
+        try:
+            suffix = b'_' + name.encode('ascii')
+        except UnicodeEncodeError:
+            suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
+        return b'PyInit' + suffix
+
+It is possible to export multiple modules from a single shared library by
+defining multiple initialization functions. However, importing them requires
+using symbolic links or a custom importer, because by default only the
+function corresponding to the filename is found.
+See :PEP:`489#multiple-modules-in-one-library` for details.
+
+
+.. highlightlang:: c
+
+Building C and C++ Extensions with distutils
+============================================
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
 
-Building an extension module using distutils requires that distutils is
-installed on the build machine, which is included in Python 2.x and available
-separately for Python 1.5. Since distutils also supports creation of binary
-packages, users don't necessarily need a compiler and distutils to install the
-extension.
+Extension modules can be built using distutils,  which is included in Python.
+Since distutils also supports creation of binary packages, users don't
+necessarily need a compiler and distutils to install the extension.
 
 A distutils package contains a driver script, :file:`setup.py`. This is a plain
 Python file, which, in the most simple case, could look like this::

Doc/extending/extending.rst

@@ -413,6 +413,13 @@ A more substantial example module is included in the Python source distribution
 as :file:`Modules/xxmodule.c`.  This file may be used as a  template or simply
 read as an example.
 
+.. note::
+
+   Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization*
+   (new in Python 3.5), where a PyModuleDef structure is returned from
+   ``PyInit_spam``, and creation of the module is left to the import machinery.
+   For details on multi-phase initialization, see :PEP:`489`.
+
 
 .. _compilation:
 

Doc/extending/windows.rst

@@ -98,9 +98,8 @@ described here are distributed with the Python sources in the
    it.  Copy your C sources into it.  Note that the module source file name does
    not necessarily have to match the module name, but the name of the
    initialization function should match the module name --- you can only import a
-   module :mod:`spam` if its initialization function is called :c:func:`initspam`,
-   and it should call :c:func:`Py_InitModule` with the string ``"spam"`` as its
-   first argument (use the minimal :file:`example.c` in this directory as a guide).
+   module :mod:`spam` if its initialization function is called :c:func:`PyInit_spam`,
+   (see :ref:`building`, or use the minimal :file:`Modules/xxmodule.c` as a guide).
    By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.
    The output file should be called :file:`spam.pyd` (in Release mode) or
    :file:`spam_d.pyd` (in Debug mode). The extension :file:`.pyd` was chosen

Doc/whatsnew/3.5.rst

@@ -283,7 +283,7 @@ two step module loading mechanism introduced by :pep:`451` in Python 3.4.
 
 This change brings the import semantics of extension modules that opt-in to
 using the new mechanism much closer to those of Python source and bytecode
-modules, including the ability to any valid identifier as a module name,
+modules, including the ability to use any valid identifier as a module name,
 rather than being restricted to ASCII.
 
 .. seealso::
@@ -763,7 +763,7 @@ unicodedata
 -----------
 
 * The :mod:`unicodedata` module now uses data from `Unicode 8.0.0
-<http://unicode.org/versions/Unicode8.0.0/>`_.
+  <http://unicode.org/versions/Unicode8.0.0/>`_.
 
 
 wsgiref

Misc/NEWS

@@ -92,6 +92,9 @@ Tests
 Documentation
 -------------
 
+- Issue #24458: Update documentation to cover multi-phase initialization for
+  extension modules (PEP 489). Patch by Petr Viktorin.
+
 - Issue #24351: Clarify what is meant by "identifier" in the context of
   string.Template instances.