From cbc541497fd831ea92919cf072ef76a08ce1a42a Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Sun, 4 Oct 2009 07:35:43 -0400 Subject: [PATCH] merged with Minh, and continued with language basics. --- conf.py | 5 +- index.rst | 10 ++ src/reference/overview.rst => overview.rst | 33 +++- src/reference/compilation.rst | 4 - src/reference/extension_types.rst | 3 - src/reference/index.rst | 7 +- src/reference/interfacing_with_other_code.rst | 3 - src/reference/language_basics.rst | 156 ++++++++++++++---- src/reference/limitations.rst | 2 - src/reference/special_mention.rst | 3 - src/tutorial/index.rst | 2 +- 11 files changed, 170 insertions(+), 58 deletions(-) rename src/reference/overview.rst => overview.rst (91%) diff --git a/conf.py b/conf.py index b5047ebd..ef34a070 100644 --- a/conf.py +++ b/conf.py @@ -29,7 +29,7 @@ import cython_highlighting # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['ipython_console_highlighting', 'cython_highlighting'] +extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -157,3 +157,6 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +# todo +todo_include_todos = True diff --git a/index.rst b/index.rst index a67db73d..83e6c3ce 100644 --- a/index.rst +++ b/index.rst @@ -7,5 +7,15 @@ Contents: .. toctree:: :maxdepth: 1 + overview src/reference/index src/tutorial/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/overview.rst b/overview.rst similarity index 91% rename from src/reference/overview.rst rename to overview.rst index 78a3f99e..a00e8ed6 100644 --- a/src/reference/overview.rst +++ b/overview.rst @@ -6,9 +6,6 @@ Overview ******** -.. contents:: - :local: - =============== What is Cython? =============== @@ -41,9 +38,11 @@ Tell Me More! The Python language is well known. The primary Python execution environment is commonly referred to as CPython, as it is written in -C. Other major implementations use Java (Jython -[#Jython]_), C# (IronPython [#IronPython]_) and Python -itself (PyPy [#PyPy]_). +C. Other major implementations use: + +:Java: Jython [#Jython]_ +:C#: IronPython [#IronPython]_) +:Python itself: PyPy [#PyPy]_ Written in C, CPython has been conducive to wrapping many external libraries that interface through the C language. It has, however, remained non trivial to write the necessary glue code in @@ -83,6 +82,18 @@ Where Do I Get It? Well.. at `cython.org `_.. of course! + +How Do I Report a Bug? +====================== + +I Want To Make A Feature Request! +================================= + +How Can I Contact You? +======================= + + + .. rubric:: Footnotes .. [#Jython] **Jython:** \J. Huginin, B. Warsaw, F. Bock, et al., Jython: Python for the Java platform, http://www.jython.org/ @@ -96,3 +107,13 @@ Well.. at `cython.org `_.. of course! + + + + + + + + + + diff --git a/src/reference/compilation.rst b/src/reference/compilation.rst index 3c85fa8c..981d88e5 100644 --- a/src/reference/compilation.rst +++ b/src/reference/compilation.rst @@ -10,10 +10,6 @@ Compilation There are several ways to compile cython code. -.. contents:: - :local: - - ===================== From the Command Line ===================== diff --git a/src/reference/extension_types.rst b/src/reference/extension_types.rst index 0e50beb0..b69be066 100644 --- a/src/reference/extension_types.rst +++ b/src/reference/extension_types.rst @@ -6,9 +6,6 @@ Extention Types *************** -.. contents:: - :local: - ========== Attributes ========== diff --git a/src/reference/index.rst b/src/reference/index.rst index 5943f509..d181b100 100644 --- a/src/reference/index.rst +++ b/src/reference/index.rst @@ -1,12 +1,15 @@ Reference Guide =============== +.. note:: + .. todo:: + Most of the **boldface** is to be changed to refs or other markup later. + Contents: .. toctree:: :maxdepth: 2 - overview language_basics compilation extension_types @@ -15,7 +18,7 @@ Contents: limitations Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/src/reference/interfacing_with_other_code.rst b/src/reference/interfacing_with_other_code.rst index b3176df9..73e2fb8b 100644 --- a/src/reference/interfacing_with_other_code.rst +++ b/src/reference/interfacing_with_other_code.rst @@ -6,9 +6,6 @@ Interfacing with Other Code *************************** -.. contents:: - :local: - == C == diff --git a/src/reference/language_basics.rst b/src/reference/language_basics.rst index 9a3ca493..9e1040e0 100644 --- a/src/reference/language_basics.rst +++ b/src/reference/language_basics.rst @@ -4,21 +4,14 @@ .. _language_basics: -**************** -Languange Basics -**************** - -.. contents:: - :depth: 2 - :local: +*************** +Language Basics +*************** ================= Cython File Types ================= -.. contents:: - :local: - There are three file types in cython: * Definition files carry a ``.pxd`` suffix @@ -104,16 +97,13 @@ How do I use it? * The included code can itself contain other ``include`` statements. -=========== -Data Typing -=========== +==================== +Declaring Data Types +==================== -.. contents:: - :local: - -.. - I think having paragraphs like this should only be in the tutorial which - we can link to from here +.. note:: + .. todo:: + I think having paragraphs like this should be somewhere else 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. @@ -185,8 +175,8 @@ The ``cdef`` statement is used to make C level declarations for: tons_of_spam = 3 -Grouping -======== +Grouping cdef Declarations +========================== A series of declarations can grouped into a ``cdef`` block:: @@ -201,21 +191,124 @@ A series of declarations can grouped into a ``cdef`` block:: 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. +* Both C and Python **function** types can be declared to have parameters C data types. +* Use normal C declaration syntax:: + + def spam(int i, char *s): + ... + + cdef int eggs(unsigned long l, float f): + ... + +* As these parameters are passed into a Python declared function, they are magically **converted** to the specified C type value. + + * This holds true for only numeric and string types + +.. todo:: + The previous statement is still true ..?? + +* If no type is specified for a parameter or a return value, it is assumed to be a Python object + + * The following takes two Python objects as parameters and returns a Python object:: + + cdef spamobjs(x, y): + ... + + * .. note:: + This is different then C language behavior, where it is an int by default. + + + +* Python object types have reference counting performed according to the standard Python C-API rules: + + * Borrowed references are taken as parameters + * New references are returned + +.. todo:: + link or label here the one ref count caveat for numpy. + +* The name ``object`` can be used to explicitly declare something as a Python Object. + + * For sake of code clarity, it recomened to always use ``object`` explicitly in your code. + + * This is also useful for cases where the name being declared would otherwise be taken for a type:: + + cdef foo(object int): + ... + + * As a return type:: + + cdef object foo(object int): + ... + +.. todo:: + Do a see also here ..?? + + +Automatic Type Conversion +========================= + +* For basic numeric and string types, in most situations, when a Python object is used in the context of a C value and vice versa. + +* The following table summarises the conversion possibilities: + + +----------------------------+--------------------+------------------+ + | C types | From Python types | To Python types | + +============================+====================+==================+ + | [unsigned] char | int, long | int | + +----------------------------+ | | + | [unsigned] short | | | + +----------------------------+ | | + | int, long | | | + +----------------------------+--------------------+------------------+ + | unsigned int | int, long | long | + +----------------------------+ | | + | unsigned long | | | + +----------------------------+ | | + | [unsigned] long long | | | + +----------------------------+--------------------+------------------+ + | float, double, long double | int, long, float | float | + +----------------------------+--------------------+------------------+ + | char * | str/bytes | str/bytes [#]_ | + +----------------------------+--------------------+------------------+ + | struct | | dict | + +----------------------------+--------------------+------------------+ + + +.. [#] The conversion is to/from str for Python 2.x, and bytes for Python 3.x. + + +.. note:: + **Python String in a C Context** + + * A Python string, passed to C context expecting a ``char*``, is only valid as long as the Python string exists. + * A reference to the Python string must be kept around for as long as the C string is needed. + * If this can't be guarenteed, then make a copy of the C string. + * Cython may produce an error message: ``Obtaining char* from a temporary Python value`` and will not resume compiling in situations like this:: + + cdef char *s + s = pystring1 + pystring2 + + * The reason is that concatenating to strings in Python produces a temporary variable. + + * The variable is decrefed, and the Python string deallocated as soon as the statement has finished, + + * Therefore the lvalue **``s``** is left dangling. + + * The solution is to assign the result of the concatenation to a Python variable, and then obtain the ``char*`` from that:: + + cdef char *s + p = pystring1 + pystring2 + s = p + + .. note:: + **It is up to you to be aware of this, and not to depend on Cython's error message, as it is not guarenteed to be generated for every situation.** - * 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 -========== Casting ======= @@ -232,9 +325,6 @@ Statements and Expressions Functions ========= -.. contents:: - :local: - Callable from Python ===================== diff --git a/src/reference/limitations.rst b/src/reference/limitations.rst index b1aded75..a4a3ff0e 100644 --- a/src/reference/limitations.rst +++ b/src/reference/limitations.rst @@ -6,5 +6,3 @@ Limitations *********** -.. contents:: - :local: diff --git a/src/reference/special_mention.rst b/src/reference/special_mention.rst index eaf28751..0b40771c 100644 --- a/src/reference/special_mention.rst +++ b/src/reference/special_mention.rst @@ -6,6 +6,3 @@ *************** Special Mention *************** - -.. contents:: - :local: diff --git a/src/tutorial/index.rst b/src/tutorial/index.rst index 7dba1dc2..a7cb6c0e 100644 --- a/src/tutorial/index.rst +++ b/src/tutorial/index.rst @@ -25,7 +25,7 @@ Contents: Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` -- 2.26.2