setuptools-cythonize 1.0.7
Distribute python modules/packages as binary files (compilation based on Cython)
License: MIT license
Keywords: setup,install,compilation



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