example-cython.rst

Cython

Getting Started

This document provides examples of using Cython-generated code in ray. To get started, run the following from directory $RAY_HOME/examples/cython:

pip install scipy # For BLAS example
python setup.py develop
python cython_main.py --help

You can import the cython_examples module from a Python script or interpreter.

Notes

• You must include the following two lines at the top of any *.pyx file:

#!python
# cython: embedsignature=True, binding=True

• You cannot decorate Cython functions within a *.pyx file (there are ways around this, but creates a leaky abstraction between Cython and Python that would be very challenging to support generally). Instead, prefer the following in your Python code:

some_cython_func = ray.remote(some_cython_module.some_cython_func)

• You cannot transfer memory buffers to a remote function (see example8, which currently fails); your remote function must return a value
• Have a look at cython_main.py, cython_simple.pyx, and setup.py for examples of how to call, define, and build Cython code, respectively. The Cython documentation is also very helpful.
• Several limitations come from Cython's own unsupported Python features.
• We currently do not support compiling and distributing Cython code to ray clusters. In other words, Cython developers are responsible for compiling and distributing any Cython code to their cluster (much as would be the case for users who need Python packages like scipy).
• For most simple use cases, developers need not worry about Python 2 or 3, but users who do need to care can have a look at the language_level Cython compiler directive (see here).