The setuptools-cythonize provides distutils classes to compile Python source code into C code using Cython. The generated code is packaged into a platform dependent archive.

Install

$> pip install setuptools-cythonize

Setup configuration

Add the cmdclass keyword to the setup:

from setuptools import setup
from setuptools_cythonize import get_cmdclass

setup(
    cmdclass=get_cmdclass(),
    name="my_package",
    version="2.0.5",
    description="My custom library",
    ...
)

Note

the function get_cmdclass() force wheel as default format (recommended format for binary distribution). This behavior can be disabled by passing the parameter wheel_default=False.

Some packages can be excluded from the cythonization by setting the exclude_cythonize option. The module names matching is done using the function fnmatch.fnmatchcase .

from setuptools import setup
from setuptools_cythonize import get_cmdclass

setup(
    cmdclass=get_cmdclass(),
    name="my_package",
    ...
    options={
        'build_py':
            {'exclude_cythonize': ['my_package.subpack*']}
    },
    ...
)

Note

some Python modules starting with __ are excluded from the cythonization. This includes:

• the __init__.py files which are mandatory to keep the Python packages integrity
• the __main__.py file in order to exectute the package using the command python -m ...

The Cython compiler options can also be customized before running the setup:

from setuptools import setup

from Cython.Compiler import Options

Options.docstrings = False

setup(
    ...
)

To speedup files compilation, the cythonization can be performed in parallel by setting the parallel option. The number of CPUs availbale can be retrived using the multiprocessing module. For instance:

import multiprocessing
from setuptools import setup
from setuptools_cythonize import get_cmdclass

setup(
    cmdclass=get_cmdclass(),
    name="my_package",
    ...
    options={
        'build_ext':
            {'parallel': multiprocessing.cpu_count()}
    },
    ...
)

Packaging

Generate your package by executing the setup.py file, all Python modules (except the ones defined in exclude_cythonize) will be compiled and packaged:

$> python setup.py bdist --cythonize

A source package can still be generated by removing the --cythonize option:

$> python setup.py bdist

!:warning: If you want upload binary wheel on PyPI, read the PEP 513 – A Platform Tag for Portable Linux Built ⚠️!