Initial commit

Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web htmlhelp latex changes linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  web       to make files usable by Sphinx.web"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf build/*
+
+html:
+	mkdir -p build/html build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+
+web:
+	mkdir -p build/web build/doctrees
+	$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) build/web
+	@echo
+	@echo "Build finished; now you can run"
+	@echo "  python -m sphinx.web build/web"
+	@echo "to start the server."
+
+htmlhelp:
+	mkdir -p build/htmlhelp build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in build/htmlhelp."
+
+latex:
+	mkdir -p build/latex build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p build/changes build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+	@echo
+	@echo "The overview file is in build/changes."
+
+linkcheck:
+	mkdir -p build/linkcheck build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in build/linkcheck/output.txt."

README

+This is a collection of all the assorted pyrex/cython documentation assembled into
+a unified Python style Sphinx project. It is hoped that this will become the default
+documentation for the Cython tool set.

conf.py

+# -*- coding: utf-8 -*-
+#
+# Cython documentation build configuration file, created by
+# sphinx-quickstart on Fri Apr 25 12:49:32 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Cython'
+copyright = '2008, Stefan Behnel, Robert Bradshaw, William Stein, Gary Furnish, Dag Seljebotn, Gabriel Gellner, Greg Ewing'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.9.6'
+# The full version, including alpha/beta/rc tags.
+release = '0.9.6.13.1'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Cythondoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+#_stdauthor = r'Greg Ewig\\ Gabriel Gellner, editor'
+_stdauthor = r'Stefan Behnel, Robert Bradshaw, William Stein\\ Gary Furnish, Dag Seljebotn, Greg Ewing\\ Gabriel Gellner, editor'
+latex_documents = [
+    ('index', 'cython.tex', 
+     'Cython Manual', _stdauthor, 'manual')
+]
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

docs/early_binding_for_speed.rst

+.. _early-binding-speed-label:
+
+Early Binding for Speed
+=======================
+
+As a dynamic language, Python encourages a programming style of considering
+classes and objects in terms of their methods and attributes, more than where
+they fit into the class hierarchy.
+
+This can make Python a very relaxed and comfortable language for rapid
+development, but with a price - the 'red tape' of managing data types is
+dumped onto the interpreter. At run time, the interpreter does a lot of work
+searching namespaces, fetching attributes and parsing argument and keyword
+tuples. This run-time 'late binding' is a major cause of Python's relative
+slowness compared to 'early binding' languages such as C++.
+
+However with Cython it is possible to gain significant speed-ups through the
+use of 'early binding' programming techniques.
+
+For example, consider the following (silly) code example::
+
+    cdef class Rectangle:
+        cdef int x0, y0
+        cdef int x1, y1
+        def __init__(self, int x0, int y0, int x1, int y1):
+            self.x0 = x0; self.y0 = y0; self.x1 = x1; self.y1 = y1
+        def area(self):
+            area = (self.x1 - self.x0) * (self.y1 - self.y0)
+            if area < 0:
+                area = -area
+            return area
+
+    def rectArea(x0, y0, x1, y1):
+        rect = Rectangle(x0, y0, x1, y1)
+        return rect.area()
+
+In the :func:`rectArea` method, the call to :meth:`rect.area` and the
+:meth:`.area` method contain a lot of Python overhead.
+
+However, in Cython, it is possible to eliminate a lot of this overhead in cases
+where calls occur within Cython code. For example::
+
+    cdef class Rectangle:
+        cdef int x0, y0
+        cdef int x1, y1
+        def __init__(self, int x0, int y0, int x1, int y1):
+            self.x0 = x0; self.y0 = y0; self.x1 = x1; self.y1 = y1
+        cdef int _area(self):
+            int area
+            area = (self.x1 - self.x0) * (self.y1 - self.y0)
+            if area < 0:
+                area = -area
+            return area
+        def area(self):
+            return self._area()
+
+    def rectArea(x0, y0, x1, y1):
+        cdef Rectangle rect
+        rect = Rectangle(x0, y0, x1, y1)
+        return rect._area()
+
+Here, in the Rectangle extension class, we have defined two different area
+calculation methods, the efficient :meth:`_area` C method, and the
+Python-callable :meth:`area` method which serves as a thin wrapper around
+:meth:`_area`. Note also in the function :func:`rectArea` how we 'early bind'
+by declaring the local variable ``rect`` which is explicitly given the type
+Rectangle. By using this declaration, instead of just dynamically assigning to
+``rect``, we gain the ability to access the much more efficient C-callable
+:meth:`_rect` method.
+
+But Cython offers us more simplicity again, by allowing us to declare
+dual-access methods - methods that can be efficiently called at C level, but
+can also be accessed from pure Python code at the cost of the Python access
+overheads. Consider this code::
+
+    cdef class Rectangle:
+        cdef int x0, y0
+        cdef int x1, y1
+        def __init__(self, int x0, int y0, int x1, int y1):
+            self.x0 = x0; self.y0 = y0; self.x1 = x1; self.y1 = y1
+        cpdef int area(self):
+            int area
+            area = (self.x1 - self.x0) * (self.y1 - self.y0)
+            if area < 0:
+                area = -area
+            return area
+
+    def rectArea(x0, y0, x1, y1):
+        cdef Rectangle rect
+        rect = Rectangle(x0, y0, x1, y1)
+        return rect.area()
+
+.. note:: 
+
+    in earlier versions of Cython, the :keyword:`cpdef` keyword is
+    :keyword:`rdef` - but has the same effect).
+
+Here, we just have a single area method, declared as :keyword:`cpdef` to make it
+efficiently callable as a C function, but still accessible from pure Python
+(or late-binding Cython) code.
+
+If within Cython code, we have a variable already 'early-bound' (ie, declared
+explicitly as type Rectangle, (or cast to type Rectangle), then invoking its
+area method will use the efficient C code path and skip the Python overhead.
+But if in Pyrex or regular Python code we have a regular object variable
+storing a Rectangle object, then invoking the area method will require:
+
+* an attribute lookup for the area method
+* packing a tuple for arguments and a dict for keywords (both empty in this case)
+* using the Python API to call the method 
+
+and within the area method itself:
+
+* parsing the tuple and keywords
+* executing the calculation code
+* converting the result to a python object and returning it 
+
+So within Cython, it is possible to achieve massive optimisations by
+using strong typing in declaration and casting of variables. For tight loops
+which use method calls, and where these methods are pure C, the difference can
+be huge.
+

docs/limitations.rst

+.. _cython-limitations-label:
+
+Limitations
+===========
+
+Unsupported Python features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Cython is not quite a full superset of Python. The following restrictions apply:
+
+* Function definitions (whether using ``def`` or ``cdef``) cannot be nested within
+  other function definitions.  
+* Class definitions can only appear at the top level of a module, 
+  not inside a function.
+* The ``import *`` form of import is not allowed anywhere (other forms of the
+  import statement are fine, though).  
+* Generators cannot be defined in Cython.
+* The ``globals()`` and ``locals()`` functions cannot be used.
+
+The above restrictions will most likely remain, since removing them would be
+difficult and they're not really needed for Cython's intended applications.
+
+There are also some temporary limitations, which may eventually be lifted, including:
+
+* Class and function definitions cannot be placed inside control structures.
+* There is no support for Unicode.
+* Special methods of extension types cannot have functioning docstrings.
+* The use of string literals as comments is not recommended at present,
+  because Cython doesn't optimize them away, and won't even accept them in places
+  where executable statements are not allowed.
+
+Semantic differences between Python and Cython
+----------------------------------------------
+
+Behaviour of class scopes
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Python, referring to a method of a class inside the class definition, i.e.
+while the class is being defined, yields a plain function object, but in
+Cython it yields an unbound method [#]_. A consequence of this is that the
+usual idiom for using the ``classmethod`` and ``staticmethod`` functions,
+e.g.::
+
+    class Spam:
+
+        def method(cls):
+            ...
+
+        method = classmethod(method)
+
+will not work in Cython. This can be worked around by defining the function
+outside the class, and then assigning the result of ``classmethod`` or
+``staticmethod`` inside the class, i.e.::
+
+    def Spam_method(cls):
+        ...
+
+    class Spam:
+
+        method = classmethod(Spam_method)
+
+.. rubric:: Footnotes
+
+.. [#] The reason for the different behaviour of class scopes is that
+       Cython-defined Python functions are PyCFunction objects, not PyFunction
+       objects, and are not recognised by the machinery that creates a bound
+       or unbound method when a function is extracted from a class. To get
+       around this, Cython wraps each method in an unbound method object itself
+       before storing it in the class's dictionary.

docs/overview.rst

+.. _overview-label:
+
+********
+Overview
+********
+
+A language for writing Python extension modules
+
+What is Cython all about?
+=========================
+
+Cython is a language specially designed for writing Python extension modules.
+It's designed to bridge the gap between the nice, high-level, easy-to-use
+world of Python and the messy, low-level world of C.
+
+You may be wondering why anyone would want a special language for this. Python
+is really easy to extend using C or C++, isn't it? Why not just write your
+extension modules in one of those languages?
+
+Well, if you've ever written an extension module for Python, you'll know that
+things are not as easy as all that. First of all, there is a fair bit of
+boilerplate code to write before you can even get off the ground. Then you're
+faced with the problem of converting between Python and C data types. For the
+basic types such as numbers and strings this is not too bad, but anything more
+elaborate and you're into picking Python objects apart using the Python/C API
+calls, which requires you to be meticulous about maintaining reference counts,
+checking for errors at every step and cleaning up properly if anything goes
+wrong. Any mistakes and you have a nasty crash that's very difficult to debug.
+
+Various tools have been developed to ease some of the burdens of producing
+extension code, of which perhaps SWIG is the best known. SWIG takes a
+definition file consisting of a mixture of C code and specialised
+declarations, and produces an extension module. It writes all the boilerplate
+for you, and in many cases you can use it without knowing about the Python/C
+API. But you need to use API calls if any substantial restructuring of the
+data is required between Python and C.
+
+What's more, SWIG gives you no help at all if you want to create a new
+built-in Python type. It will generate pure-Python classes which wrap (in a
+slightly unsafe manner) pointers to C data structures, but creation of true
+extension types is outside its scope.
+
+Another notable attempt at making it easier to extend Python is PyInline ,
+inspired by a similar facility for Perl. PyInline lets you embed pieces of C
+code in the midst of a Python file, and automatically extracts them and
+compiles them into an extension. But it only converts the basic types
+automatically, and as with SWIG,  it doesn't address the creation of new
+Python types.
+
+Cython aims to go far beyond what any of these previous tools provides. Cython
+deals with the basic types just as easily as SWIG, but it also lets you write
+code to convert between arbitrary Python data structures and arbitrary C data
+structures, in a simple and natural way, without knowing anything about the
+Python/C API. That's right -- nothing at all! Nor do you have to worry about
+reference counting or error checking -- it's all taken care of automatically,
+behind the scenes, just as it is in interpreted Python code. And what's more,
+Cython lets you define new built-in Python types just as easily as you can
+define new classes in Python.
+
+Sound too good to be true? Read on and find out how it's done.
+
+The Basics of Cython
+====================
+
+The fundamental nature of Cython can be summed up as follows: Cython is Python
+with C data types.
+
+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
+serve for now.) The Cython compiler will convert it into C code which makes
+equivalent calls to the Python/C API. 
+
+But Cython is much more than that, because parameters and variables can be
+declared to have C data types. Code which manipulates Python values and C
+values can be freely intermixed, with conversions occurring automatically
+wherever possible. Reference count maintenance and error checking of Python
+operations is also automatic, and the full power of Python's exception
+handling facilities, including the try-except and try-finally statements, is
+available to you -- even in the midst of manipulating C data.
+
+Here's a small example showing some of what can be done. It's a routine for
+finding prime numbers. You tell it how many primes you want, and it returns
+them as a Python list.
+
+:file:`primes.pyx`:
+
+.. code-block:: none 
+    :linenos:
+
+    def primes(int kmax):
+        cdef int n, k, i
+        cdef int p[1000]
+        result = []
+        if kmax > 1000:
+            kmax = 1000
+        k = 0
+        n = 2
+        while k < kmax:
+            i = 0
+            while i < k and n % p[i] != 0:
+                i = i + 1
+            if i == k:
+               p[k] = n
+               k = k + 1
+               result.append(n)
+            n = n + 1
+        return result
+
+You'll see that it starts out just like a normal Python function definition,
+except that the parameter ``kmax`` is declared to be of type ``int`` . This
+means that the object passed will be converted to a C integer (or a
+``TypeError.`` will be raised if it can't be).
+
+Lines 2 and 3 use the ``cdef`` statement to define some local C variables.
+Line 4 creates a Python list which will be used to return the result. You'll
+notice that this is done exactly the same way it would be in Python. Because
+the variable result hasn't been given a type, it is assumed to hold a Python
+object.
+
+Lines 7-9 set up for a loop which will test candidate numbers for primeness
+until the required number of primes has been found. Lines 11-12, which try
+dividing a candidate by all the primes found so far, are of particular
+interest. Because no Python objects are referred to, the loop is translated
+entirely into C code, and thus runs very fast.
+
+When a prime is found, lines 14-15 add it to the p array for fast access by
+the testing loop, and line 16 adds it to the result list. Again, you'll notice
+that line 16 looks very much like a Python statement, and in fact it is, with
+the twist that the C parameter ``n`` is automatically converted to a Python
+object before being passed to the append method. Finally, at line 18, a normal
+Python return statement returns the result list.
+
+Compiling primes.pyx with the Cython compiler produces an extension module
+which we can try out in the interactive interpreter as follows::
+
+    >>> import primes
+    >>> primes.primes(10)
+    [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
+
+See, it works! And if you're curious about how much work Cython has saved you,
+take a look at the C code generated for this module. 
+
+Language Details
+================
+
+For more about the Cython language, see :ref:`language-basics-label`.
+
+Future Plans
+============
+Cython is not finished. Substantial tasks remaining. See
+:ref:`cython-limitations-label` for a current list. 
+

docs/pyrex_differences.rst

+Differences between Cython and Pyrex
+====================================
+
+Package names and cross-directory imports
+-----------------------------------------
+
+Just like in python. 
+
+List Comprehensions
+-------------------
+
+`[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
+a list. Also, use the :keyword:`for` ... :keyword:`from` syntax too, e.g.::
+
+    [i*i for i from 0 <= i < 10] 
+
+In-place operators
+------------------
+
+The following is now legal::
+
+    x += 10
+       
+for all single-character operators, for both python and :keyword:`cdef` variables. Side
+effects behave properly, i.e. for::
+
+    L[foo()] += bar()
+
+:func:`foo` is called exactly once, before :func:`bar`. 
+
+Conditional expressions "x if b else y" (python 2.5)
+----------------------------------------------------
+
+Conditional expressions as described in
+http://www.python.org/dev/peps/pep-0308/::
+
+    X if C else Y
+       
+Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). 
+
+cdef 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.::
+
+    cdef inline int something_fast(int a, int b):
+        return a*a + b
+       
+Note that class-level :keyword:`cdef` functions are handled via a virtual
+function table, so the compiler won't be able to inline them in almost all
+cases. 
+
+Assignment on declaration (e.g. "cdef int spam = 5")
+----------------------------------------------------
+
+In Pyrex, one must write::
+
+    cdef int i, j, k
+    i = 2
+    j = 5
+    k = 7
+    
+Now, with cython, one can write::
+
+    cdef int i = 2, j = 5, k = 7
+    
+The expression on the right hand side can be arbitrarily complicated, e.g.::
+
+    cdef int n = python_call(foo(x,y), a + b + c) - 32
+       
+
+'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2")
+----------------------------------------------------------------
+    
+::
+
+    for i from 0 <= i < 10 by 2:
+        print i
+       
+
+yields::
+
+    0
+    2
+    4
+    6
+    8
+       
+
+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
+truth value (using the :meth:`__nonzero__` method, but the canonical choices
+are the two boolean objects ``True`` and ``False``. The :keyword:`bint` of
+"boolean int" object is compiled to a C int, but get coerced to and from
+Cython as booleans. The return type of comparisons and several builtins is a
+:ctype:`bint` as well. This allows one to avoid having to wrap things in
+:func:`bool()`. For example, one can write::
+
+    def is_equal(x):
+        return x == y
+
+which would return ``1`` or ``0`` in Pyrex, but returns ``True`` or ``False`` in
+python. One can declare variables and return values for functions to be of the
+:ctype:`bint` type.  For example::
+
+    cdef int i = x
+    Cdef bint b = x
+
+The first conversion would happen via ``x.__int__()`` whereas the second would
+happen via ``x.__nonzero__()``. (Actually, if ``x`` is the python object
+``True`` or ``False`` then no method call is made.) 
+
+Executable class bodies
+-----------------------
+
+Including a working :func:`classmethod`::
+
+    cdef class Blah:
+        def some_method(self):
+            print self
+        some_method = classmethod(some_method)
+        a = 2*3
+        print "hi", a
+        
+cpdef functions
+---------------
+
+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
+from and overridden by both extension and normal python subclasses. You can
+essentially think of a :keyword:`cpdef` method as a :keyword:`cdef` method +
+some extras. (That's how it's implemented at least.) First, it creates a
+:keyword:`def` method that does nothing but call the underlying
+:keyword:`cdef` method (and does argument unpacking/coercion if needed). At
+the top of the :keyword:`cdef` method a little bit of code is added to check
+to see if it's overridden.  Specifically, in pseudocode::
+
+    if type(self) has a __dict__:
+        foo = self.getattr('foo')
+        if foo is not wrapper_foo:
+            return foo(args)
+    [cdef method body]
+
+To detect whether or not a type has a dictionary, it just checks the
+tp_dictoffset slot, which is ``NULL`` (by default) for extension types, but
+non- null for instance classes. If the dictionary exists, it does a single
+attribute lookup and can tell (by comparing pointers) whether or not the
+returned result is actually a new function. If, and only if, it is a new
+function, then the arguments packed into a tuple and the method called. This
+is all very fast. A flag is set so this lookup does not occur if one calls the
+method on the class directly, e.g.::
+
+    cdef class A:
+        cpdef foo(self):
+        pass
+
+    x = A()
+    x.foo()  # will check to see if overridden
+    A.foo(x) # will call A's implementation whether overridden or not
+
+See :ref:`early-binding-speed-label` for explanation and usage tips. 
+
+.. _automatic-range-conversion:
+
+(Optional) automatic range conversion
+-------------------------------------
+
+::
+
+    $cython --convert-range
+       
+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
+of step) can be determined. 
+
+.. warning:: 
+
+    This may change the semantics if the range causes
+    assignment to ``i`` to overflow. Specifically, if this option is set, an error
+    will be raised before the loop is entered, whereas without this option the loop
+    will execute until a overflowing value is encountered. 
+
+More friendly type casting
+--------------------------
+
+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``
+is a C int, one will get an "object" at location ``i`` in memory. This leads
+to confusing results and segfaults.
+
+In Cython ``<type>x`` will try and do a coercion (as would happen on assignment of
+``x`` to a variable of type type) if exactly one of the types is a python object.
+It does not stop one from casting where there is no conversion (though it will
+emit a warning). If one really wants the address, cast to a ``void *`` first.
+
+As in Pyrex ``<MyExtensionType>x`` will cast ``x`` to type <ctype>`MyExtensionType` without any
+type checking. Cython supports the syntax ``<MyExtensionType?>`` to do the cast
+with type checking (i.e. it will throw an error if ``x`` is not a (subclass of)
+<ctype>`MyExtensionType`. 
+
+Optional arguments in cdef/cpdef functions
+------------------------------------------
+
+Cython now supports optional arguments for :keyword:`cdef` and
+:keyword:`cpdef` functions.
+
+The syntax in the ``.pyx`` file remains as in Python, but one declares such
+functions in the ``.pxd`` file by writing ``cdef foo(x=*)``. The number of
+arguments may increase on subclassing, but the argument types and order must
+remain the same. There is a slight performance penalty in some cases when a
+cdef/cpdef function without any optional is overridden with one that does have
+default argument values. 
+
+For example, one can have the ``.pxd`` file::
+
+    cdef class A:
+        cdef foo(self)
+    cdef class B(A)
+        cdef foo(self, x=*)
+    cdef class C(B):
+        cpdef foo(self, x=*, int k=*)
+
+with corresponding ``.pyx`` file::
+
+    cdef class A:
+        cdef foo(self):
+            print "A"
+    cdef class B(A)
+        cdef foo(self, x=None)
+            print "B", x
+    cdef class C(B):
+        cpdef foo(self, x=True, int k=3)
+            print "C", x, k
+
+.. note:: 
+
+    this also demonstrates how :keyword:`cpdef` functions can override
+    :keyword:`cdef` functions.
+
+Function pointers in structs
+----------------------------
+
+Functions declared in :keyword:`structs` are automatically converted to
+function pointers for convenience.
+
+C++ Exception handling
+----------------------
+
+:keyword:`cdef` functions can now be declared as::
+
+    cdef int foo(...) except +
+    cdef int foo(...) except +TypeError
+    cdef int foo(...) except +python_error_raising_function
+
+in which case a Python exception will be raised when a C++ error is caught.
+See :ref:`wrapping-cplusplus-label` for more details.
+
+Synonyms
+--------
+
+``cdef import from`` means the same thing as ``cdef extern from``
+
+Source code encoding
+--------------------
+
+-- TODO: add the links to the relevent PEPs
+
+Cython supports PEP 3120 and PEP 263, i.e. you can start your Cython source
+file with an encoding comment and generally write your source code in UTF-8.
+This impacts the encoding of byte strings and the conversion of unicode string
+literals like ``u'abcd'`` to unicode objects.
+

docs/sharing_declarations.rst

+.. _sharing-declarations-label:
+
+Sharing Declarations Between Cython Modules
+===========================================
+
+This section describes a new set of facilities for making C declarations,
+functions and extension types in one Cython module available for use in
+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.
+
+Definition and Implementation files
+-----------------------------------
+
+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
+modules, and an implementation file with a ``.pyx`` suffix, containing
+everything else. When a module wants to use something declared in another
+module's definition file, it imports it using the :keyword:`cimport`
+statement.  What a Definition File contains A definition file can contain:
+
+* Any kind of C type declaration.
+* extern C function or variable declarations.
+* Declarations of C functions defined in the module.
+* The definition part of an extension type (see below).
+
+It cannot contain any non-extern C variable declarations.
+
+It cannot contain the implementations of any C or Python functions, or any
+Python class definitions, or any executable statements.
+
+.. note::
+
+    You don't need to (and shouldn't) declare anything in a declaration file
+    public in order to make it available to other Cython modules; its mere
+    presence in a definition file does that. You only need a public
+    declaration if you want to make something available to external C code.
+
+What an Implementation File contains
+------------------------------------
+
+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
+corresponding definition file also defines that type (see below). 
+
+The cimport statement
+---------------------
+
+The :keyword:`cimport` statement is used in a definition or
+implementation file to gain access to names declared in another definition
+file. Its syntax exactly parallels that of the normal Python import
+statement::
+
+    cimport module [, module...]
+
+    from module cimport name [as name] [, name [as name] ...]
+
+Here is an example. The file on the left is a definition file which exports a
+C data type. The file on the right is an implementation file which imports and
+uses it.
+ 
+:file:`dishes.pxd`::
+
+   cdef enum otherstuff:       
+       sausage, eggs, lettuce  
+                               
+   cdef struct spamdish:       
+       int oz_of_spam          
+       otherstuff filler       
+                               
+:file:`restaurant.pyx`::
+
+    cimport dishes
+    from dishes cimport spamdish
+
+    cdef void prepare(spamdish *d):
+        d.oz_of_spam = 42
+        d.filler = dishes.sausage
+
+    def serve():
+        spamdish d
+        prepare(&d)
+        print "%d oz spam, filler no. %d" % (d->oz_of_spam, d->otherstuff)
+                               
+It is important to understand that the :keyword:`cimport` statement can only
+be used to import C data types, C functions and variables, and extension
+types. It cannot be used to import any Python objects, and (with one
+exception) it doesn't imply any Python import at run time. If you want to
+refer to any Python names from a module that you have cimported, you will have
+to include a regular import statement for it as well.
+
+The exception is that when you use :keyword:`cimport` to import an extension type, its
+type object is imported at run time and made available by the name under which
+you imported it. Using :keyword:`cimport` to import extension types is covered in more
+detail below.  
+
+Search paths for definition files 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you :keyword:`cimport` a module called ``modulename``, the Cython
+compiler searches for a file called :file:`modulename.pxd` along the search
+path for include files, as specified by ``-I`` command line options.
+
+Also, whenever you compile a file :file:`modulename.pyx`, the corresponding
+definition file :file:`modulename.pxd` is first searched for along the same
+path, and if found, it is processed before processing the ``.pyx`` file.  
+
+Using cimport to resolve naming conflicts 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :keyword:`cimport` mechanism provides a clean and simple way to solve the
+problem of wrapping external C functions with Python functions of the same
+name. All you need to do is put the extern C declarations into a ``.pxd`` file
+for an imaginary module, and :keyword:`cimport` that module. You can then
+refer to the C functions by qualifying them with the name of the module.
+Here's an example:
+ 
+:file:`c_lunch.pxd` ::
+
+    cdef extern from "lunch.h":
+        void eject_tomato(float) 	
+
+:file:`lunch.pyx` ::
+
+    cimport c_lunch
+
+    def eject_tomato(float speed):
+        c_lunch.eject_tomato(speed)
+
+You don't need any :file:`c_lunch.pyx` file, because the only things defined
+in :file:`c_lunch.pxd` are extern C entities. There won't be any actual
+``c_lunch`` module at run time, but that doesn't matter; the
+:file:`c_lunch.pxd` file has done its job of providing an additional namespace
+at compile time.  
+
+Sharing C Functions
+===================
+
+C functions defined at the top level of a module can be made available via
+:keyword:`cimport` by putting headers for them in the ``.pxd`` file, for
+example,:
+
+:file:`volume.pxd`:
+
+:file:`spammery.pyx`::
+
+    cdef float cube(float)
+
+    from volume cimport cube
+
+    def menu(description, size):
+        print description, ":", cube(size), \
+            "cubic metres of spam"
+
+    menu("Entree", 1)
+    menu("Main course", 3)
+    menu("Dessert", 2)
+
+:file:`volume.pyx`::
+
+    cdef float cube(float x):
+        return x * x * x
+
+.. note::
+
+    When a module exports a C function in this way, an object appears in the
+    module dictionary under the function's name. However, you can't make use of
+    this object from Python, nor can you use it from Cython using a normal import
+    statement; you have to use :keyword:`cimport`.  
+
+Sharing Extension Types 
+=======================
+
+An extension type can be made available via :keyword:`cimport` by splitting
+its definition into two parts, one in a definition file and the other in the
+corresponding implementation file.
+
+The definition part of the extension type can only declare C attributes and C
+methods, not Python methods, and it must declare all of that type's C
+attributes and C methods.
+
+The implementation part must implement all of the C methods declared in the
+definition part, and may not add any further C attributes. It may also define
+Python methods.
+
+Here is an example of a module which defines and exports an extension type,
+and another module which uses it.::
+ 
+    Shrubbing.pxd 	Shrubbing.pyx
+    cdef class Shrubbery:
+        cdef int width
+        cdef int length 	cdef class Shrubbery:
+        def __new__(self, int w, int l):
+            self.width = w
+            self.length = l
+
+    def standard_shrubbery():
+        return Shrubbery(3, 7)
+    Landscaping.pyx
+    cimport Shrubbing
+    import Shrubbing
+
+    cdef Shrubbing.Shrubbery sh
+    sh = Shrubbing.standard_shrubbery()
+    print "Shrubbery size is %d x %d" % (sh.width, sh.height)
+ 
+Some things to note about this example:
+
+* There is a :keyword:`cdef` class Shrubbery declaration in both
+  :file:`Shrubbing.pxd` and :file:`Shrubbing.pyx`. When the Shrubbing module
+  is compiled, these two declarations are combined into one.
+* In Landscaping.pyx, the :keyword:`cimport` Shrubbing declaration allows us
+  to refer to the Shrubbery type as :class:`Shrubbing.Shrubbery`. But it
+  doesn't bind the name Shrubbing in Landscaping's module namespace at run
+  time, so to access :func:`Shrubbing.standard_shrubbery` we also need to
+  ``import Shrubbing``.
+

docs/source_files_and_compilation.rst

+.. TODO: Rewrite this to be more comprehensive, with examples!
+
+****************************
+Source Files and Compilation
+****************************
+
+Cython source file names consist of the name of the module followed by a
+``.pyx`` extension, for example a module called primes would have a source
+file named :file:`primes.pyx`.
+
+If your module is destined to live in a package, the source file name should
+include the full dotted name that the module will eventually have. For
+example, a module called primes that will be installed in a package called
+numbers should have a source file called numbers.primes.pyx. This will ensure
+that the :attr:`__name__` properties of the module and any classes defined in
+it are set correctly. If you don't do this, you may find that pickling doesn't
+work, among other problems. It also ensures that the Cython compiler has the
+right idea about the layout of the module namespace, which can be important
+when accessing extension types defined in other modules.
+
+Once you have written your ``.pyx`` file, there are a couple of ways of turning it
+into an extension module. One way is to compile it manually with the Cython
+compiler, e.g.::
+
+    $ cython primes.pyx
+
+This will produce a file called :file:`primes.c`, which then needs to be
+compiled with the C compiler using whatever options are appropriate on your
+platform for generating an extension module. There's a Makefile in the Demos
+directory (called Makefile.nodistutils) that shows how to do this for Linux.
+
+The other, and probably better, way is to use the :mod:`distutils` extension
+provided with Cython. See the :file:`setup.py` file in the Demos directory for an
+example of how to use it. This method has the advantage of being
+cross-platform -- the same setup file should work on any platform where
+:mod:`distutils` can compile an
+extension module.

docs/wrapping_CPlusPlus.rst

+.. _wrapping-cplusplus-label:
+
+Wrapping C++
+============
+
+TODO

index.rst

+.. 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!
+================================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   docs/overview
+   docs/language_basics
+   docs/extension_types
+   docs/sharing_declarations
+   docs/external_C_code
+   docs/wrapping_CPlusPlus
+   docs/source_files_and_compilation
+   docs/limitations
+   docs/pyrex_differences
+   docs/early_binding_for_speed
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. toctree::
+