Merge pull request #2184 from jkleckner/add-no_zip_safe-to-documentation

Add zip_safe=False to userguide setup.py

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

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
 ============================

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()``.