Merge pull request #1312 from coldrye-collaboration/gh-97

fix #97 PEP420: find_packages()

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index 511a9898..0660e14d 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -57,6 +57,9 @@ Feature Highlights:
 * Create extensible applications and frameworks that automatically discover
   extensions, using simple "entry points" declared in a project's setup script.
 
+* Full support for PEP 420 via ``find_packages_ns()``, which is also backwards
+  compatible to the existing ``find_packages()`` for Python >= 3.3.
+
 .. contents:: **Table of Contents**
 
 .. _ez_setup.py: `bootstrap module`_
@@ -459,6 +462,67 @@ argument in your setup script.  Especially since it frees you from having to
 remember to modify your setup script whenever your project grows additional
 top-level packages or subpackages.
 
+``find_packages_ns()``
+----------------------
+In Python 3.3+, ``setuptools`` also provides the ``find_packages_ns`` variant
+of ``find_packages``, which has the same function signature as
+``find_packages``, but works with `PEP 420`_ compliant implicit namespace
+packages. Here is a minimal setup script using ``find_packages_ns``::
+
+    from setuptools import setup, find_packages_ns
+    setup(
+        name="HelloWorld",
+        version="0.1",
+        packages=find_packages_ns(),
+    )
+
+
+Keep in mind that according to PEP 420, you may have to either re-organize your
+codebase a bit or define a few exclusions, as the definition of an implicit
+namespace package is quite lenient, so for a project organized like so::
+
+
+    ├── namespace
+    │   └── mypackage
+    │       ├── __init__.py
+    │       └── mod1.py
+    ├── setup.py
+    └── tests
+        └── test_mod1.py
+
+A naive ``find_packages_ns()`` would install both ``namespace.mypackage`` and a
+top-level package called ``tests``! One way to avoid this problem is to use the
+``include`` keyword to whitelist the packages to include, like so::
+
+    from setuptools import setup, find_packages_ns
+
+    setup(
+        name="namespace.mypackage",
+        version="0.1",
+        packages=find_packages_ns(include=['namespace.*'])
+    )
+
+Another option is to use the "src" layout, where all package code is placed in
+the ``src`` directory, like so::
+
+
+    ├── setup.py
+    ├── src
+    │   └── namespace
+    │       └── mypackage
+    │           ├── __init__.py
+    │           └── mod1.py
+    └── tests
+        └── test_mod1.py
+
+With this layout, the package directory is specified as ``src``, as such::
+
+    setup(name="namespace.mypackage",
+          version="0.1",
+          package_dir={'': 'src'},
+          packages=find_packages_ns(where='src'))
+
+.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 
 Automatic Script Creation
 =========================