docs error: cythonize(include_path=x) does not set C include path

The documentation in compilation.rst claims that

cythonize(extensions, include_path=[numpy.get_include()])

adds the numpy include path to the include file search path used by the compiler. This has been quoted many times and the documented feature is used by many packages, although with zero effect: include_path only adds to the search path used by Cython to find pyx and pxd files.

Some alternative ways to address this:

1. Change docs to match code by removing the misleading section.
2. Change code to match docs by adding the feature.
3. Change docs and code to use cython(include_dirs=[]) as a way for globally specifying C include paths.
4. Change it all to have cython_include_dirs and c_include_dirs (or path).

3 has the benefit that code using include_path will continue to function as before (no effect on C include path), while making the feature people have obviously been expecting available. The term include_dir would then consistently (albeit not obviously) refer to the C includes and the term include_path to the Cython includes.

[makmanalp]

Having just hit this and spent a while trying to figure out how to work around it, I’d like to voice my support for solution #2 (I can’t see the harm, but I don’t know much about this, so …), but also just as an interim measure doing #1 or some variant to fix the docs, which is explicitly claiming something with numpy that doesn’t work. I know I’m not the only one to be mislead by this, just by how very often this issue shows up:

https://www.google.com/search?q=numpy%2Farrayobject.h'+file+not+found&oq=numpy%2Farrayobject.h'+file+not+found&aqs=chrome..69i57j69i58.427j0j7&sourceid=chrome&ie=UTF-8

For posterity, my interim solution was to pass in my own Extension() to cythonize, which does kinda take away from the benefit of having cythonize in the first place IMHO.

from setuptools import setup, Extension
from Cython.Build import cythonize
import numpy as np

setup(
    name='xyz',
    ext_modules=cythonize(
        Extension(
            "xyz",
            sources=[a/b.pyx"],
            include_dirs=[np.get_include()]
        )
    ),
    install_requires=["numpy"]
)

[native-api]

I’d say it’s not a doc bug but a Cython bug. cythonize produces an Extension object which has include_dirs as one of its attributes. cythonize should be setting this attribute.

>>> from Cython.Build import cythonize
>>> import numpy as np
>>> e=cythonize("test.pyx",include_path=[np.get_include()])
>>> len(e)
1
>>> e[0].include_dirs
[]