Getting Started

Installation

Compilertools is available on PyPI and can be installed with pip:

pip install compilertools

Enabling compilertools in a Python package

This explains how to enable compilertools in a Python package:

Enabling compilertools import hook

The import hook is used to select the best version of a compiled module on build time. It needs to be initialized on module startup.

This can be done by simply importing compilertools on the top of the main module of the package (__init__.py depending of package architecture):

"""Main package __init__.py"""
try:
    import compilertools
except ImportError:
    # Reverts back to classic import behavior if compilertools not available
    # or imported on a non compatible Python version.
    pass

The try except block ensures that the package is imported correctly even if compilertools is not available or can’t run. In this case, compiled modules will be imported in compatibility mode, without optimisations.

Enabling compilertools on build

To generate multiple optimized compiled modules, compilertools needs to be initialized in the setup.py of the package.

This can be done by simply importing compilertools.build in setup.py just after used build library (like setuptools, distutils, …):

"""setup.py file"""
from setuptools import setup
try:
    import compilertools.build
except ImportError:
    # Reverts back to classic build behavior if compilertools imported
    # on a non compatible Python version.
    pass

Don’t forget to add compilertools as requirement for the package in the install_requires argument of inside setup.py.

The try except block ensures that setup.py can still be used on Python versions that are not supported by compilertools (Like Python 2). In this case, compiled modules will be build without optimization.

"""setup.py file, continued..."""
setup(
    # ...Others setup arguments...
    install_requires=['compilertools']
    )

And next ?

That’s its, compilertools is enabled on the package. Its configuration can be tweaked (See below) if needed, but it work with default value else.

You can now build the wheel package with setup.py bdist_wheel. If an user uses this generated wheel, Python will use the best optimized compiled file available inside the package for its machine.

If an user build your package with pip from source, it will get an automatically optimized file for its machine.

Configuring compilertools

Compilertools configuration is done with the compilertools.build.ConfigBuild object, simply by changing its parameters to adjust compilertools behavior as needed directly in setup.py:

"""setup.py file"""
try:
    import compilertools.build

    # Creates optimized modules only for AVX2 and AVX512 CPU instructions.
    compilertools.build.ConfigBuild.suffixes_includes = ['avx2', 'avx512']
except ImportError:
    pass

Read ConfigBuild documentation for available parameters.

compilertools exception

On import or on installation from PIP, compilertools exceptions are ignored ( only logged in stdout) to not break application.

In this case, no optimizations are enabled and module are compiled/loaded in compatible mode.