hatch-cython

CI/CD
Package
Meta

Table of Contents

• Usage
• Installation
  • Build System Requirements for Library Includes
• Configuration Options
  • Platform-Specific Arguments
  • Files
  • Explicit Build Targets
• Source Distributions
• Templating
• Notes
• Development
• License

Usage

The build hook plugin name is cython. It can be configured either globally (applies to all build targets) or specifically for the wheel target.

Installation

Add hatch-cython to your build dependencies in pyproject.toml:

[build-system]
requires = ["hatchling", "hatch-cython", "Cython", "setuptools"]
build-backend = "hatchling.build"

Important: Cython and setuptools must be included in build-system.requires because the build hook imports Cython modules at load time, before hook-specific dependencies are resolved.

Build System Requirements for Library Includes

When using include_numpy, include_pyarrow, include_pythran, or custom include_{package} options, those packages must also be added to build-system.requires. This is because hatch-cython imports these packages at hook initialization to resolve their include paths.

Example with NumPy:

[build-system]
requires = ["hatchling", "hatch-cython", "Cython", "setuptools", "numpy"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel.hooks.cython]
dependencies = ["hatch-cython"]

[tool.hatch.build.targets.wheel.hooks.cython.options]
include_numpy = true
define_macros = [["NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION"]]

Example with PyArrow:

[build-system]
requires = ["hatchling", "hatch-cython", "Cython", "setuptools", "pyarrow"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel.hooks.cython]
dependencies = ["hatch-cython"]

[tool.hatch.build.targets.wheel.hooks.cython.options]
include_pyarrow = true

Hook Configuration Locations

You can define the hook in several locations depending on your needs:

Basic Example (pyproject.toml)

[build-system]
requires = ["hatchling", "hatch-cython", "Cython", "setuptools"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel.hooks.cython]
dependencies = ["hatch-cython"]

[tool.hatch.build.targets.wheel.hooks.cython.options]
# Include directories for .h or .cpp files
includes = []

# Include headers from common scientific packages
include_numpy = false
include_pyarrow = false

# Custom library integration (see "Custom Library Includes" section)
include_somelib = {
    pkg = "somelib",              # module name (must be in dependencies)
    include = "gets_include",      # somelib.gets_include() -> str | list[str]
    libraries = "gets_libraries",  # somelib.gets_libraries() -> list[str]
    library_dirs = "gets_library_dirs",  # somelib.gets_library_dirs() -> list[str]
    required_call = "some_setup_op"      # somelib.some_setup_op() called before build
}

# Cython compiler directives
directives = { boundscheck = false, nonecheck = false, language_level = 3, binding = true }

# Additional keyword arguments passed to setuptools.Extension()
compile_kwargs = { }

Basic Example (hatch.toml)

[build.targets.wheel.hooks.cython]
dependencies = ["hatch-cython"]

[build.targets.wheel.hooks.cython.options]
directives = { boundscheck = false, nonecheck = false, language_level = 3, binding = true }
compile_args = ["-O3"]
includes = []
include_numpy = false

# Example: equivalent to include_pyarrow = true
include_somelib = { pkg = "pyarrow", include = "get_include", libraries = "get_libraries", library_dirs = "get_library_dirs", required_call = "create_library_symlinks" }

define_macros = [
    ["NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION"],
]

Configuration Options

All options are specified under [tool.hatch.build.targets.wheel.hooks.cython.options] (pyproject.toml) or [build.targets.wheel.hooks.cython.options] (hatch.toml).

Platform-Specific Arguments

The compile_args and extra_link_args fields support platform-specific configuration using objects with the following fields:

Note: The "anon" architecture value matches systems that return an empty string for platform.machine(), which can occur in some containerized or emulated environments.

PEP 508 Markers

The marker field accepts standard PEP 508 environment markers for conditional compilation. Common variables include:

• python_version - Python version (e.g., "3.10")
• python_full_version - Full Python version (e.g., "3.10.12")
• os_name - OS name ("posix", "nt", "java")
• sys_platform - System platform ("linux", "darwin", "win32")
• platform_machine - Machine architecture ("x86_64", "arm64")
• platform_system - System name ("Linux", "Darwin", "Windows")
• implementation_name - Python implementation ("cpython", "pypy")

Examples:

compile_args = [
  # Simple string argument (applies to all platforms)
  "-v",

  # Platform-specific
  { platforms = ["linux", "darwin"], arg = "-Wcpp" },

  # Platform and architecture specific
  { platforms = "darwin", arch = "x86_64", arg = "-arch x86_64" },
  { platforms = "darwin", arch = "arm64", arg = "-arch arm64" },

  # Only include if path exists (useful for optional dependencies)
  { platforms = "darwin", arg = "-I/opt/homebrew/include", depends_path = true },

  # Only for Python 3.10 and earlier
  { arg = "-I/legacy/include", marker = "python_version <= '3.10'" },

  # Only for CPython (not PyPy)
  { arg = "-DCPYTHON_ONLY", marker = "implementation_name == 'cpython'" },

  # Combine platform, arch, path check, and marker
  { platforms = "darwin", arch = "x86_64", arg = "-I/usr/local/opt/llvm/include", depends_path = true, marker = "python_version < '3.11'" },

  # Complex marker expressions
  { arg = "-DOLD_ABI", marker = "python_version < '3.9' or implementation_name == 'pypy'" },
]

Files

The files section controls which files are included or excluded from compilation.

[build.targets.wheel.hooks.cython.options.files]
exclude = [
    # Anything matching this pattern is ignored by cython
    "*/no_compile/*",

    # Note: "*" in patterns is converted to "([^\s]*)" (non-whitespace regex)
    # For a literal regex asterisk, use the full regex syntax:
    "([^.]\\*).(pyd$|pytempl$)",

    # Platform-specific exclusions (exclude on all OTHER platforms)
    { matches = "*/windows", platforms = ["linux", "darwin", "freebsd"] },
    { matches = "*/darwin", platforms = ["linux", "freebsd", "windows"] },
    { matches = "*/linux", platforms = ["darwin", "freebsd", "windows"] },
    { matches = "*/freebsd", platforms = ["linux", "darwin", "windows"] },
]

# Rename modules in the final build
aliases = {"mylib._internal" = "mylib.public_name"}

Explicit Build Targets

By default, hatch-cython compiles all .pyx files (and .py files if compile_py = true). To compile only specific files, use options.files.targets:

[build.targets.wheel.hooks.cython.options.files]
targets = [
  # String pattern
  "*/compile.py",

  # Platform-specific targets
  { matches = "*/windows", platforms = ["windows"] },
  { matches = "*/posix", platforms = ["darwin", "freebsd", "linux"] },
]

When targets is specified, only matching files are compiled. This also implicitly enables compilation of .py, .c, .cpp, and .cc files that match the patterns.

Source Distributions

Source distributions (sdist) work normally with hatch-cython. When building an sdist:

1. Hatch automatically installs hatch-cython as specified in your build dependencies
2. Platform-specific compile arguments are evaluated but compilation is skipped
3. Template files (.pyx.in, .pyi.in, etc.) can be processed and included
4. Generated .c and .cpp files can optionally be included in the sdist

Note: If hatch-cython runs during a non-wheel build target, the extension compilation is skipped. The generated intermediate files (.c, .cpp) may still be included if desired, though the compile arguments will differ per-platform at install time.

Templating

hatch-cython supports Cython Tempita templates for generating code at build time. Any file with a .in suffix is processed as a template:

Supported template extensions:

• .pyx.in → .pyx
• .pxd.in → .pxd
• .pyi.in → .pyi
• .py.in → .py
• .c.in → .c
• .cpp.in → .cpp

Template Example

Source file (templated.pyx.in):

{{for typ in supported}}

cpdef {{typ}} add_{{typ}}({{typ}} a, {{typ}} b):
    return a + b

{{endfor}}

With configuration:

[build.targets.wheel.hooks.cython.options.templates]
global = { supported = ["int", "float", "double"] }

Generated output (templated.pyx):

cpdef int add_int(int a, int b):
    return a + b

cpdef float add_float(float a, float b):
    return a + b

cpdef double add_double(double a, double b):
    return a + b

Module Aliasing with Templates

Templates can be combined with aliases to rename modules:

[build.targets.wheel.hooks.cython.options.files]
aliases = {"mylib._templated" = "mylib.templated"}

Build process:

1. Source: _templated.pyx.in, templated.pyi.in
2. After template processing: _templated.pyx, templated.pyi
3. Final module: mylib.templated

Template Arguments

Templates receive keyword arguments based on matching rules. Configure these in the templates section:

[build.targets.wheel.hooks.cython.options.templates]
# Index defines which keyword sets apply to which files
index = [
  { keyword = "global", matches = "*" },
  { keyword = "mac_types", matches = "templated.*.in", platforms = ["darwin"] },
  { keyword = "win_types", matches = "templated.*.in", platforms = ["windows"] },
  { keyword = "win_x64_types", matches = "templated.*.in", platforms = ["windows"], arch = ["x86_64"] },
  { keyword = "py38_compat", matches = "*.in", marker = "python_version == '3.8'" },
]

# Keyword argument sets
global = { supported = ["int"] }
mac_types = { supported = ["int", "float"] }
win_types = { supported = ["int", "float", "complex"] }
win_x64_types = { supported = ["int", "float", "double", "complex"] }
py38_compat = { use_legacy_api = true }

Matching behavior:

• global is always evaluated first and can be overridden by other matches
• Multiple matching keywords are merged in FIFO order (first defined takes precedence for conflicts)
• Each index entry supports platforms, arch, and marker for conditional matching

Example merge:

# Given matches: global, mac_types
# global = { supported = ["int"], extra = "value" }
# mac_types = { supported = ["int", "float"] }
# Result: { supported = ["int", "float"], extra = "value" }

See the test_libraries/src_structure directory for complete working examples.

Notes

macOS

• Users with Homebrew installed will automatically have brew --prefix library and include paths added during compilation

• GitHub Actions runners now use Apple Silicon (M1) for macOS. If using M1 runners, disable macos-max-compat:

  # hatch.toml
  [build.targets.wheel]
  macos-max-compat = false
  

OpenMP on macOS

To use parallel = true on macOS, you need Homebrew's LLVM instead of Apple's Clang:

brew install llvm libomp

The plugin automatically detects Homebrew's LLVM and adds the appropriate include/library paths.

Development

Requirements

• C/C++ compiler (gcc, clang, or MSVC)
• Python 3.8 - 3.13
• Mise

Development Scripts

License

hatch-cython is distributed under the terms of the MIT license.