From: Peter Alexander Date: Thu, 1 Oct 2009 13:59:31 +0000 (-0400) Subject: languge basics outline X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=71e547b021f2650400d0e08b3e462dfa250966d0;p=cython.git languge basics outline --- diff --git a/NOTES b/NOTES deleted file mode 100644 index 8b137891..00000000 --- a/NOTES +++ /dev/null @@ -1 +0,0 @@ - diff --git a/README b/README index ce358bff..fa4603fb 100644 --- a/README +++ b/README @@ -1,21 +1,14 @@ 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 diff --git a/TODO b/TODO index cb18f2fc..e69de29b 100644 --- a/TODO +++ b/TODO @@ -1,10 +0,0 @@ -* 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. - diff --git a/index.rst b/index.rst index 2ba2a5d4..c5186638 100644 --- a/index.rst +++ b/index.rst @@ -1,6 +1,6 @@ -Welcome to Cython's Users Guide -================================= +Welcome to Cython's Reference Guide +=================================== Contents: diff --git a/src/language_basics.rst b/src/language_basics.rst index 57b4e2be..9a3ca493 100644 --- a/src/language_basics.rst +++ b/src/language_basics.rst @@ -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 =========================