Cython

Not to be confused with CPython.

Cython

Developer	Robert Bradshaw, Stefan Behnel, et al.
First appeared	28 July 2007 (2007-07-28)
Stable release	3.0.11-1  (5 August 2024 (5 August 2024)) [±]
Preview release	3.0.0 beta 2 (27 March 2023 (2023-03-27)) [±]
Implementation language	Python
OS	Windows, macOS, Linux
License	Apache License 2.0
Filename extensions	.pyx, .pxd, .pxi
Website	cython.org
Influenced by
C, Python

Cython (/ˈsaɪθɒn/) is a superset of the programming language Python, which allows developers to write Python code (with optional, C-inspired syntax extensions) that yields performance comparable to that of C.

Cython is a compiled language that is typically used to generate CPython extension modules. Annotated Python-like code is compiled to C and then automatically wrapped in interface code, producing extension modules that can be loaded and used by regular Python code using the import statement, but with significantly less computational overhead at run time. Cython also facilitates wrapping independent C or C++ code into python-importable modules.

Cython is written in Python and C and works on Windows, macOS, and Linux, producing C source files compatible with CPython 2.6, 2.7, and 3.3 and later versions. The Cython source code that Cython compiles (to C) can use both Python 2 and Python 3 syntax, defaulting to Python 2 syntax in Cython 0.x and Python 3 syntax in Cython 3.x. The default can be overridden (e.g. in source code comment) to Python 3 (or 2) syntax. Since Python 3 syntax has changed in recent versions, Cython may not be up to date with the latest additions. Cython has "native support for most of the C++ language" and "compiles almost all existing Python code".

Cython 3.0.0 was released on 17 July 2023.

Design

Cython works by producing a standard Python module. However, the behavior differs from standard Python in that the module code, originally written in Python, is translated into C. While the resulting code is fast, it makes many calls into the CPython interpreter and CPython standard libraries to perform actual work. Choosing this arrangement saved considerably on Cython's development time, but modules have a dependency on the Python interpreter and standard library.

Although most of the code is C-based, a small stub loader written in interpreted Python is usually required (unless the goal is to create a loader written entirely in C, which may involve work with the undocumented internals of CPython). However, this is not a major problem due to the presence of the Python interpreter.

Cython has a foreign function interface for invoking C/C++ routines and the ability to declare the static type of subroutine parameters and results, local variables, and class attributes.

A Cython program that implements the same algorithm as a corresponding Python program may consume fewer computing resources such as core memory and processing cycles due to differences between the CPython and Cython execution models. A basic Python program is loaded and executed by the CPython virtual machine, so both the runtime and the program itself consume computing resources. A Cython program is compiled to C code, which is further compiled to machine code, so the virtual machine is used only briefly when the program is loaded.

Cython employs:

• Optimistic optimizations
• Type inference (optional)
• Low overhead in control structures
• Low function call overhead

Performance depends both on what C code is generated by Cython and how that code is compiled by the C compiler.

History

Cython is a derivative of the Pyrex language, but it supports more features and optimizations than Pyrex. Cython was forked from Pyrex in 2007 by developers of the Sage computer algebra package, because they were unhappy with Pyrex's limitations and could not get patches accepted by Pyrex's maintainer Greg Ewing, who envisioned a much smaller scope for his tool than the Sage developers had in mind. They then forked Pyrex as SageX. When they found people were downloading Sage just to get SageX, and developers of other packages (including Stefan Behnel, who maintains the XML library LXML) were also maintaining forks of Pyrex, SageX was split off the Sage project and merged with cython-lxml to become Cython.

Cython files have a .pyx extension. At its most basic, Cython code looks exactly like Python code. However, whereas standard Python is dynamically typed, in Cython, types can optionally be provided, allowing for improved performance, allowing loops to be converted into C loops where possible. For example:

# The argument will be converted to int or raise a TypeError.
def primes(int kmax): 

    # These variables are declared with C types.
    cdef int n, k, i 

    # Another C type 
    cdef int p[1000]
 
    # A Python type
    result = [] 

    if kmax > 1000:
        kmax = 1000

    k = 0
    n = 2

    while k < kmax:
        i = 0

        while i < k and n % p[i] != 0:
            i = i + 1

        if i == k:
            p[k] = n
            k = k + 1
            result.append(n)

        n = n + 1

    return result

Example

Hello World in Cython

A sample hello world program for Cython is more complex than in most languages because it interfaces with the Python C API and setuptools or other PEP517-compliant extension building facilities. At least three files are required for a basic project:

• A setup.py file to invoke the setuptools build process that generates the extension module
• A main python program to load the extension module
• Cython source file(s)

The following code listings demonstrate the build and launch process:

# hello.pyx - Python module, this code will be translated to C by Cython.
def say_hello():
    print("Hello World!")

# launch.py - Python stub loader, loads the module that was made by Cython.

# This code is always interpreted, like normal Python.
# It is not compiled to C.

import hello
hello.say_hello()

# setup.py - unnecessary if not redistributing the code, see below
from setuptools import setup
from Cython.Build import cythonize

setup(name = "Hello world app",
      ext_modules = cythonize("*.pyx"))

These commands build and launch the program:

$ python setup.py build_ext --inplace
$ python launch.py

Using in IPython/Jupyter notebook

A more straightforward way to start with Cython is through command-line IPython (or through in-browser python console called Jupyter notebook):

In [1]: %load_ext Cython

In [2]: %%cython
   ...: def f(n):
   ...:     a = 0
   ...:     for i in range(n):
   ...:         a += i
   ...:     return a
   ...: 
   ...: cpdef g(int n):
   ...:     cdef long a = 0
   ...:     cdef int i
   ...:     for i in range(n):
   ...:         a += i
   ...:     return a
   ...: 

In [3]: %timeit f(1000000)
10 loops, best of 3: 26.5 ms per loop

In [4]: %timeit g(1000000)
1000 loops, best of 3: 279 µs per loop

which gives a 95 times improvement over the pure-python version. More details on the subject in the official quickstart page.

class Bugatti:

   def __init__(self, model, year):
       # Initialize the Bugatti with make, model, year, speed, and fuel level
       self.make = "Bugatti"
       self.model = model
       self.year = year
       self.speed = 0  # Speed starts at 0
       self.fuel = 100  # Fuel starts full at 100%
   
   def accelerate(self, amount=20):
       # Method to increase speed and reduce fuel
       if self.fuel > 0:
           self.speed += amount
           self.fuel -= amount * 0.1  # Fuel decreases as the car accelerates
           self.fuel = max(self.fuel, 0)  # Ensure fuel doesn’t go below 0
           print(f"The Bugatti accelerates by {amount} km/h. Current speed: {self.speed} km/h, Fuel: {self.fuel:.1f}%")
       else:
           print("The Bugatti is out of fuel and cannot accelerate.")
   
   def brake(self, amount=20):
       # Method to decrease speed
       if self.speed - amount < 0:
           self.speed = 0
       else:
           self.speed -= amount
       print(f"The Bugatti slows down by {amount} km/h. Current speed: {self.speed} km/h")
   
   def stop(self):
       # Method to stop the car
       self.speed = 0
       print("The Bugatti has stopped.")
   
   def refuel(self):
       # Refuel the Bugatti to 100%
       self.fuel = 100
       print("The Bugatti has been refueled to 100%.")
   
   def display_info(self):
       # Display the car's details
       print(f"Car Info: {self.year} {self.make} {self.model}, Current Speed: {self.speed} km/h, Fuel: {self.fuel:.1f}%")
   
   # Create an instance of the Bugatti
   my_bugatti = Bugatti("Chiron", 2023)
   
   # Use the Bugatti's methods
   my_bugatti.display_info()   # Show Bugatti details
   my_bugatti.accelerate()     # Accelerate the Bugatti
   my_bugatti.accelerate(50)   # Accelerate by a custom amount
   my_bugatti.brake(30)        # Slow down the car
   my_bugatti.stop()           # Stop the car
   my_bugatti.refuel()         # Refuel the car
   my_bugatti.display_info()   # Show final Bugatti details

See also

• PyPy
• Numba

External links

• Official website
• Cython on GitHub