Add zip_safe=False to userguide setup.py

This adds notes in the documentation to include zip_safe=False when
using setuptools instead of distutils for setup.py.

Because cimport will not load pxd definitions from a zipped egg file and
the default format when installing from a source package using
setuptools and "python setup.py install" is to create a zipped egg,
including this option will guard against this error when people install
this way.

3 files changed, 23 insertions, 0 deletions

diff --git a/docs/src/quickstart/build.rst b/docs/src/quickstart/build.rst
index 9cc6a4561..68d63d811 100644
--- a/docs/src/quickstart/build.rst
+++ b/docs/src/quickstart/build.rst
@@ -56,6 +56,12 @@ To build, run ``python setup.py build_ext --inplace``.  Then simply
 start a Python session and do ``from hello import say_hello_to`` and
 use the imported function as you see fit.
 
+One caveat if you use setuptools instead of distutils, the default
+action when running ``python setup.py install`` is to create a zipped
+``egg`` file which will not work with ``cimport`` for ``pxd`` files
+when you try to use them from a dependent package.
+To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
+
 .. _jupyter-notebook:
 
 Using the Jupyter notebook
diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst
index 34f2bf260..8462cd957 100644
--- a/docs/src/reference/compilation.rst
+++ b/docs/src/reference/compilation.rst
@@ -140,6 +140,12 @@ Note that when using setuptools, you should import it before Cython as
 setuptools may replace the ``Extension`` class in distutils.  Otherwise,
 both might disagree about the class to use here.
 
+Note also that if you use setuptools instead of distutils, the default
+action when running ``python setup.py install`` is to create a zipped
+``egg`` file which will not work with ``cimport`` for ``pxd`` files
+when you try to use them from a dependent package.
+To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
+
 If your options are static (for example you do not need to call a tool like
 ``pkg-config`` to determine them) you can also provide them directly in your
 .pyx or .pxd source file using a special comment block at the start of the file::
@@ -324,6 +330,12 @@ e.g.::
 These ``.pxd`` files need not have corresponding ``.pyx``
 modules if they contain purely declarations of external libraries.
 
+Remember that if you use setuptools instead of distutils, the default
+action when running ``python setup.py install`` is to create a zipped
+``egg`` file which will not work with ``cimport`` for ``pxd`` files
+when you try to use them from a dependent package.
+To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
+
 
 Integrating multiple modules
 ============================
diff --git a/docs/src/userguide/sharing_declarations.rst b/docs/src/userguide/sharing_declarations.rst
index 42214ba3a..24e15114f 100644
--- a/docs/src/userguide/sharing_declarations.rst
+++ b/docs/src/userguide/sharing_declarations.rst
@@ -263,3 +263,8 @@ Some things to note about this example:
   doesn't bind the name Shrubbing in Landscaping's module namespace at run
   time, so to access :func:`Shrubbing.standard_shrubbery` we also need to
   ``import Shrubbing``.
+* One caveat if you use setuptools instead of distutils, the default
+  action when running ``python setup.py install`` is to create a zipped
+  ``egg`` file which will not work with ``cimport`` for ``pxd`` files
+  when you try to use them from a dependent package.
+  To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.