From 70816c16d2c36a96fb7f632e97325fd1ea06dc33 Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Tue, 6 Oct 2009 03:31:14 -0400 Subject: [PATCH] compilation and extension types started --- index.rst | 10 --- src/reference/compilation.rst | 87 ++++++++++++++++++- src/reference/extension_types.rst | 139 ++++++++++++++++++++++++++++++ src/reference/language_basics.rst | 2 +- 4 files changed, 224 insertions(+), 14 deletions(-) diff --git a/index.rst b/index.rst index a48069fe..2b827b2b 100644 --- a/index.rst +++ b/index.rst @@ -10,13 +10,3 @@ Contents: 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 diff --git a/src/reference/compilation.rst b/src/reference/compilation.rst index 981d88e5..e62d9a99 100644 --- a/src/reference/compilation.rst +++ b/src/reference/compilation.rst @@ -6,32 +6,113 @@ 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 diff --git a/src/reference/extension_types.rst b/src/reference/extension_types.rst index b69be066..190e733b 100644 --- a/src/reference/extension_types.rst +++ b/src/reference/extension_types.rst @@ -6,18 +6,153 @@ 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 =============== @@ -32,6 +167,10 @@ Subclassing Forward Declarations ==================== +======================== +Extension Types and None +======================== + ================ Weak Referencing ================ diff --git a/src/reference/language_basics.rst b/src/reference/language_basics.rst index 45cd2fac..e086f48d 100644 --- a/src/reference/language_basics.rst +++ b/src/reference/language_basics.rst @@ -514,7 +514,7 @@ Functions and Methods * 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 ===================== -- 2.26.2