Commit 71e547b0 authored by Peter Alexander's avatar Peter Alexander

languge basics outline

parent 16ea4ffd
Cython's entire documentation suite is currently being overhauled.
For the time being, I will use this page to post notes to both myself and to any interested parties that come to view my progress.
For the time being, I'll use this page to post notes.
The prvious Cython documentation files are hosted at http://hg.cython.org/cython-docs
The previous Cython documentation files are hosted at http://hg.cython.org/cython-docs
For my vistors
===============
1) This is creative process not necessarily a predetermined blueprint of what I may have in mind.
2) It's also an iterative process.
3) All constructive thoughts, visions, and criticisms most welcome.. :)
For me :)
=========
Notes
=======
1) Some css work should definately be done.
2) Use local 'top-of-page' contents rather than the sidebar, imo.
3) Provide a link from each (sub)section to the TOC of the page.
4) Temporarily using bold emphisis everywhere to signify special markup to be addressed later.
\ No newline at end of file
4) Fix cython highlighter for cdef blocks
* Make a Pygments lexer for cython/pyrex so we get nice color coding. [Partially Done]
* Fix up the latex style file so that boxes are not messed up when we have
code examples.
* Put on my writing hat, and do an overhaul of the structure of the docs so
that it is faster to navigate. I will be using the python doc structure as a
reference.
* Get some simple howto's written.
* Thinking if there is an easy way to test the cython code in the docs so that
I can ensure accuracy.
Welcome to Cython's Users Guide
=================================
Welcome to Cython's Reference Guide
===================================
Contents:
......
......@@ -16,14 +16,15 @@ Languange Basics
Cython File Types
=================
.. contents::
:local:
There are three file types in cython:
* Definition files carry a `.pxd` suffix
* Implementation files carry a `.pyx` suffix
* Include files which carry a `.pxi` suffix
* Definition files carry a ``.pxd`` suffix
* Implementation files carry a ``.pyx`` suffix
* Include files which carry a ``.pxi`` suffix
.. contents::
:local:
Definition File
===============
......@@ -32,7 +33,7 @@ What can it contain?
--------------------
* Any kind of C type declaration.
* `extern` C function or variable decarations.
* ``extern`` C function or variable decarations.
* Declarations for module implementations.
* The definition parts of **extension types**.
* All declarations of functions, etc., for an **external library**
......@@ -57,15 +58,15 @@ cimport
* Use the **cimport** statement, as you would Python's import statement, to access these files
from other definition or implementation files.
* **cimport** does not need to be called in `.pyx` file for for `.pxd` file that has the
* **cimport** does not need to be called in ``.pyx`` file for for ``.pxd`` file that has the
same name. This is automatic.
* For cimport to find the stated definition file, the path to the file must be appended to the
`-I` option of the **cython compile command**.
``-I`` option of the **cython compile command**.
compilation order
`````````````````
* When a `.pyx` file is to be compiled, cython first checks to see if a corresponding `.pxd` file
* When a ``.pyx`` file is to be compiled, cython first checks to see if a corresponding ``.pxd`` file
exits and processes it first.
......@@ -92,15 +93,15 @@ What can it contain?
--------------------
* Any Cythonic code really, because the entire file is textually embedded at the location
you prescribe. Think.. "C pre-processor".
you prescribe.
How do I use it?
----------------
* Include the `.pxi` file with an `include` statement like: `include "spamstuff.pxi`
* The `include` statement can appear anywhere in your cython file and at any indentation level
* The code in the `.pxi` file needs to be rooted at the "zero" indentation level.
* The included code can itself contain other `include` statements.
* Include the ``.pxi`` file with an ``include`` statement like: ``include "spamstuff.pxi``
* The ``include`` statement can appear anywhere in your cython file and at any indentation level
* The code in the ``.pxi`` file needs to be rooted at the "zero" indentation level.
* The included code can itself contain other ``include`` statements.
===========
......@@ -110,12 +111,109 @@ Data Typing
.. contents::
:local:
..
I think having paragraphs like this should only be in the tutorial which
we can link to from here
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.
The cdef Statement
==================
The ``cdef`` statement is used to make C level declarations for:
:Variables:
::
cdef int i, j, k
cdef float f, g[42], *h
:Structs:
::
cdef struct Grail:
int age
float volume
:Unions:
::
cdef union Food:
char *spam
float *eggs
:Enums:
::
cdef enum CheeseType:
cheddar, edam,
camembert
cdef enum CheeseState:
hard = 1
soft = 2
runny = 3
:Funtions:
::
cdef int eggs(unsigned long l, float f):
...
:Extenstion Types:
::
cdef class Spam:
...
.. note::
Constants can be defined by using an anonymous enum::
cdef enum:
tons_of_spam = 3
Grouping
========
A series of declarations can grouped into a ``cdef`` block::
cdef:
struct Spam:
int tons
int i
float f
Spam *p
void f(Spam *s):
print s.tons, "Tons of spam"
Parameters
==========
* All the different **function** types can be declared to have C data types.
* Use normal C declaration syntax.
* **Python callable functions** can also be declared with C data types.
* As these parameters are passed into the Python function, they magically **convert** to
the specified C typed value.
* See also... **link the various areas that detail this**
Conversion
==========
......@@ -155,6 +253,7 @@ Error and Exception Handling
Conditional Compilation
=======================
Compile-Time Definitions
=========================
......
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