enhancements compilerdirectives

## page was renamed from docs/compilerdirectives

Compiler directives

For up to date information, please see the relevant section in the cython documentation.

Compiler directives are instructions which affect which kind of code Cython generates.

Available directives

Directive	Values	Default	Notes
boundscheck	True/False	True	If set to False, Cython is free to assume that indexing operations ([]-operator) in the code will not cause any IndexErrors to be raised. Lists, tuples, and stings are affected only if the index can be determined to be non-negative (or if wraparound is False). Conditions which would normally trigger an IndexError may instead cause segfaults or data corruption if this is set to False.
wraparound	True/False	True	In Python arrays can be indexed relative to the end. For example A[-1] indexes the last value of a list. In C negative indexing is not supported. If set to False, Cython will not ensure that python indexing is not used.
nonecheck	True/False	False	If set to False, Cython is free to assume that native field accesses on variables typed as an extension type, or buffer accesses on a buffer variable, never occurs when the variable is set to None. Otherwise a check is inserted and the appropriate exception is raised. This is off by default for performance reasons.
embedsignature	True/False	False	If set to True, Cython will embed a textual copy of the call signature in the docstring of all Python visible functions and classes. Tools like IPython and epydoc can thus display the signature, which cannot otherwise be retrieved after compilation.
cdivision	True/False	Version < 0.12	If set to False, Cython will adjust the remainder and quotient operators C types to match those of Python ints (which differ when the operands have opposite signs) and raise a ZeroDivisionError when the right operand is 0. This has about a 35% speed penalty. If set to True, no checks are performed. See CEP 516
cdivision_warnings	True/False	False	If set to True, Cython will emit a runtime warning whenever division is performed with negative operands. See CEP 516
always_allow_keywords	True/False	False	Avoid the METH_NOARGS and METH_O when constructing functions/methods which take zero or one arguments. Has no effect on special methods and functions with more than one argument. The METH_NOARGS and METH_O signatures provide faster calling conventions but disallow the use of keywords.
profile	True/False	False	Add hooks for Python profilers into the compiled C code.
infer_types	True/False	False	Infer types of untyped variables in function bodies. (Cython 0.12+)

How to set directives

Globally

One can set compiler directives through a special header comment at the top of the file, like this:

#!python
#cython: boundscheck=False

The comment must appear before any code (but can appear after other comments or whitespace).

One can also pass a directive on the command line by using the -X switch:

$ cython -X boundscheck=True ...

Directives passed on the command line will override directives set in header comments.

Locally

For local blocks, you need to cimport the special builtin cython module:

#!python
cimport cython

Then you can use the directives either as decorators or in a with statement, like this:

#!python
@cython.boundscheck(False) # turn off boundscheck for this function
def f():
    ...
    with cython.boundscheck(True): # turn it temporarily on again for this block
        ...

Note: These two methods of setting directives are not affected by overriding the directive on the command-line using the -X option.

In setup.py

For setup.py scripts, you can set cython_directives on extension modules with a dictionary of directives:

#!python

ext_modules = [Extension("spam", ["spam.pyx"]),
               Extension("ham", ["ham.pyx"])]
for e in ext modules:
    e.cython_directives = {"boundscheck": False}