welcome
src/tutorial/index
src/reference/index
-
-
-.. note::
- .. todo::
- I think some css work is definitely needed
- 1) Really can't tell difference between section-level headers
- 2) and some etceteras..
-
-.. note::
- .. todolist::
\ No newline at end of file
Compilation
***********
-.. Describe the two stage process here
+* Cython code, unlike Python, must be compiled.
+* This happens in two stages:
-There are several ways to compile cython code.
+ * A ``.pyx`` file is compiles by Cython to a ``.c`` file.
+ * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a ``.pyd`` file on Windows)
+
+* The following sub-sections describe several ways to build your extension modules.
+
+.. note:: The ``-a`` option
+
+ * Using the Cython compiler with the ``-a`` option will produce a really nice HTML file of the Cython generated ``.c`` code.
+ * Double clicking on the highlighted sections will expand the code to reveal what Cython has actually generated for you.
+ * This is very useful for understanding, optimizing or debugging your module.
=====================
From the Command Line
=====================
+* Run the Cython compiler command with your options and list of ``.pyx`` files to generate::
+
+ $ cython -a yourmod.pyx
+
+* This creates a ``yourmod.c`` file. (and the -a switch produces a generated html file)
+* Compiling your ``.c`` files will vary depending on your operating system.
+
+ * Python documentation for writing extension modules should have some details for your system.
+
+* Here we give an example on a Linux system::
+
+ $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c
+
+ * ``gcc`` will need to have paths to your included header files and paths to libraries you need to link with.
+ * A ``yourmod.so`` file is now in the same directory.
+ * Your module, ``yourmod`` is available for you to import as you normally would.
+
+
=========
Distutils
=========
+* Ensure Distutils is installed in your system.
+* The following assumes a Cython file to be compiled called *hello.pyx*.
+* Create a ``setup.py`` script::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+ from Cython.Distutils import build_ext
+
+ ext_modules = [Extension("hello", ["hello.pyx"])]
+
+ setup(
+ name = ’Hello world app’,
+ cmdclass = {’build_ext’: build_ext},
+ ext_modules = ext_modules
+ )
+
+* Run the command ``python setup.py build_ext --inplace`` in your system's command shell.
+* Your done.. import your new extension module into your python shell or script as normal.
+
=====
SCons
=====
+to be completed...
+
=========
Pyximport
=========
+* For generating Cython code right in your pure python modulce::
+
+ >>> import pyximport; pyximport.install()
+ >>> import helloworld
+ Hello World
+
+* Use for simple Cython builds only.
+
+ * No extra C libraries.
+ * No special build setup needed.
+
+* Also has experimental compilation support for normal Python modules.
+
+ * Allows you to automatically run Cython on every ``.pyx`` and ``.py`` module that Python imports.
+
+ * This includes the standard library and installed packages.
+ * In the case that Cython fails to compile a Python module, *pyximport* will fall back to loading the source modules instead.
+
+* The ``.py`` import mechanism is installed like this::
+
+ >>> pyximport.install(pyimport = True)
+
+
+.. note:: Authors
+
+ Paul Prescod, Stefan Behnal
+
====
Sage
====
+The Sage notebook allows transparently editing and
+compiling Cython code simply by typing %cython at
+the top of a cell and evaluate it. Variables and func-
+tions defined in a Cython cell imported into the run-
+ning session.
-
+.. todo:: Provide a link to Sage docs
Extention Types
***************
+* Normal Python as well as extension type classes can be defined.
+* Extension types:
+
+ * Are considered by Python to be "built-in" types.
+ * Can be used to wrap arbitrary C data structures, and provide a Python-like interface to them from Python.
+ * Attributes and methods can be called from Python or Cython code
+ * Are defined by the ``cdef`` class statement::
+
+ cdef class Shrubbery:
+
+ cdef int width, height
+
+ def __init__(self, w, h):
+ self.width = w
+ self.height = h
+
+ def describe(self):
+ print "This shrubbery is", self.width, \
+ "by", self.height, "cubits."
+
==========
Attributes
==========
+* Are stored directly in the object's C struct.
+* Are fixed at compile time.
+
+ * You can't add attributes to an extension type instance at run time like in normal Python.
+ * You can sub-class the extenstion type in Python to add attributes at run-time.
+
+* There are two ways to access extension type attributes:
+
+ * By Python look-up.
+
+ * Python code's only method of access.
+
+ * By direct access to the C struct from Cython code.
+
+ * Cython code can use either method of access, though.
+
+* By default, extension type attributes are:
+
+ * Only accessible by direct access.
+ * Not accessible from Python code.
+
+* To make attributes accessible to Python, they must be declared ``public`` or ``readonly``::
+
+ cdef class Shrubbery:
+ cdef public int width, height
+ cdef readonly float depth
+
+ * The ``width`` and ``height`` attributes are readable and writable from Python code.
+ * The ``depth`` attribute is readable but not writable.
+
+.. note::
+ .. note::
+ You can only expose simple C types, such as ints, floats, and strings, for Python access. You can also expose Python-valued attributes.
+
+ .. note::
+ The ``public`` and ``readonly`` options apply only to Python access, not direct access. All the attributes of an extension type are always readable and writable by C-level access.
+
+
=======
Methods
=======
+* ``self`` is used in extension type methods just like it normally is in Python.
+* See **Functions and Methods**; all of which applies here.
+
==========
Properties
==========
+* Cython provides a special syntax::
+
+ cdef class Spam:
+
+ property cheese:
+
+ "A doc string can go here."
+
+ def __get__(self):
+ # This is called when the property is read.
+ ...
+
+ def __set__(self, value):
+ # This is called when the property is written.
+ ...
+
+ def __del__(self):
+ # This is called when the property is deleted.
+
+* The ``__get__()``, ``__set__()``, and ``__del__()`` methods are all optional.
+
+ * If they are ommitted, An exception is raised when an access attempt is made.
+
+* Below, is a full example that defines a property which can..
+
+ * Add to a list each time it is written to.
+ * Return the list when it is read.
+ * Empty the list when it is deleted.
+
+::
+
+ # cheesy.pyx
+ cdef class CheeseShop:
+
+ cdef object cheeses
+
+ def __cinit__(self):
+ self.cheeses = []
+
+ property cheese:
+
+ def __get__(self):
+ return "We don't have: %s" % self.cheeses
+
+ def __set__(self, value):
+ self.cheeses.append(value)
+
+ def __del__(self):
+ del self.cheeses[:]
+
+ # Test input
+ from cheesy import CheeseShop
+
+ shop = CheeseShop()
+ print shop.cheese
+
+ shop.cheese = "camembert"
+ print shop.cheese
+
+ shop.cheese = "cheddar"
+ print shop.cheese
+
+ del shop.cheese
+ print shop.cheese
+
+::
+
+ # Test output
+ We don't have: []
+ We don't have: ['camembert']
+ We don't have: ['camembert', 'cheddar']
+ We don't have: []
+
+
===============
Special Methods
===============
Forward Declarations
====================
+========================
+Extension Types and None
+========================
+
================
Weak Referencing
================
* There are three types of function declarations in Cython as the sub-sections show below.
* Only "Python" functions can be called outside a Cython module from *Python interpretted code*.
-*
+
Callable from Python
=====================
projects / cython.git / commitdiff