Commit 70816c16 authored by Peter Alexander's avatar Peter Alexander

compilation and extension types started

parent 3d1e83f9
...@@ -10,13 +10,3 @@ Contents: ...@@ -10,13 +10,3 @@ Contents:
welcome welcome
src/tutorial/index src/tutorial/index
src/reference/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
...@@ -6,32 +6,113 @@ ...@@ -6,32 +6,113 @@
Compilation 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 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 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 SCons
===== =====
to be completed...
========= =========
Pyximport 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 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
......
...@@ -6,18 +6,153 @@ ...@@ -6,18 +6,153 @@
Extention Types 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 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 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 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 Special Methods
=============== ===============
...@@ -32,6 +167,10 @@ Subclassing ...@@ -32,6 +167,10 @@ Subclassing
Forward Declarations Forward Declarations
==================== ====================
========================
Extension Types and None
========================
================ ================
Weak Referencing Weak Referencing
================ ================
......
...@@ -514,7 +514,7 @@ Functions and Methods ...@@ -514,7 +514,7 @@ Functions and Methods
* There are three types of function declarations in Cython as the sub-sections show below. * 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*. * Only "Python" functions can be called outside a Cython module from *Python interpretted code*.
*
Callable from Python Callable from Python
===================== =====================
......
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