setuptools-cythonize

.. image:: https://raw.githubusercontent.com/anxuae/setuptools-cythonize/master/docs/cythonize.png :align: center :alt: setuptools-cythonize

|PythonVersions| |PypiPackage| |Downloads|

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.

.. image:: https://raw.githubusercontent.com/anxuae/setuptools-cythonize/master/docs/cythonization.png :align: center :alt: cythonization

Install

::

 $> pip install setuptools-cythonize

Setup configuration

Add the cmdclass keyword to the setup:

.. code-block:: python

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 <https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatchcase>_ .

.. code-block:: python

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 <https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#compiler-options>_ can also be customized before running the setup:

.. code-block:: python

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:

.. code-block:: python

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

.. |PythonVersions| image:: https://img.shields.io/badge/python-2.7+ / 3.5+-red.svg :target: https://www.python.org/downloads :alt: Python 2.7+/3.5+

.. |PypiPackage| image:: https://badge.fury.io/py/setuptools-cythonize.svg :target: https://pypi.org/project/setuptools-cythonize :alt: PyPi package

.. |Downloads| image:: https://img.shields.io/pypi/dm/setuptools-cythonize?color=purple :target: https://pypi.org/project/setuptools-cythonize :alt: PyPi downloads