Implementation File

Definition File

Include File

The cdef Statement

The cdef statement is used to make C level declarations for:

cdef int i, j, k
cdef float f, g[42], *h

cdef struct Grail:
    int age
    float volume

cdef union Food:
    char *spam
    float *eggs

cdef enum CheeseType:
    cheddar, edam,
    camembert

cdef enum CheeseState:
    hard = 1
    soft = 2
    runny = 3

cdef int eggs(unsigned long l, float f):
    ...

cdef class Spam:
    ...

cdef enum:
    tons_of_spam = 3

Grouping cdef Declarations

A series of declarations can grouped into a cdef block:

cdef:
    struct Spam:
        int tons

    int i
    float f
    Spam *p

    void f(Spam *s):
    print s.tons, "Tons of spam"

ctypedef unsigned long ULong

ctypedef int *IntPtr

Parameters

• Both C and Python function types can be declared to have parameters C data types.

• Use normal C declaration syntax:

  def spam(int i, char *s):
      ...
  
      cdef int eggs(unsigned long l, float f):
          ...
  

• As these parameters are passed into a Python declared function, they are magically converted to the specified C type value.

• This holds true for only numeric and string types

• If no type is specified for a parameter or a return value, it is assumed to be a Python object

• The following takes two Python objects as parameters and returns a Python object:

  cdef spamobjs(x, y):
      ...
  

Note

–

This is different then C language behavior, where it is an int by default.

• Python object types have reference counting performed according to the standard Python C-API rules:

• Borrowed references are taken as parameters
• New references are returned

• The name object can be used to explicitly declare something as a Python Object.

• For sake of code clarity, it recommended to always use object explicitly in your code.

• This is also useful for cases where the name being declared would otherwise be taken for a type:

  cdef foo(object int):
      ...
  

• As a return type:

  cdef object foo(object int):
      ...
  

Keyword-only Arguments

• As in Python 3, def functions can have keyword-only argurments listed after a "*" parameter and before a "**" parameter if any:

  def f(a, b, *args, c, d = 42, e, **kwds):
      ...
  

• Shown above, the c, d and e arguments can not be passed as positional arguments and must be passed as keyword arguments.
• Furthermore, c and e are required keyword arguments since they do not have a default value.

• If the parameter name after the "*" is omitted, the function will not accept any extra positional arguments:

  def g(a, b, *, c, d):
      ...
  

• Shown above, the signature takes exactly two positional parameters and has two required keyword parameters

Automatic Type Conversion

• For basic numeric and string types, in most situations, when a Python object is used in the context of a C value and vice versa.

• The following table summarizes the conversion possibilities, assuming sizeof(int) == sizeof(long):

  C types	From Python types	To Python types
  [unsigned] char	int, long	int
  [unsigned] short
  int, long
  unsigned int	int, long	long
  unsigned long
  [unsigned] long long
  float, double, long double	int, long, float	float
  char *	str/bytes	str/bytes [1]
  struct		dict

Type Casting

• The syntax used in type casting are "<" and ">"

Note

The syntax is different from C convention

cdef char *p, float *q
p = <char*>q

• If one of the types is a python object for <type>x, Cython will try and do a coercion.

Note

Cython will not stop a casting where there is no conversion, but it will emit a warning.

• If the address is what is wanted, cast to a void* first.

Python Objects

Differences Between Cython and C

• Most notable are C constructs which have no direct equivalent in Python.

• An integer literal is treated as a C constant

• It will be truncated to whatever size your C compiler thinks appropriate.

• Cast to a Python object like this:

  <object>10000000000000000000
  

• The "L", "LL" and the "U" suffixes have the same meaning as in C

• There is no -> operator in Cython.. instead of p->x, use p.x.
• There is no * operator in Cython.. instead of *p, use p[0].
• & is permissible and has the same semantics as in C.
• NULL is the null C pointer.

• Do NOT use 0.
• NULL is a reserved word in Cython

• Syntax for Type casts are <type>value.

Scope Rules

• All determination of scoping (local, module, built-in) in Cython is determined statically.
• As with Python, a variable assignment which is not declared explicitly is implicitly declared to be a Python variable residing in the scope where it was assigned.

Built-in Constants

Predefined Python built-in constants:

• None
• True
• False

Operator Precedence

• Cython uses Python precedence order, not C

For-loops

• range() is C optimized when the index value has been declared by cdef:

  cdef i
  for i in range(n):
      ...
  

• Iteration over C arrays is also permitted, e.g.:

  cdef double x
  cdef double* data
  for x in data[:10]:
      ...
  

• Iterating over many builtin types such as lists and tuples is optimized.

• There is also a more C-style for-from syntax

• The target expression must be a variable name.

• The name between the lower and upper bounds must be the same as the target name.

  for i from 0 <= i < n:

  ...

• Or when using a step size:

  for i from 0 <= i < n by s:
      ...
  

• To reverse the direction, reverse the conditional operation:

  for i from n > i >= 0:
      ...
  

• The break and continue are permissible.
• Can contain an else clause.

Callable from Python

• Are declared with the def statement
• Are called with Python objects
• Return Python objects
• See Parameters for special consideration

Callable from C

• Are declared with the cdef statement.
• Are called with either Python objects or C values.
• Can return either Python objects or C values.

Callable from both Python and C

• Are declared with the cpdef statement.
• Can be called from anywhere, because it uses a little Cython magic.
• Uses the faster C calling conventions when being called from other Cython code.

Overriding

cpdef functions can override cdef functions:

cdef class A:
    cdef foo(self):
        print "A"
cdef class B(A)
    cdef foo(self, x=None)
        print "B", x
cdef class C(B):
    cpdef foo(self, x=True, int k=3)
        print "C", x, k

Function Pointers

• Functions declared in a struct are automatically converted to function pointers.
• see using exceptions with function pointers

Python Built-ins

Cython compiles calls to most built-in functions into direct calls to the corresponding Python/C API routines, making them particularly fast.

Only direct function calls using these names are optimised. If you do something else with one of these names that assumes it’s a Python object, such as assign it to a Python variable, and later call it, the call will be made as a Python function call.

Note 1: Pyrex originally provided a function getattr3(obj, name, default)() corresponding to the three-argument form of the Python builtin getattr(). Cython still supports this function, but the usage is deprecated in favour of the normal builtin, which Cython can optimise in both forms.

Checking return values for non-Cython functions..

• Do not try to raise exceptions by returning the specified value.. Example:

  cdef extern FILE *fopen(char *filename, char *mode) except NULL # WRONG!
  

• The except clause does not work that way.
• It’s only purpose is to propagate Python exceptions that have already been raised by either...

• A Cython function
• A C function that calls Python/C API routines.

• To propagate an exception for these circumstances you need to raise it yourself:

  cdef FILE *p
  p = fopen("spam.txt", "r")
  if p == NULL:
      raise SpamError("Couldn't open the spam file")
  

Compile-Time Definitions

• Defined using the DEF statement:

  DEF FavouriteFood = "spam"
  DEF ArraySize = 42
  DEF OtherArraySize = 2 * ArraySize + 17
  

• The right hand side must be a valid compile-time expression made up of either:

• Literal values
• Names defined by other DEF statements

• They can be combined using any of the Python expression syntax
• Cython provides the following predefined names

• Corresponding to the values returned by os.uname()

• UNAME_SYSNAME
• UNAME_NODENAME
• UNAME_RELEASE
• UNAME_VERSION
• UNAME_MACHINE

• A name defined by DEF can appear anywhere an identifier can appear.
• Cython replaces the name with the literal value before compilation.

• The compile-time expression, in this case, must evaluate to a Python value of int, long, float, or str:

  cdef int a1[ArraySize]
  cdef int a2[OtherArraySize]
  print "I like", FavouriteFood
  

Conditional Statements

• Similar semantics of the C pre-processor
• The following statements can be used to conditionally include or exclude sections of code to compile.

• IF
• ELIF
• ELSE

IF UNAME_SYSNAME == "Windows":
    include "icky_definitions.pxi"
ELIF UNAME_SYSNAME == "Darwin":
    include "nice_definitions.pxi"
ELIF UNAME_SYSNAME == "Linux":
    include "penguin_definitions.pxi"
ELSE:
    include "other_definitions.pxi"

• ELIF and ELSE are optional.
• IF can appear anywhere that a normal statement or declaration can appear
• It can contain any statements or declarations that would be valid in that context.

• This includes other IF and DEF statements