# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'
+# Include the Cython logo in the sidebar
+html_logo = '_static/cythonlogo.png'
+
+# used a favicon!
+html_favicon = '_static/favicon.ico'
+
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
.. highlight:: cython
-.. _early-binding-speed-label:
+.. _early-binding-for-speed:
+**************************
Early Binding for Speed
-=======================
+**************************
As a dynamic language, Python encourages a programming style of considering
classes and objects in terms of their methods and attributes, more than where
rect = Rectangle(x0, y0, x1, y1)
return rect.area()
-.. Note::
+.. note::
in earlier versions of Cython, the :keyword:`cpdef` keyword is
:keyword:`rdef` - but has the same effect).
.. highlight:: cython
+.. _extension-types:
+
+******************
Extension Types
-===============
+******************
Introduction
--------------
+==============
As well as creating normal user-defined classes with the Python class
statement, Cython also lets you create new built-in Python types, known as
interface to them.
Attributes
------------
+============
Attributes of an extension type are stored directly in the object's C struct.
The set of attributes is fixed at compile time; you can't add attributes to an
are always readable and writable by direct access.
Type declarations
------------------
+===================
Before you can directly access the attributes of an extension type, the Cython
compiler must know that you have an instance of that type, and not just a
return sh2
Extension types and None
-------------------------
+=========================
When you declare a parameter or C variable as being of an extension type,
Cython will allow it to take on the value ``None`` as well as values of its
will invoke Python operations and therefore be much slower.
Special methods
----------------
+================
Although the principles are similar, there are substantial differences between
many of the :meth:`__xxx__` special methods of extension types and their Python
extension types.
Properties
-----------
+============
There is a special syntax for defining properties in an extension class::
We don't have: []
Subclassing
------------
+=============
An extension type may inherit from a built-in type or another extension type::
Parrot.describe(self)
Forward-declaring extension types
----------------------------------
+===================================
Extension types can be forward-declared, like :keyword:`struct` and
:keyword:`union` types. This will be necessary if you have two extension types
# attributes and methods
Making extension types weak-referenceable
------------------------------------------
+==========================================
By default, extension types do not support having weak references made to
them. You can enable weak referencing by declaring a C attribute of type
cdef object __weakref__
Public and external extension types
------------------------------------
+====================================
Extension types can be declared extern or public. An extern extension type
declaration makes an extension type defined in external C code available to a
In Pyrex versions before 0.8, extern extension types were also used to
reference extension types defined in another Pyrex module. While you can still
do that, Cython provides a better mechanism for this. See
- :ref:`sharing-declarations-label`.
+ :ref:`sharing-declarations`.
Here is an example which will let you get at the C-level members of the
built-in complex object.::
.. highlight:: cython
+.. external-C-code:
+
+**********************************
Interfacing with External C Code
-================================
+**********************************
One of the main uses of Cython is wrapping existing libraries of C code. This
is achieved by using external declarations to declare the C functions and
can also be used to allow C code to call Python code.
External declarations
----------------------
+=======================
By default, C functions and variables declared at the module level are local
to the module (i.e. they have the C static storage class). They can also be
cdef extern void order_spam(int tons)
Referencing C header files
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
When you use an extern definition on its own as in the examples above, Cython
includes a declaration for it in the generated C file. This can cause problems
...
Styles of struct, union and enum declaration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------------
There are two main ways that structs, unions and enums can be declared in C
header files: using a tag name, or using a typedef. There are also some
as :ctype:`Foo`, not ``struct Foo``.
Accessing Python/C API routines
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
One particular use of the ``cdef extern from`` statement is for gaining access to
routines in the Python/C API. For example,::
will allow you to create Python strings containing null bytes.
Special Types
-^^^^^^^^^^^^^
+--------------
Cython predefines the name ``Py_ssize_t`` for use with Python/C API routines. To
make your extensions compatible with 64-bit systems, you should always use
this type where it is specified in the documentation of Python/C API routines.
Windows Calling Conventions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
The ``__stdcall`` and ``__cdecl`` calling convention specifiers can be used in
Cython, with the same syntax as used by C compilers on Windows, for example,::
other ``__stdcall`` functions of the same signature.
Resolving naming conflicts - C name specifications
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------------------
Each Cython module has a single module-level namespace for both Python and C
names. This can be inconvenient if you want to wrap some external C functions
second "beta" = 3
Using Cython Declarations from C
---------------------------------
+==================================
Cython provides two methods for making C declarations from a Cython module
available for use by external C code – public declarations and C API
:keyword:`cimport` statement for that. Sharing Declarations Between Cython Modules.
Public Declarations
-^^^^^^^^^^^^^^^^^^^
+---------------------
You can make C types, variables and functions defined in a Cython module
accessible to C code that is linked with the module, by declaring them with
:mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
C API Declarations
-^^^^^^^^^^^^^^^^^^
+-------------------
The other way of making declarations available to C code is to declare them
with the :keyword:`api` keyword. You can use this keyword with C functions and
:file:`foo.spam_api.h` and an importing function called
:func:`import_foo__spam`.
-Multiple public and api declarations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Multiple public and API declarations
+--------------------------------------
You can declare a whole group of items as :keyword:`public` and/or
:keyword:`api` all at once by enclosing them in a :keyword:`cdef` block, for
char *get_lunch(float tomato_size)
This can be a useful thing to do in a ``.pxd`` file (see
-:ref:`sharing-declarations-label`) to make the module's public interface
+:ref:`sharing-declarations`) to make the module's public interface
available by all three methods.
Acquiring and Releasing the GIL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
Cython provides facilities for releasing the Global Interpreter Lock (GIL)
before calling C code, and for acquiring the GIL in functions that are to be
...
Declaring a function as callable without the GIL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------------------
You can specify :keyword:`nogil` in a C function header or function type to
declare that it is safe to call without the GIL.::
.. highlight:: cython
-.. _language-basics-label:
+.. _language-basics:
+*****************
Language Basics
-===============
+*****************
Python functions vs. C functions
---------------------------------
+==================================
There are two kinds of function definition in Cython:
ctypedef int *IntPtr
Grouping multiple C declarations
-================================
+==================================
If you have a series of declarations that all begin with :keyword:`cdef`, you
can group them into a :keyword:`cdef` block like this::
----------------------
.. warning::
- This feature is deprecated. Use :ref:`sharing-declarations-label` instead.
+ This feature is deprecated. Use :ref:`sharing-declarations` instead.
A Cython source file can include material from other files using the include
statement, for example::
There are other mechanisms available for splitting Cython code into
separate parts that may be more appropriate in many cases. See
- :ref:`sharing-declarations-label`.
+ :ref:`sharing-declarations`.
Keyword-only arguments
----------------------
.. highlight:: cython
-.. _cython-limitations-label:
+.. _cython-limitations:
*************
Limitations
.. highlight:: cython
-.. _numpy_tute-label:
+.. _numpy_tutorial:
**************************
Cython for NumPy users
Cython at a glance
====================
+
Cython is a compiler which compiles Python-like code files to C code. Still,
''Cython is not a Python to C translator''. That is, it doesn't take your full
program and "turns it into C" -- rather, the result makes full use of the
Your Cython environment
========================
+
Using Cython consists of these steps:
1. Write a :file:`.pyx` source file
.. highlight:: cython
-.. _overview-label:
+.. _overview:
********
Overview
Future Plans
============
Cython is not finished. Substantial tasks remaining. See
-:ref:`cython-limitations-label` for a current list.
+:ref:`cython-limitations` for a current list.
.. rubric:: Footnotes
-.. [#] For differences with Pyrex see :ref:`pyrex-differences-label`.
+.. [#] For differences with Pyrex see :ref:`pyrex-differences`.
.. highlight:: cython
-.. _pyrex-differences-label:
+.. _pyrex-differences:
+**************************************
Differences between Cython and Pyrex
-====================================
+**************************************
Package names and cross-directory imports
------------------------------------------
+==========================================
Just like in python.
List Comprehensions
--------------------
+====================
`[expr(x) for x in A]` is now available, implementing the full specification
at http://www.python.org/dev/peps/pep-0202/ . Looping is optimized if ``A`` is
[i*i for i from 0 <= i < 10]
Conditional expressions "x if b else y" (python 2.5)
-----------------------------------------------------
+=====================================================
Conditional expressions as described in
http://www.python.org/dev/peps/pep-0308/::
Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C).
cdef inline
------------
+=============
Module level functions can now be declared inline, with the :keyword:`inline`
keyword passed on to the C compiler. These can be as fast as macros.::
cases.
Assignment on declaration (e.g. "cdef int spam = 5")
-----------------------------------------------------
+======================================================
In Pyrex, one must write::
'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2")
-----------------------------------------------------------------
+==================================================================
::
Boolean int type (e.g. it acts like a c int, but coerces to/from python as a boolean)
--------------------------------------------------------------------------------------
+======================================================================================
In C, ints are used for truth values. In python, any object can be used as a
truth value (using the :meth:`__nonzero__` method, but the canonical choices
``True`` or ``False`` then no method call is made.)
Executable class bodies
------------------------
+=========================
Including a working :func:`classmethod`::
print "hi", a
cpdef functions
----------------
+=================
Cython adds a third function type on top of the usual :keyword:`def` and
:keyword:`cdef`. If a function is declared :keyword:`cpdef` it can be called
x.foo() # will check to see if overridden
A.foo(x) # will call A's implementation whether overridden or not
-See :ref:`early-binding-speed-label` for explanation and usage tips.
+See :ref:`early-binding-for-speed` for explanation and usage tips.
.. _automatic-range-conversion:
Automatic range conversion
--------------------------------------
+============================
This will convert statements of the form ``for i in range(...)`` to ``for i
from ...`` when ``i`` is any cdef'd integer type, and the direction (i.e. sign
way to set this).
More friendly type casting
---------------------------
+===========================
In Pyrex, if one types ``<int>x`` where ``x`` is a Python object, one will get
the memory address of ``x``. Likewise, if one types ``<object>i`` where ``i``
:ctype:`MyExtensionType`.
Optional arguments in cdef/cpdef functions
-------------------------------------------
+============================================
Cython now supports optional arguments for :keyword:`cdef` and
:keyword:`cpdef` functions.
:keyword:`cdef` functions.
Function pointers in structs
-----------------------------
+=============================
Functions declared in :keyword:`structs` are automatically converted to
function pointers for convenience.
C++ Exception handling
-----------------------
+=========================
:keyword:`cdef` functions can now be declared as::
cdef int foo(...) except +python_error_raising_function
in which case a Python exception will be raised when a C++ error is caught.
-See :ref:`wrapping-cplusplus-label` for more details.
+See :ref:`wrapping-cplusplus` for more details.
Synonyms
---------
+=========
``cdef import from`` means the same thing as ``cdef extern from``
Source code encoding
---------------------
+======================
.. TODO: add the links to the relevent PEPs
.. highlight:: cython
-.. _sharing-declarations-label:
+.. _sharing-declarations:
+********************************************
Sharing Declarations Between Cython Modules
-===========================================
+********************************************
This section describes a new set of facilities for making C declarations,
functions and extension types in one Cython module available for use in
import mechanism, and can be thought of as a compile-time version of it.
Definition and Implementation files
------------------------------------
+====================================
A Cython module can be split into two parts: a definition file with a ``.pxd``
suffix, containing C declarations that are to be available to other Cython
statement.
What a Definition File contains
--------------------------------
+================================
A definition file can contain:
declaration if you want to make something available to external C code.
What an Implementation File contains
-------------------------------------
+======================================
An implementation file can contain any kind of Cython statement, although there
are some restrictions on the implementation part of an extension type if the
corresponding definition file also defines that type (see below).
The cimport statement
----------------------
+=======================
The :keyword:`cimport` statement is used in a definition or
implementation file to gain access to names declared in another definition
.. highlight:: cython
-.. _compilation_label:
+.. _compilation:
****************************
Source Files and Compilation
)
To understand the :file:`setup.py` more fully look at the official
-``distutils`` documentation. To compile the extension for use in the
+:mod:`distutils` documentation. To compile the extension for use in the
current directory use::
$ python setup.py build_ext --inplace
Cython Files Depending on C Files
===================================
-TODO
+When you have come C files that have been wrapped with cython and you want to
+compile them into your extension the basic :file:`setup.py` file to do this
+would be::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+ from Cython.Distutils import build_ext
+
+ sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
+
+ setup(
+ cmdclass = {'build_ext': build_ext},
+ ext_modules = [Extension("example", sourcefiles)]
+ )
+
+Notice that the files have been given a name, this is not necessary, but it
+makes the file easier to format if the list gets long.
+
+If any of the files depend on include paths information can be passed to the
+:obj:`Extension` class through the :keyword:`include_dirs` option, which is a
+list of paths to the include directories.
+
Multiple Cython Files in a Package
===================================
TODO
-Distributing Pyrex modules
-===========================
+Distributing Cython modules
+============================
It is strongly recommended that you distribute the generated ``.c`` files as well
as your Cython sources, so that users can install your module without needing
to have Cython available.
.. highlight:: cython
-.. _tutorial_label:
+.. _tutorial:
*********
Tutorial
with C data types.
Cython is Python: Almost any piece of Python code is also valid Cython code.
-(There are a few :ref:`cython-limitations-label`, but this approximation will
+(There are a few :ref:`cython-limitations`, but this approximation will
serve for now.) The Cython compiler will convert it into C code which makes
equivalent calls to the Python/C API.
print "Hello World"
So the first thing to do is rename the file to :file:`helloworld.pyx`. Now we
-need to make the :file:`setup.py`, which is like a python Makefile.::
+need to make the :file:`setup.py`, which is like a python Makefile (for more
+information see :ref:`compilation`)::
from distutils.core import setup
from distutils.extension import Extension
$ python setup.py build_ext --inplace
-Which will leave a file in your local directory called `helloworld.so` in unix
-or `helloworld.dll` in Windows. Now to use this file start the python
+Which will leave a file in your local directory called :file:`helloworld.so` in unix
+or :file:`helloworld.dll` in Windows. Now to use this file: start the python
interpreter and simply import it as if it was a regular python module::
>>> import helloworld
Language Details
================
-For more about the Cython language, see :ref:`language-basics-label`.
+For more about the Cython language, see :ref:`language-basics`.
.. highlight:: cython
-.. _wrapping-cplusplus-label:
+.. _wrapping-cplusplus:
+********************************
Wrapping C++ Classes in Cython
-====================================
+********************************
Overview
---------
+=========
This page aims to get you quickly up to speed so you can wrap C++ interfaces
with a minimum of pain and 'surprises'.
limitations, which we will discuss at the end of the document.
Procedure Overview
-------------------
+====================
* Specify C++ language in :file:`setup.py` script
* Create ``cdef extern from`` blocks and declare classes as
* Create Cython wrapper class
An example C++ API
-------------------
+===================
Here is a tiny C++ API which we will use as an example throughout this
document. Let's assume it will be in a header file called
This is pretty dumb, but should suffice to demonstrate the steps involved.
Specify C++ language in setup.py
---------------------------------
+=================================
In Cython :file:`setup.py` scripts, one normally instantiates an Extension
object. To make Cython generate and compile a C++ source, you just need
With the language="c++" keyword, Cython distutils will generate a C++ file.
Create cdef extern from block
------------------------------
+==============================
The procedure for wrapping a C++ class is quite similar to that for wrapping
normal C structs, with a couple of additions. Let's start here by creating the
This will make the C++ class def for Rectangle available.
Declare class as a ctypedef struct
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------
Now, let's add the Rectangle class to this extern from block -- just copy the
class def from :file:`Rectangle.h` and adjust for Cython syntax, so now it
we'll cover this now.
Add constructors and destructors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
We now need to expose a constructor and destructor into the Cython
namespace. Again, we'll be using C name specifications::
void del_Rectangle "delete" (c_Rectangle *rect)
Add class methods
-^^^^^^^^^^^^^^^^^
+-------------------
Now, let's add the class methods. You can circumvent Cython syntax
limitations by declaring these as function pointers. Recall that in the C++
``(int *getArea)()``.
Create Cython wrapper class
----------------------------
+=============================
At this point, we have exposed into our pyx file's namespace a struct which
gives us access to the interface of a C++ Rectangle type. Now, we need to make
...
Caveats and Limitations
------------------------
+========================
In this document, we have discussed a relatively straightforward way of
wrapping C++ classes with Cython. However, there are some limitations in
more) include:
Overloading
-^^^^^^^^^^^
+------------
Presently, it's not easy to overload methods or constructors, but there may be
a workaround if you try some creative C name specifications
Access to C-only functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
Whenever generating C++ code, Cython generates declarations of and calls
to functions assuming these functions are C++ (ie, not declared as extern "C"
respective pure-C function
Inherited C++ methods
-^^^^^^^^^^^^^^^^^^^^^
+----------------------
If you have a class ``Foo`` with a child class ``Bar``, and ``Foo`` has a
method :meth:`fred`, then you'll have to cast to access this method from
ways of handling this issue.
Advanced C++ features
-^^^^^^^^^^^^^^^^^^^^^
+----------------------
Exceptions
-""""""""""
+^^^^^^^^^^^
Cython cannot throw C++ exceptions, or catch them with a try-except statement,
but it is possible to declare a function as potentially raising an C++
raised.
Templates
-"""""""""
+^^^^^^^^^^
Cython does not natively understand C++ templates but we can put them to use
in some way. As an example consider an STL vector of C ints::
v.push_back(2)
Overloading
-"""""""""""
+^^^^^^^^^^^^
To support function overloading simply add a different alias to each
signature, so if you have e.g. ::
int fooii "foo"(int, int)
Operators
-"""""""""
+^^^^^^^^^^
Some operators (e.g. +,-,...) can be accessed from Cython like this::
c_Rectangle add "operator+"(c_Rectangle right)
Declaring/Using References
-""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Question: How do you declare and call a function that takes a reference as an argument?
Conclusion
-----------
+============
A great many existing C++ classes can be wrapped using these techniques, in a
way much easier than writing a large messy C shim module. There's a bit of
-.. Cython documentation master file, created by sphinx-quickstart on Fri Apr 25 12:49:32 2008.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-Welcome to Cython's documentation!
-================================================
+Welcome to Cython's Users Guide
+=================================
Contents:
projects / cython.git / commitdiff
