Commit 2e83f128 authored by ggellner@encolpuis's avatar ggellner@encolpuis

Fixed heading levels. Added some Cython branding!

parent 9b08f2ff
...@@ -87,12 +87,18 @@ html_style = 'default.css' ...@@ -87,12 +87,18 @@ html_style = 'default.css'
# Add any paths that contain custom static files (such as style sheets) here, # 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, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # 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, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.
html_last_updated_fmt = '%b %d, %Y' 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 # If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities. # typographically correct entities.
#html_use_smartypants = True #html_use_smartypants = True
......
.. highlight:: cython .. highlight:: cython
.. _early-binding-speed-label: .. _early-binding-for-speed:
**************************
Early Binding for Speed Early Binding for Speed
======================= **************************
As a dynamic language, Python encourages a programming style of considering As a dynamic language, Python encourages a programming style of considering
classes and objects in terms of their methods and attributes, more than where classes and objects in terms of their methods and attributes, more than where
...@@ -98,7 +99,7 @@ overheads. Consider this code: ...@@ -98,7 +99,7 @@ overheads. Consider this code:
rect = Rectangle(x0, y0, x1, y1) rect = Rectangle(x0, y0, x1, y1)
return rect.area() return rect.area()
.. Note:: .. note::
in earlier versions of Cython, the :keyword:`cpdef` keyword is in earlier versions of Cython, the :keyword:`cpdef` keyword is
:keyword:`rdef` - but has the same effect). :keyword:`rdef` - but has the same effect).
......
.. highlight:: cython .. highlight:: cython
.. _extension-types:
******************
Extension Types Extension Types
=============== ******************
Introduction Introduction
------------- ==============
As well as creating normal user-defined classes with the Python class 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 statement, Cython also lets you create new built-in Python types, known as
...@@ -35,7 +38,7 @@ extension types to wrap arbitrary C data structures and provide a Python-like ...@@ -35,7 +38,7 @@ extension types to wrap arbitrary C data structures and provide a Python-like
interface to them. interface to them.
Attributes Attributes
----------- ============
Attributes of an extension type are stored directly in the object's C struct. 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 The set of attributes is fixed at compile time; you can't add attributes to an
...@@ -75,7 +78,7 @@ and the depth attribute readable but not writable. ...@@ -75,7 +78,7 @@ and the depth attribute readable but not writable.
are always readable and writable by direct access. are always readable and writable by direct access.
Type declarations Type declarations
----------------- ===================
Before you can directly access the attributes of an extension type, the Cython 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 compiler must know that you have an instance of that type, and not just a
...@@ -112,7 +115,7 @@ The same consideration applies to local variables, for example,:: ...@@ -112,7 +115,7 @@ The same consideration applies to local variables, for example,::
return sh2 return sh2
Extension types and None Extension types and None
------------------------ =========================
When you declare a parameter or C variable as being of an extension type, 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 Cython will allow it to take on the value ``None`` as well as values of its
...@@ -171,7 +174,7 @@ with checking that it has the right type. ...@@ -171,7 +174,7 @@ with checking that it has the right type.
will invoke Python operations and therefore be much slower. will invoke Python operations and therefore be much slower.
Special methods Special methods
--------------- ================
Although the principles are similar, there are substantial differences between Although the principles are similar, there are substantial differences between
many of the :meth:`__xxx__` special methods of extension types and their Python many of the :meth:`__xxx__` special methods of extension types and their Python
...@@ -180,7 +183,7 @@ read it carefully before attempting to use any special methods in your ...@@ -180,7 +183,7 @@ read it carefully before attempting to use any special methods in your
extension types. extension types.
Properties Properties
---------- ============
There is a special syntax for defining properties in an extension class:: There is a special syntax for defining properties in an extension class::
...@@ -251,7 +254,7 @@ when it is deleted.:: ...@@ -251,7 +254,7 @@ when it is deleted.::
We don't have: [] We don't have: []
Subclassing Subclassing
----------- =============
An extension type may inherit from a built-in type or another extension type:: An extension type may inherit from a built-in type or another extension type::
...@@ -316,7 +319,7 @@ method using the usual Python technique, i.e.:: ...@@ -316,7 +319,7 @@ method using the usual Python technique, i.e.::
Parrot.describe(self) Parrot.describe(self)
Forward-declaring extension types Forward-declaring extension types
--------------------------------- ===================================
Extension types can be forward-declared, like :keyword:`struct` and Extension types can be forward-declared, like :keyword:`struct` and
:keyword:`union` types. This will be necessary if you have two extension types :keyword:`union` types. This will be necessary if you have two extension types
...@@ -342,7 +345,7 @@ definition, for example,:: ...@@ -342,7 +345,7 @@ definition, for example,::
# attributes and methods # attributes and methods
Making extension types weak-referenceable Making extension types weak-referenceable
----------------------------------------- ==========================================
By default, extension types do not support having weak references made to 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 them. You can enable weak referencing by declaring a C attribute of type
...@@ -355,7 +358,7 @@ object called :attr:`__weakref__`. For example,:: ...@@ -355,7 +358,7 @@ object called :attr:`__weakref__`. For example,::
cdef object __weakref__ cdef object __weakref__
Public and external extension types Public and external extension types
----------------------------------- ====================================
Extension types can be declared extern or public. An extern extension type 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 declaration makes an extension type defined in external C code available to a
...@@ -373,7 +376,7 @@ objects defined in the Python core or in a non-Cython extension module. ...@@ -373,7 +376,7 @@ objects defined in the Python core or in a non-Cython extension module.
In Pyrex versions before 0.8, extern extension types were also used to 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 reference extension types defined in another Pyrex module. While you can still
do that, Cython provides a better mechanism for this. See 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 Here is an example which will let you get at the C-level members of the
built-in complex object.:: built-in complex object.::
......
.. highlight:: cython .. highlight:: cython
.. external-C-code:
**********************************
Interfacing with External C Code Interfacing with External C Code
================================ **********************************
One of the main uses of Cython is wrapping existing libraries of C code. This 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 is achieved by using external declarations to declare the C functions and
...@@ -15,7 +18,7 @@ Cython module can be used as a bridge to allow Python code to call C code, it ...@@ -15,7 +18,7 @@ Cython module can be used as a bridge to allow Python code to call C code, it
can also be used to allow C code to call Python code. can also be used to allow C code to call Python code.
External declarations External declarations
--------------------- =======================
By default, C functions and variables declared at the module level are local 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 to the module (i.e. they have the C static storage class). They can also be
...@@ -26,7 +29,7 @@ declared extern to specify that they are defined elsewhere, for example:: ...@@ -26,7 +29,7 @@ declared extern to specify that they are defined elsewhere, for example::
cdef extern void order_spam(int tons) cdef extern void order_spam(int tons)
Referencing C header files Referencing C header files
^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------------------------
When you use an extern definition on its own as in the examples above, Cython 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 includes a declaration for it in the generated C file. This can cause problems
...@@ -143,7 +146,7 @@ A few more tricks and tips: ...@@ -143,7 +146,7 @@ A few more tricks and tips:
... ...
Styles of struct, union and enum declaration Styles of struct, union and enum declaration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------------------
There are two main ways that structs, unions and enums can be declared in C 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 header files: using a tag name, or using a typedef. There are also some
...@@ -198,7 +201,7 @@ Note that in all the cases below, you refer to the type in Cython code simply ...@@ -198,7 +201,7 @@ Note that in all the cases below, you refer to the type in Cython code simply
as :ctype:`Foo`, not ``struct Foo``. as :ctype:`Foo`, not ``struct Foo``.
Accessing Python/C API routines Accessing Python/C API routines
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------------------------------
One particular use of the ``cdef extern from`` statement is for gaining access to One particular use of the ``cdef extern from`` statement is for gaining access to
routines in the Python/C API. For example,:: routines in the Python/C API. For example,::
...@@ -210,14 +213,14 @@ routines in the Python/C API. For example,:: ...@@ -210,14 +213,14 @@ routines in the Python/C API. For example,::
will allow you to create Python strings containing null bytes. will allow you to create Python strings containing null bytes.
Special Types Special Types
^^^^^^^^^^^^^ --------------
Cython predefines the name ``Py_ssize_t`` for use with Python/C API routines. To 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 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. this type where it is specified in the documentation of Python/C API routines.
Windows Calling Conventions Windows Calling Conventions
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------
The ``__stdcall`` and ``__cdecl`` calling convention specifiers can be used in 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,:: Cython, with the same syntax as used by C compilers on Windows, for example,::
...@@ -230,7 +233,7 @@ If ``__stdcall`` is used, the function is only considered compatible with ...@@ -230,7 +233,7 @@ If ``__stdcall`` is used, the function is only considered compatible with
other ``__stdcall`` functions of the same signature. other ``__stdcall`` functions of the same signature.
Resolving naming conflicts - C name specifications Resolving naming conflicts - C name specifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------------------------
Each Cython module has a single module-level namespace for both Python and C 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 names. This can be inconvenient if you want to wrap some external C functions
...@@ -274,7 +277,7 @@ enums, struct and union members, and enum values. For example,:: ...@@ -274,7 +277,7 @@ enums, struct and union members, and enum values. For example,::
second "beta" = 3 second "beta" = 3
Using Cython Declarations from C Using Cython Declarations from C
-------------------------------- ==================================
Cython provides two methods for making C declarations from a Cython module Cython provides two methods for making C declarations from a Cython module
available for use by external C code – public declarations and C API available for use by external C code – public declarations and C API
...@@ -287,7 +290,7 @@ declarations. ...@@ -287,7 +290,7 @@ declarations.
:keyword:`cimport` statement for that. Sharing Declarations Between Cython Modules. :keyword:`cimport` statement for that. Sharing Declarations Between Cython Modules.
Public Declarations Public Declarations
^^^^^^^^^^^^^^^^^^^ ---------------------
You can make C types, variables and functions defined in a Cython module 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 accessible to C code that is linked with the module, by declaring them with
...@@ -313,7 +316,7 @@ file consists of the full dotted name of the module, e.g. a module called ...@@ -313,7 +316,7 @@ file consists of the full dotted name of the module, e.g. a module called
:mod:`foo.spam` would have a header file called :file:`foo.spam.h`. :mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
C API Declarations C API Declarations
^^^^^^^^^^^^^^^^^^ -------------------
The other way of making declarations available to C code is to declare them 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 with the :keyword:`api` keyword. You can use this keyword with C functions and
...@@ -381,8 +384,8 @@ E.g. a module called :mod:`foo.spam` would have an API header file called ...@@ -381,8 +384,8 @@ E.g. a module called :mod:`foo.spam` would have an API header file called
:file:`foo.spam_api.h` and an importing function called :file:`foo.spam_api.h` and an importing function called
:func:`import_foo__spam`. :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 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 :keyword:`api` all at once by enclosing them in a :keyword:`cdef` block, for
...@@ -393,11 +396,11 @@ example,:: ...@@ -393,11 +396,11 @@ example,::
char *get_lunch(float tomato_size) char *get_lunch(float tomato_size)
This can be a useful thing to do in a ``.pxd`` file (see 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. available by all three methods.
Acquiring and Releasing the GIL Acquiring and Releasing the GIL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------------------------------
Cython provides facilities for releasing the Global Interpreter Lock (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 before calling C code, and for acquiring the GIL in functions that are to be
...@@ -428,7 +431,7 @@ header:: ...@@ -428,7 +431,7 @@ header::
... ...
Declaring a function as callable without the GIL Declaring a function as callable without the GIL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------------------------
You can specify :keyword:`nogil` in a C function header or function type to You can specify :keyword:`nogil` in a C function header or function type to
declare that it is safe to call without the GIL.:: declare that it is safe to call without the GIL.::
......
.. highlight:: cython .. highlight:: cython
.. _language-basics-label: .. _language-basics:
*****************
Language Basics Language Basics
=============== *****************
Python functions vs. C functions Python functions vs. C functions
-------------------------------- ==================================
There are two kinds of function definition in Cython: There are two kinds of function definition in Cython:
...@@ -123,7 +124,7 @@ an anonymous :keyword:`enum` declaration for this purpose, for example,:: ...@@ -123,7 +124,7 @@ an anonymous :keyword:`enum` declaration for this purpose, for example,::
ctypedef int *IntPtr ctypedef int *IntPtr
Grouping multiple C declarations Grouping multiple C declarations
================================ ==================================
If you have a series of declarations that all begin with :keyword:`cdef`, you If you have a series of declarations that all begin with :keyword:`cdef`, you
can group them into a :keyword:`cdef` block like this:: can group them into a :keyword:`cdef` block like this::
...@@ -422,7 +423,7 @@ The include statement ...@@ -422,7 +423,7 @@ The include statement
---------------------- ----------------------
.. warning:: .. 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 A Cython source file can include material from other files using the include
statement, for example:: statement, for example::
...@@ -440,7 +441,7 @@ the level of the include statement that is including the file. ...@@ -440,7 +441,7 @@ the level of the include statement that is including the file.
There are other mechanisms available for splitting Cython code into There are other mechanisms available for splitting Cython code into
separate parts that may be more appropriate in many cases. See separate parts that may be more appropriate in many cases. See
:ref:`sharing-declarations-label`. :ref:`sharing-declarations`.
Keyword-only arguments Keyword-only arguments
---------------------- ----------------------
......
.. highlight:: cython .. highlight:: cython
.. _cython-limitations-label: .. _cython-limitations:
************* *************
Limitations Limitations
......
.. highlight:: cython .. highlight:: cython
.. _numpy_tute-label: .. _numpy_tutorial:
************************** **************************
Cython for NumPy users Cython for NumPy users
...@@ -34,6 +34,7 @@ The style of this tutorial will not fit everybody, so you can also consider: ...@@ -34,6 +34,7 @@ The style of this tutorial will not fit everybody, so you can also consider:
Cython at a glance Cython at a glance
==================== ====================
Cython is a compiler which compiles Python-like code files to C code. Still, 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 ''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 program and "turns it into C" -- rather, the result makes full use of the
...@@ -56,6 +57,7 @@ functions and generator functions). ...@@ -56,6 +57,7 @@ functions and generator functions).
Your Cython environment Your Cython environment
======================== ========================
Using Cython consists of these steps: Using Cython consists of these steps:
1. Write a :file:`.pyx` source file 1. Write a :file:`.pyx` source file
......
.. highlight:: cython .. highlight:: cython
.. _overview-label: .. _overview:
******** ********
Overview Overview
...@@ -24,9 +24,9 @@ and for fast C modules that speed up the execution of Python code. ...@@ -24,9 +24,9 @@ and for fast C modules that speed up the execution of Python code.
Future Plans Future Plans
============ ============
Cython is not finished. Substantial tasks remaining. See 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 .. rubric:: Footnotes
.. [#] For differences with Pyrex see :ref:`pyrex-differences-label`. .. [#] For differences with Pyrex see :ref:`pyrex-differences`.
.. highlight:: cython .. highlight:: cython
.. _pyrex-differences-label: .. _pyrex-differences:
**************************************
Differences between Cython and Pyrex Differences between Cython and Pyrex
==================================== **************************************
Package names and cross-directory imports Package names and cross-directory imports
----------------------------------------- ==========================================
Just like in python. Just like in python.
List Comprehensions List Comprehensions
------------------- ====================
`[expr(x) for x in A]` is now available, implementing the full specification `[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 at http://www.python.org/dev/peps/pep-0202/ . Looping is optimized if ``A`` is
...@@ -20,7 +21,7 @@ a list. Also, use the :keyword:`for` ... :keyword:`from` syntax too, e.g.:: ...@@ -20,7 +21,7 @@ a list. Also, use the :keyword:`for` ... :keyword:`from` syntax too, e.g.::
[i*i for i from 0 <= i < 10] [i*i for i from 0 <= i < 10]
Conditional expressions "x if b else y" (python 2.5) Conditional expressions "x if b else y" (python 2.5)
---------------------------------------------------- =====================================================
Conditional expressions as described in Conditional expressions as described in
http://www.python.org/dev/peps/pep-0308/:: http://www.python.org/dev/peps/pep-0308/::
...@@ -30,7 +31,7 @@ http://www.python.org/dev/peps/pep-0308/:: ...@@ -30,7 +31,7 @@ http://www.python.org/dev/peps/pep-0308/::
Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C).
cdef inline cdef inline
----------- =============
Module level functions can now be declared inline, with the :keyword:`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.:: keyword passed on to the C compiler. These can be as fast as macros.::
...@@ -43,7 +44,7 @@ function table, so the compiler won't be able to inline them in almost all ...@@ -43,7 +44,7 @@ function table, so the compiler won't be able to inline them in almost all
cases. cases.
Assignment on declaration (e.g. "cdef int spam = 5") Assignment on declaration (e.g. "cdef int spam = 5")
---------------------------------------------------- ======================================================
In Pyrex, one must write:: In Pyrex, one must write::
...@@ -62,7 +63,7 @@ The expression on the right hand side can be arbitrarily complicated, e.g.:: ...@@ -62,7 +63,7 @@ The expression on the right hand side can be arbitrarily complicated, e.g.::
'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2") 'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2")
---------------------------------------------------------------- ==================================================================
:: ::
...@@ -82,7 +83,7 @@ yields:: ...@@ -82,7 +83,7 @@ yields::
Boolean int type (e.g. it acts like a c int, but coerces to/from python as a boolean) 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 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 truth value (using the :meth:`__nonzero__` method, but the canonical choices
...@@ -107,7 +108,7 @@ happen via ``x.__nonzero__()``. (Actually, if ``x`` is the python object ...@@ -107,7 +108,7 @@ happen via ``x.__nonzero__()``. (Actually, if ``x`` is the python object
``True`` or ``False`` then no method call is made.) ``True`` or ``False`` then no method call is made.)
Executable class bodies Executable class bodies
----------------------- =========================
Including a working :func:`classmethod`:: Including a working :func:`classmethod`::
...@@ -119,7 +120,7 @@ Including a working :func:`classmethod`:: ...@@ -119,7 +120,7 @@ Including a working :func:`classmethod`::
print "hi", a print "hi", a
cpdef functions cpdef functions
--------------- =================
Cython adds a third function type on top of the usual :keyword:`def` and 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 :keyword:`cdef`. If a function is declared :keyword:`cpdef` it can be called
...@@ -154,12 +155,12 @@ method on the class directly, e.g.:: ...@@ -154,12 +155,12 @@ method on the class directly, e.g.::
x.foo() # will check to see if overridden x.foo() # will check to see if overridden
A.foo(x) # will call A's implementation whether overridden or not 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:
Automatic range conversion Automatic range conversion
------------------------------------- ============================
This will convert statements of the form ``for i in range(...)`` to ``for i 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 from ...`` when ``i`` is any cdef'd integer type, and the direction (i.e. sign
...@@ -175,7 +176,7 @@ of step) can be determined. ...@@ -175,7 +176,7 @@ of step) can be determined.
way to set this). way to set this).
More friendly type casting More friendly type casting
-------------------------- ===========================
In Pyrex, if one types ``<int>x`` where ``x`` is a Python object, one will get 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`` the memory address of ``x``. Likewise, if one types ``<object>i`` where ``i``
...@@ -193,7 +194,7 @@ with type checking (i.e. it will throw an error if ``x`` is not a (subclass of) ...@@ -193,7 +194,7 @@ with type checking (i.e. it will throw an error if ``x`` is not a (subclass of)
:ctype:`MyExtensionType`. :ctype:`MyExtensionType`.
Optional arguments in cdef/cpdef functions Optional arguments in cdef/cpdef functions
------------------------------------------ ============================================
Cython now supports optional arguments for :keyword:`cdef` and Cython now supports optional arguments for :keyword:`cdef` and
:keyword:`cpdef` functions. :keyword:`cpdef` functions.
...@@ -232,13 +233,13 @@ with corresponding ``.pyx`` file:: ...@@ -232,13 +233,13 @@ with corresponding ``.pyx`` file::
:keyword:`cdef` functions. :keyword:`cdef` functions.
Function pointers in structs Function pointers in structs
---------------------------- =============================
Functions declared in :keyword:`structs` are automatically converted to Functions declared in :keyword:`structs` are automatically converted to
function pointers for convenience. function pointers for convenience.
C++ Exception handling C++ Exception handling
---------------------- =========================
:keyword:`cdef` functions can now be declared as:: :keyword:`cdef` functions can now be declared as::
...@@ -247,15 +248,15 @@ C++ Exception handling ...@@ -247,15 +248,15 @@ C++ Exception handling
cdef int foo(...) except +python_error_raising_function cdef int foo(...) except +python_error_raising_function
in which case a Python exception will be raised when a C++ error is caught. 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 Synonyms
-------- =========
``cdef import from`` means the same thing as ``cdef extern from`` ``cdef import from`` means the same thing as ``cdef extern from``
Source code encoding Source code encoding
-------------------- ======================
.. TODO: add the links to the relevent PEPs .. TODO: add the links to the relevent PEPs
......
.. highlight:: cython .. highlight:: cython
.. _sharing-declarations-label: .. _sharing-declarations:
********************************************
Sharing Declarations Between Cython Modules Sharing Declarations Between Cython Modules
=========================================== ********************************************
This section describes a new set of facilities for making C declarations, This section describes a new set of facilities for making C declarations,
functions and extension types in one Cython module available for use in functions and extension types in one Cython module available for use in
...@@ -11,7 +12,7 @@ another Cython module. These facilities are closely modelled on the Python ...@@ -11,7 +12,7 @@ another Cython module. These facilities are closely modelled on the Python
import mechanism, and can be thought of as a compile-time version of it. import mechanism, and can be thought of as a compile-time version of it.
Definition and Implementation files Definition and Implementation files
----------------------------------- ====================================
A Cython module can be split into two parts: a definition file with a ``.pxd`` 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 suffix, containing C declarations that are to be available to other Cython
...@@ -21,7 +22,7 @@ module's definition file, it imports it using the :keyword:`cimport` ...@@ -21,7 +22,7 @@ module's definition file, it imports it using the :keyword:`cimport`
statement. statement.
What a Definition File contains What a Definition File contains
------------------------------- ================================
A definition file can contain: A definition file can contain:
...@@ -43,14 +44,14 @@ Python class definitions, or any executable statements. ...@@ -43,14 +44,14 @@ Python class definitions, or any executable statements.
declaration if you want to make something available to external C code. declaration if you want to make something available to external C code.
What an Implementation File contains What an Implementation File contains
------------------------------------ ======================================
An implementation file can contain any kind of Cython statement, although there 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 are some restrictions on the implementation part of an extension type if the
corresponding definition file also defines that type (see below). corresponding definition file also defines that type (see below).
The cimport statement The cimport statement
--------------------- =======================
The :keyword:`cimport` statement is used in a definition or The :keyword:`cimport` statement is used in a definition or
implementation file to gain access to names declared in another definition implementation file to gain access to names declared in another definition
......
.. highlight:: cython .. highlight:: cython
.. _compilation_label: .. _compilation:
**************************** ****************************
Source Files and Compilation Source Files and Compilation
...@@ -44,7 +44,7 @@ would be:: ...@@ -44,7 +44,7 @@ would be::
) )
To understand the :file:`setup.py` more fully look at the official 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:: current directory use::
$ python setup.py build_ext --inplace $ python setup.py build_ext --inplace
...@@ -52,15 +52,36 @@ current directory use:: ...@@ -52,15 +52,36 @@ current directory use::
Cython Files Depending on C Files 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 Multiple Cython Files in a Package
=================================== ===================================
TODO TODO
Distributing Pyrex modules Distributing Cython modules
=========================== ============================
It is strongly recommended that you distribute the generated ``.c`` files as well 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 as your Cython sources, so that users can install your module without needing
to have Cython available. to have Cython available.
......
.. highlight:: cython .. highlight:: cython
.. _tutorial_label: .. _tutorial:
********* *********
Tutorial Tutorial
...@@ -13,7 +13,7 @@ The fundamental nature of Cython can be summed up as follows: Cython is Python ...@@ -13,7 +13,7 @@ The fundamental nature of Cython can be summed up as follows: Cython is Python
with C data types. with C data types.
Cython is Python: Almost any piece of Python code is also valid Cython code. 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 serve for now.) The Cython compiler will convert it into C code which makes
equivalent calls to the Python/C API. equivalent calls to the Python/C API.
...@@ -38,7 +38,8 @@ So lets start with the canonical python hello world:: ...@@ -38,7 +38,8 @@ So lets start with the canonical python hello world::
print "Hello World" print "Hello World"
So the first thing to do is rename the file to :file:`helloworld.pyx`. Now we 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.core import setup
from distutils.extension import Extension from distutils.extension import Extension
...@@ -53,8 +54,8 @@ To use this to build your Cython file use the commandline options:: ...@@ -53,8 +54,8 @@ To use this to build your Cython file use the commandline options::
$ python setup.py build_ext --inplace $ python setup.py build_ext --inplace
Which will leave a file in your local directory called `helloworld.so` in unix Which will leave a file in your local directory called :file:`helloworld.so` in unix
or `helloworld.dll` in Windows. Now to use this file start the python 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:: interpreter and simply import it as if it was a regular python module::
>>> import helloworld >>> import helloworld
...@@ -138,5 +139,5 @@ take a look at the C code generated for this module. ...@@ -138,5 +139,5 @@ take a look at the C code generated for this module.
Language Details 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 .. highlight:: cython
.. _wrapping-cplusplus-label: .. _wrapping-cplusplus:
********************************
Wrapping C++ Classes in Cython Wrapping C++ Classes in Cython
==================================== ********************************
Overview Overview
-------- =========
This page aims to get you quickly up to speed so you can wrap C++ interfaces This page aims to get you quickly up to speed so you can wrap C++ interfaces
with a minimum of pain and 'surprises'. with a minimum of pain and 'surprises'.
...@@ -24,7 +25,7 @@ you wrap a lot of C++ code with only moderate effort. There are some ...@@ -24,7 +25,7 @@ you wrap a lot of C++ code with only moderate effort. There are some
limitations, which we will discuss at the end of the document. limitations, which we will discuss at the end of the document.
Procedure Overview Procedure Overview
------------------ ====================
* Specify C++ language in :file:`setup.py` script * Specify C++ language in :file:`setup.py` script
* Create ``cdef extern from`` blocks and declare classes as * Create ``cdef extern from`` blocks and declare classes as
...@@ -34,7 +35,7 @@ Procedure Overview ...@@ -34,7 +35,7 @@ Procedure Overview
* Create Cython wrapper class * Create Cython wrapper class
An example C++ API An example C++ API
------------------ ===================
Here is a tiny C++ API which we will use as an example throughout this 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 document. Let's assume it will be in a header file called
...@@ -54,7 +55,7 @@ document. Let's assume it will be in a header file called ...@@ -54,7 +55,7 @@ document. Let's assume it will be in a header file called
This is pretty dumb, but should suffice to demonstrate the steps involved. This is pretty dumb, but should suffice to demonstrate the steps involved.
Specify C++ language in setup.py Specify C++ language in setup.py
-------------------------------- =================================
In Cython :file:`setup.py` scripts, one normally instantiates an Extension In Cython :file:`setup.py` scripts, one normally instantiates an Extension
object. To make Cython generate and compile a C++ source, you just need object. To make Cython generate and compile a C++ source, you just need
...@@ -73,7 +74,7 @@ to add a keyword to your Extension construction statement, as in:: ...@@ -73,7 +74,7 @@ to add a keyword to your Extension construction statement, as in::
With the language="c++" keyword, Cython distutils will generate a C++ file. With the language="c++" keyword, Cython distutils will generate a C++ file.
Create cdef extern from block Create cdef extern from block
----------------------------- ==============================
The procedure for wrapping a C++ class is quite similar to that for wrapping 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 normal C structs, with a couple of additions. Let's start here by creating the
...@@ -84,7 +85,7 @@ basic ``cdef extern from`` block:: ...@@ -84,7 +85,7 @@ basic ``cdef extern from`` block::
This will make the C++ class def for Rectangle available. This will make the C++ class def for Rectangle available.
Declare class as a ctypedef struct Declare class as a ctypedef struct
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------------
Now, let's add the Rectangle class to this extern from block -- just copy the 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 class def from :file:`Rectangle.h` and adjust for Cython syntax, so now it
...@@ -99,7 +100,7 @@ We don't have any way of accessing the constructor/destructor or methods, but ...@@ -99,7 +100,7 @@ We don't have any way of accessing the constructor/destructor or methods, but
we'll cover this now. we'll cover this now.
Add constructors and destructors Add constructors and destructors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------
We now need to expose a constructor and destructor into the Cython We now need to expose a constructor and destructor into the Cython
namespace. Again, we'll be using C name specifications:: namespace. Again, we'll be using C name specifications::
...@@ -111,7 +112,7 @@ namespace. Again, we'll be using C name specifications:: ...@@ -111,7 +112,7 @@ namespace. Again, we'll be using C name specifications::
void del_Rectangle "delete" (c_Rectangle *rect) void del_Rectangle "delete" (c_Rectangle *rect)
Add class methods Add class methods
^^^^^^^^^^^^^^^^^ -------------------
Now, let's add the class methods. You can circumvent Cython syntax Now, let's add the class methods. You can circumvent Cython syntax
limitations by declaring these as function pointers. Recall that in the C++ limitations by declaring these as function pointers. Recall that in the C++
...@@ -142,7 +143,7 @@ In Pyrex you must explicitly declare these as function pointers, i.e. ...@@ -142,7 +143,7 @@ In Pyrex you must explicitly declare these as function pointers, i.e.
``(int *getArea)()``. ``(int *getArea)()``.
Create Cython wrapper class Create Cython wrapper class
--------------------------- =============================
At this point, we have exposed into our pyx file's namespace a struct which 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 gives us access to the interface of a C++ Rectangle type. Now, we need to make
...@@ -177,7 +178,7 @@ attribute access, you could just implement some properties:: ...@@ -177,7 +178,7 @@ attribute access, you could just implement some properties::
... ...
Caveats and Limitations Caveats and Limitations
----------------------- ========================
In this document, we have discussed a relatively straightforward way of In this document, we have discussed a relatively straightforward way of
wrapping C++ classes with Cython. However, there are some limitations in wrapping C++ classes with Cython. However, there are some limitations in
...@@ -189,13 +190,13 @@ The major limitations I'm most immediately aware of (and there will be many ...@@ -189,13 +190,13 @@ The major limitations I'm most immediately aware of (and there will be many
more) include: more) include:
Overloading Overloading
^^^^^^^^^^^ ------------
Presently, it's not easy to overload methods or constructors, but there may be Presently, it's not easy to overload methods or constructors, but there may be
a workaround if you try some creative C name specifications a workaround if you try some creative C name specifications
Access to C-only functions Access to C-only functions
^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------------------------
Whenever generating C++ code, Cython generates declarations of and calls Whenever generating C++ code, Cython generates declarations of and calls
to functions assuming these functions are C++ (ie, not declared as extern "C" to functions assuming these functions are C++ (ie, not declared as extern "C"
...@@ -209,7 +210,7 @@ module which: ...@@ -209,7 +210,7 @@ module which:
respective pure-C function respective pure-C function
Inherited C++ methods Inherited C++ methods
^^^^^^^^^^^^^^^^^^^^^ ----------------------
If you have a class ``Foo`` with a child class ``Bar``, and ``Foo`` has a 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 method :meth:`fred`, then you'll have to cast to access this method from
...@@ -228,10 +229,10 @@ It might take some experimenting by others (you?) to find the most elegant ...@@ -228,10 +229,10 @@ It might take some experimenting by others (you?) to find the most elegant
ways of handling this issue. ways of handling this issue.
Advanced C++ features Advanced C++ features
^^^^^^^^^^^^^^^^^^^^^ ----------------------
Exceptions Exceptions
"""""""""" ^^^^^^^^^^^
Cython cannot throw C++ exceptions, or catch them with a try-except statement, 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++ but it is possible to declare a function as potentially raising an C++
...@@ -258,7 +259,7 @@ raise_py_error does not actually raise an exception a RuntimeError will be ...@@ -258,7 +259,7 @@ raise_py_error does not actually raise an exception a RuntimeError will be
raised. raised.
Templates Templates
""""""""" ^^^^^^^^^^
Cython does not natively understand C++ templates but we can put them to use 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:: in some way. As an example consider an STL vector of C ints::
...@@ -274,7 +275,7 @@ now we can use the vector like this:: ...@@ -274,7 +275,7 @@ now we can use the vector like this::
v.push_back(2) v.push_back(2)
Overloading Overloading
""""""""""" ^^^^^^^^^^^^
To support function overloading simply add a different alias to each To support function overloading simply add a different alias to each
signature, so if you have e.g. :: signature, so if you have e.g. ::
...@@ -288,7 +289,7 @@ in your C++ header then interface it like this in your :: ...@@ -288,7 +289,7 @@ in your C++ header then interface it like this in your ::
int fooii "foo"(int, int) int fooii "foo"(int, int)
Operators Operators
""""""""" ^^^^^^^^^^
Some operators (e.g. +,-,...) can be accessed from Cython like this:: Some operators (e.g. +,-,...) can be accessed from Cython like this::
...@@ -296,12 +297,12 @@ Some operators (e.g. +,-,...) can be accessed from Cython like this:: ...@@ -296,12 +297,12 @@ Some operators (e.g. +,-,...) can be accessed from Cython like this::
c_Rectangle add "operator+"(c_Rectangle right) c_Rectangle add "operator+"(c_Rectangle right)
Declaring/Using References Declaring/Using References
"""""""""""""""""""""""""" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Question: How do you declare and call a function that takes a reference as an argument? Question: How do you declare and call a function that takes a reference as an argument?
Conclusion Conclusion
---------- ============
A great many existing C++ classes can be wrapped using these techniques, in a 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 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: Contents:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment