compilation and extension types started

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

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
 
 
 

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
 ================

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
 =====================