cython

Compile into C code

$ cython [path/to/file]

$ cython --cplus [path/to/file]

$ cython [[-o|--output-file]] [path/to/output_file] [path/to/file]

$ cython [[-V|--version]]

cython [OPTIONS] file.pyx ...

-o
    Specifies the name of the output C/C++ file. If not provided, it defaults to the input file name with a .c or .cpp extension.

--embed
    Embeds the Python interpreter into the generated C file, making it a standalone executable. Useful for distributing Cython applications without requiring a separate Python installation.

-a, --annotate
    Generates an annotated HTML file, showing the compiled C code alongside the original Cython code. This is invaluable for debugging and understanding performance bottlenecks by highlighting areas that interact with the Python interpreter.

--cplus
    Generates C++ code instead of C code. This is necessary when integrating with C++ libraries or using C++ features within Cython.

-D, --debug
    Enables debug facilities in the generated code, which can be useful during development to trace execution or inspect variables.

-v, --verbose
    Increases the verbosity of the output, showing more information about the compilation process.

--gdb
    Generates extra debugging information for GDB (GNU Debugger) to allow debugging the generated C code with GDB.

--no-docstrings
    Strips docstrings from the compiled module. This can slightly reduce the size of the compiled extension module.

--cleanup
    Controls the level of cleanup for temporary C files after compilation. Higher levels perform more aggressive cleanup.

The cython command-line tool is the primary interface for compiling Cython source files (with a .pyx extension) into C or C++ code. Cython itself is a superset of the Python language, allowing developers to write C extensions for Python using Python-like syntax, optionally adding static type declarations for significant performance improvements. This generated C/C++ code can then be compiled by a standard C/C++ compiler (like GCC or Clang) into a Python extension module (a .so file on Linux, or a .pyd on Windows).

The cython command handles the crucial transpilation step, translating the high-level Cython code into low-level C/C++ that can be directly compiled into machine code. This process enables Python programs to achieve near-C performance, especially for computationally intensive tasks, while still benefiting from Python's ease of use and rich ecosystem. It also facilitates easy interaction with existing C, C++, or Fortran libraries.

While cython automates the C/C++ generation, it does not handle the subsequent C/C++ compilation. This step requires a suitable C/C++ compiler (such as GCC, Clang, or MSVC) to be installed and configured on your system. Furthermore, achieving significant performance improvements often requires careful use of static type declarations within your Cython code; simply compiling Python code with Cython might not yield substantial speedups. For complex projects, it's generally recommended to integrate Cython into a build system like setuptools via a setup.py script, rather than calling the cython command directly, as build systems manage dependencies and compilation flags more effectively.

The typical workflow involves creating a .pyx file containing your Cython code. You then use the cython command to convert this .pyx file into a .c or .cpp file. Finally, this generated C/C++ file is compiled using a standard C/C++ compiler into a shared library (e.g., .so on Linux) that can be imported directly into Python as a module. For example:
cython my_module.pyx
gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/path/to/python/include -o my_module.so my_module.c

For larger projects, direct calls to the cython command are often replaced by integration with build systems like setuptools. A setup.py script can be configured to automatically find .pyx files, run the cython transpiler, and then compile the resulting C/C++ files, simplifying the build process and dependency management. This is the recommended approach for distributing Cython-based Python packages.

Cython originated as a fork of the Pyrex project, created by Greg Ewing. It was developed to address limitations in Pyrex, particularly with its integration with C++. The project saw significant growth and adoption, especially within the scientific Python community, providing a robust tool for creating high-performance Python extensions. Over the years, it has continuously evolved, adding support for newer Python versions, advanced type annotations, and better integration with C/C++ features, solidifying its position as a cornerstone for bridging Python's flexibility with C's speed.

gcc(1), python(1), make(1)