https://github.com/anxuae/setuptools-cythonize

Distribute python modules/packages as binary files (compilation based on Cython)
https://github.com/anxuae/setuptools-cythonize

cython python setuptools wheel

Last synced: about 2 months ago
JSON representation

Distribute python modules/packages as binary files (compilation based on Cython)

• Host: GitHub
• URL: https://github.com/anxuae/setuptools-cythonize
• Owner: anxuae
• License: mit
• Created: 2019-02-21T18:47:47.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2023-02-23T10:01:06.000Z (almost 2 years ago)
• Last Synced: 2024-09-20T03:42:04.666Z (3 months ago)
• Topics: cython, python, setuptools, wheel
• Language: Python
• Homepage:
• Size: 966 KB
• Stars: 40
• Watchers: 1
• Forks: 8
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        


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

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

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

   

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

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