Document that packaging doesn’t create __init__.py files (#3902).

The bug reported expected distutils to create an __init__.py file for a
project using only C extension modules.  IMO, how Python imports
packages and submodules is well documented, and it’s never suggested
that distutils might create an __init__.py file, so I’m adding this
clarification to the packaging docs but won’t backport unless other
people tell me they shared the same wrong expectation.

Thanks to Mike Hoy for his help with the patch.

diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
index d77197283d5b0cdf829ca5c9ef8eef84fd7b6232..89b6e45fdeb9ed892568fb71bcd95873a3b4ac3a 100644 (file)
--- a/Doc/library/packaging.compiler.rst
+++ b/Doc/library/packaging.compiler.rst
@@ -675,3 +675,7 @@ extension modules.
    |                        | abort the build process, but   |                           |
    |                        | simply skip the extension.     |                           |
    +------------------------+--------------------------------+---------------------------+
+
+To distribute extension modules that live in a package (e.g. ``package.ext``),
+you need to create you need to create a :file:`{package}/__init__.py` file to
+let Python recognize and import your module.

diff --git a/Doc/packaging/setupscript.rst b/Doc/packaging/setupscript.rst
index dbac3dd89f26dea15d76bf5210e57afbc26ef32a..cafde20e548f6adb6c24d40ea1f37ca351d8a2d0 100644 (file)
--- a/Doc/packaging/setupscript.rst
+++ b/Doc/packaging/setupscript.rst
@@ -177,6 +177,10 @@ resulting object code are identical in both cases; the only difference is where
 in the filesystem (and therefore where in Python's namespace hierarchy) the
 resulting extension lives.
 
+If your distribution contains only one or more extension modules in a package,
+you need to create a :file:`{package}/__init__.py` file anyway, otherwise Python
+won't be able to import anything.
+
 If you have a number of extensions all in the same package (or all under the
 same base package), use the :option:`ext_package` keyword argument to
 :func:`setup`.  For example, ::