“Compiled” switch¶

• compiled is a special variable which is set toTrue when the compilerruns, andFalse in the interpreter. Thus, the code

  importcythonifcython.compiled:print("Yep, I'm compiled.")else:print("Just a lowly interpreted script.")

  will behave differently depending on whether or not the code is executed as acompiled extension (.so/.pyd) module or a plain.pyfile.

Static typing¶

• cython.declare declares a typed variable in the current scope, which can beused in place of thecdeftypevar[=value] construct. This has two forms,the first as an assignment (useful as it creates a declaration in interpretedmode as well):

  importcythonx=cython.declare(cython.int)# cdef int xy=cython.declare(cython.double,0.57721)# cdef double y = 0.57721

  and the second mode as a simple function call:

  importcythoncython.declare(x=cython.int,y=cython.double)# cdef int x; cdef double y

  It can also be used to define extension type private, readonly and public attributes:

  importcython@cython.cclassclassA:cython.declare(a=cython.int,b=cython.int)c=cython.declare(cython.int,visibility='public')d=cython.declare(cython.int)# private by default.e=cython.declare(cython.int,visibility='readonly')def__init__(self,a,b,c,d=5,e=3):self.a=aself.b=bself.c=cself.d=dself.e=e

• @cython.locals is a decorator that is used to specify the types of localvariables in the function body (including the arguments):

  importcython@cython.locals(a=cython.long,b=cython.long,n=cython.longlong)deffoo(a,b,x,y):n=a*b# ...

• @cython.returns(<type>) specifies the function’s return type.

• @cython.exceptval(value=None,*,check=False) specifies the function’s exceptionreturn value and exception check semantics as follows:

  @exceptval(-1)# cdef int func() except -1:@exceptval(-1,check=False)# cdef int func() except -1:@exceptval(check=True)# cdef int func() except *:@exceptval(-1,check=True)# cdef int func() except? -1:@exceptval(check=False)# no exception checking/propagation

  If exception propagation is disabled, any Python exceptions that are raisedinside of the function will be printed and ignored.

C types¶

There are numerous types built into the Cython module. It provides all thestandard C types, namelychar,short,int,long,longlongas well as their unsigned versionsuchar,ushort,uint,ulong,ulonglong. The specialbint type is used for C boolean values andPy_ssize_t for (signed) sizes of Python containers.

For each type, there are pointer typesp_int,pp_int, etc., up tothree levels deep in interpreted mode, and infinitely deep in compiled mode.Further pointer types can be constructed withcython.pointer[cython.int](orcython.pointer(cython.int) for compatibility with Cython versions before 3.1),and arrays ascython.int[10]. A limited attempt is made to emulate thesemore complex types, but only so much can be done from the Python language.

The Python types int, long and bool are interpreted as Cint,longandbint respectively. Also, the Python builtin typeslist,dict,tuple, etc. may be used, as well as any user defined types.

Typed C-tuples can be declared as a tuple of C types.

Extension types and cdef functions¶

• The class decorator@cython.cclass creates acdefclass.

• The function/method decorator@cython.cfunc creates acdef function.

• @cython.ccall creates acpdef function, i.e. one that Cython codecan call at the C level.

• @cython.locals declares local variables (see above). It can also be used todeclare types for arguments, i.e. the local variables that are used in thesignature.

• @cython.inline is the equivalent of the Cinline modifier.

• @cython.final terminates the inheritance chain by preventing a type frombeing used as a base class, or a method from being overridden in subtypes.This enables certain optimisations such as inlined method calls.

Here is an example of acdef function:

@cython.cfunc@cython.returns(cython.bint)@cython.locals(a=cython.int,b=cython.int)defc_compare(a,b):returna==b

Managing the Global Interpreter Lock¶

• cython.nogil can be used as a context manager or as a decorator to replace thenogil keyword:

  withcython.nogil:# code block with the GIL released@cython.nogil@cython.cfuncdeffunc_released_gil()->cython.int:# function that can be run with the GIL released

  Note that the two uses differ: the context manager releases the GIL while the decorator marks that afunctioncan be run without the GIL. SeeCython and the GIL for more details.

• cython.gil can be used as a context manager to replace thegil keyword:

  withcython.gil:# code block with the GIL acquired

  Note

  Cython currently does not support the@cython.with_gil decorator.

Both directives accept an optional boolean parameter for conditionallyreleasing or acquiring the GIL. The condition must be constant (at compile time):

withcython.nogil(False):# code block with the GIL not released@cython.nogil(True)@cython.cfuncdeffunc_released_gil()->cython.int:# function with the GIL releasedwithcython.gil(False):# code block with the GIL not acquiredwithcython.gil(True):# code block with the GIL acquired

A common use case for conditionally acquiring and releasing the GIL are fused typesthat allow different GIL handling depending on the specific type (seeConditional Acquiring / Releasing the GIL).

cimports¶

The specialcython.cimports package name gives access to cimportsin code that uses Python syntax. Note that this does not mean that Clibraries become available to Python code. It only means that you cantell Cython what cimports you want to use, without requiring specialsyntax. Running such code in plain Python will fail.

fromcython.cimports.libcimportmathdefuse_libc_math():returnmath.ceil(5.5)

Since such code must necessarily refer to the non-existingcython.cimports ‘package’, the plain cimport formcimportcython.cimports... is not available.You must use the formfromcython.cimports....

Further Cython functions and declarations¶

• address is used in place of the& operator:

  cython.declare(x=cython.int,x_ptr=cython.p_int)x_ptr=cython.address(x)

• sizeof emulates thesizeof operator. It can take both types andexpressions.

  cython.declare(n=cython.longlong)print(cython.sizeof(cython.longlong))print(cython.sizeof(n))

• typeof returns a string representation of the argument’s type for debugging purposes. It can take expressions.

  cython.declare(n=cython.longlong)print(cython.typeof(n))

• struct can be used to create struct types.:

  MyStruct=cython.struct(x=cython.int,y=cython.int,data=cython.double)a=cython.declare(MyStruct)

  is equivalent to the code:

  cdefstructMyStruct:intxintydoubledatacdefMyStructa

• union creates union types with exactly the same syntax asstruct.

• typedef defines a type under a given name:

  T=cython.typedef(cython.p_int)# ctypedef int* T

• cast will (unsafely) reinterpret an expression type.cython.cast(T,t)is equivalent to<T>t. The first attribute must be a type, the second isthe expression to cast. Specifying the optional keyword argumenttypecheck=True has the semantics of<T?>t.

  t1=cython.cast(T,t)t2=cython.cast(T,t,typecheck=True)

• fused_type creates a new type definition that refers to the multiple types.The following example declares a new type calledmy_fused_type which canbe either anint or adouble.:

  my_fused_type=cython.fused_type(cython.int,cython.float)

Magic Attributes within the .pxd¶

The specialcython module can also be imported and used within the augmenting.pxd file. For example, the following Python filedostuff.py:

defdostuff(n):t=0foriinrange(n):t+=ireturnt

can be augmented with the following.pxd filedostuff.pxd:

importcython@cython.locals(t=cython.int,i=cython.int)cpdefintdostuff(intn)

Thecython.declare() function can be used to specify types for globalvariables in the augmenting.pxd file.

Disabling annotations¶

To avoid conflicts with other kinds of annotationusages, Cython’s use of annotations to specify types can be disabled with theannotation_typingcompiler directive. From Cython 3you can use this as a decorator or a with statement, as shown in the following example:

importcython@cython.annotation_typing(False)deffunction_without_typing(a:int,b:int)->int:"""Cython is ignoring annotations in this function"""c:int=a+breturnc*a@cython.annotation_typing(False)@cython.cclassclassNotAnnotatedClass:"""Cython is ignoring annotatons in this class except annotated_method"""d:dictdef__init__(self,dictionary:dict):self.d=dictionary@cython.annotation_typing(True)defannotated_method(self,key:str,a:cython.int,b:cython.int):prefixed_key:str='prefix_'+keyself.d[prefixed_key]=a+bdefannotated_function(a:cython.int,b:cython.int):s:cython.int=a+bwithcython.annotation_typing(False):# Cython is ignoring annotations within this code blockc:list=[]c.append(a)c.append(b)c.append(s)returnc

typing Module¶

Support for the full range of annotations described by PEP-484 is not yetcomplete. Cython 3 currently understands the following features from thetyping module:

• Optional[tp], which is interpreted astporNone;

• Union[tp,None] orUnion[None,tp], which is interpreted astporNone;

• typed containers such asList[str], which is interpreted aslist. Thehint that the elements are of typestr is currently ignored;

• Tuple[...], which is converted into a Cython C-tuple where possibleand a regular Pythontuple otherwise.

• ClassVar[...], which is understood in the context ofcdefclass or@cython.cclass.

Some of the unsupported features are likely to remainunsupported since these type hints are not relevant for the compilation toefficient C code. In other cases, however, where the generated C code couldbenefit from these type hints but does not currently, help is welcome toimprove the type analysis in Cython.

Reference table¶

The following reference table documents how type annotations are currently interpreted.Cython 0.29 behaviour is only shown where it differs from Cython 3.0 behaviour.The current limitations will likely be lifted at some point.

Avoiding thecython runtime dependency¶

Python modules that are intended to run both compiled and as plain Pythonusually have the lineìmportcython in them and make use of the magicattributes in that module. If not compiled, this creates a runtime dependencyon Cython’s shadow module that provides fake implementations of types anddecorators.

Code that does not want to require Cython or its shadow module as as runtimedependency at all can often get away with a simple, stripped-down replacementlike the following:

try:importcythonexceptImportError:class_fake_cython:compiled=Falsedefcfunc(self,func):returnfuncdefccall(self,func):returnfuncdef__getattr__(self,type_name):return"object"cython=_fake_cython()

Calling C functions¶

The magiccython.cimports package provides a way to cimport externalcompile time C declarations from code written in plain Python. For convenience,it also provides a fallback Python implementation for thelibc.math module.

However, it is normally not possible tocall C functions in pure Pythoncode as there is no general way to represent them in normal (uncompiled) Python.But in cases where an equivalent Python function exists, this can be achievedby combining C function coercion with a conditional import as follows:

# mymodule.pxd# declare a C function as "cpdef" to export it to the modulecdefexternfrom"math.h":cpdefdoublesin(doublex)

# mymodule.pyimportcython# override with Python import if not in compiled codeifnotcython.compiled:frommathimportsin# calls sin() from math.h when compiled with Cython and math.sin() in Pythonprint(sin(0))

Note that the “sin” function will show up in the module namespace of “mymodule”here (i.e. there will be amymodule.sin() function). You can mark it as aninternal name according to Python conventions by renaming it to “_sin” in the.pxd file as follows:

cdefexternfrom"math.h":cpdefdouble_sin"sin"(doublex)

You would then also change the Python import tofrommathimportsinas_sinto make the names match again.

Using C arrays for fixed size lists¶

C arrays can automatically coerce to Python lists or tuples.This can be exploited to replace fixed size Python lists in Python code by Carrays when compiled. An example:

importcython@cython.locals(counts=cython.int[10],digit=cython.int)defcount_digits(digits):"""    >>> digits = '01112222333334445667788899'    >>> count_digits(map(int, digits))    [1, 3, 4, 5, 3, 1, 2, 2, 3, 2]    """counts=[0]*10fordigitindigits:assert0<=digit<=9counts[digit]+=1returncounts

In normal Python, this will use a Python list to collect the counts, whereasCython will generate C code that uses a C array of C ints.