From: Peter Alexander Date: Mon, 5 Oct 2009 18:40:36 +0000 (-0400) Subject: bulk of language basics transformed X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=3d1e83f94d0f80b86c8dfe5c0011785bfbe67594;p=cython.git bulk of language basics transformed --- diff --git a/src/reference/language_basics.rst b/src/reference/language_basics.rst index 00475ee6..45cd2fac 100644 --- a/src/reference/language_basics.rst +++ b/src/reference/language_basics.rst @@ -102,8 +102,7 @@ Declaring Data Types ==================== .. note:: - .. todo:: - I think having paragraphs like this should be somewhere else which we can link to from here + .. todo:: Remove paragragh 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. @@ -111,6 +110,10 @@ This can make Python a very relaxed and comfortable language for rapid developme However with Cython it is possible to gain significant speed-ups through the use of ‘early binding’ programming techniques. +.. note:: Typing is not a necessity + + Providing static typing to parameters and variables is convenience to speed up your code, but it is not a necessity. Optimize where and when needed. + The cdef Statement ================== @@ -168,7 +171,8 @@ The ``cdef`` statement is used to make C level declarations for: ... -.. note:: +.. note:: Constants + Constants can be defined by using an anonymous enum:: cdef enum: @@ -191,6 +195,16 @@ A series of declarations can grouped into a ``cdef`` block:: void f(Spam *s): print s.tons, "Tons of spam" + +.. note:: ctypedef statement + + The ``ctypedef`` statement is provided for naming types:: + + ctypedef unsigned long ULong + + ctypedef int *IntPtr + + Parameters ========== @@ -214,7 +228,8 @@ Parameters cdef spamobjs(x, y): ... - .. note:: + .. note:: -- + This is different then C language behavior, where it is an int by default. @@ -447,19 +462,82 @@ Scope Rules True = 1 +Built-in Constants +================== + +Pre-defined Python built-in constants: + +* None +* True +* False + + +Operator Precedence +=================== + +* Cython uses Python precedence order, not C + + +For-loops +========== + +* ``range()`` is C optimized when the index value has been declared by ``cdef``:: + + cdef i + for i in range(n): + ... + +* The other form available in C is the for-from style + + * The target expression must be a variable name. + * The name between the lower and upper bounds must be the same as the target name. + + for i from 0 <= i < n: + ... + + * Or when using a step size:: + + for i from 0 <= i < n by s: + ... + + * To reverse the direction, reverse the conditional operation:: + + for i from 0 >= i > n: + ... + +* The ``break`` and ``continue`` are permissible. +* Can contain an if-else clause. + ===================== 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 ===================== +* Are decalared with the ``def`` statement +* Are called with Python objects +* Return Python objects +* See **Parameters** for special consideration + Callable from C ================ +* Are declared with the ``cdef`` statement. +* Are called with either Python objects or C values. +* Can return either Python objects or C values. + Callable from both Python and C ================================ +* Are declared with the ``cpdef`` statement. +* Can be called from anywhere, because it uses a little Cython magic. +* Uses the faster C calling conventions when being called from other Cython code. + Overriding ========== @@ -482,6 +560,51 @@ Function Pointers * Functions declared in a ``struct`` are automatically converted to function pointers. * see **using exceptions with function pointers** +Python Built-ins +================ + +The following are provided: + +.. todo:: incomplete + ++------------------------------+-------------+----------------------------+ +| Function and arguments | Return type | Python/C API Equivalent | ++==============================+=============+============================+ +| abs(obj) | object | PyNumber_Absolute | ++------------------------------+-------------+----------------------------+ +| bool(obj) | object | Py_True, Py_False | ++------------------------------+-------------+----------------------------+ +| chr(obj) | object | char | ++------------------------------+-------------+----------------------------+ +| delattr(obj, name) | int | PyObject_DelAttr | ++------------------------------+-------------+----------------------------+ +| dir(obj) | object | PyObject_Dir | +| getattr(obj, name) (Note 1) | | | +| getattr3(obj, name, default) | | | ++------------------------------+-------------+----------------------------+ +| hasattr(obj, name) | int | PyObject_HasAttr | ++------------------------------+-------------+----------------------------+ +| hash(obj) | int | PyObject_Hash | ++------------------------------+-------------+----------------------------+ +| intern(obj) | object | PyObject_InternFromString | ++------------------------------+-------------+----------------------------+ +| isinstance(obj, type) | int | PyObject_IsInstance | ++------------------------------+-------------+----------------------------+ +| issubclass(obj, type) | int | PyObject_IsSubclass | ++------------------------------+-------------+----------------------------+ +| iter(obj) | object | PyObject_GetIter | ++------------------------------+-------------+----------------------------+ +| len(obj) | Py_ssize_t | PyObject_Length | ++------------------------------+-------------+----------------------------+ +| pow(x, y, z) (Note 2) | object | PyNumber_Power | ++------------------------------+-------------+----------------------------+ +| reload(obj) | object | PyImport_ReloadModule | ++------------------------------+-------------+----------------------------+ +| repr(obj) | object | PyObject_Repr | ++------------------------------+-------------+----------------------------+ +| setattr(obj, name) | void | PyObject_SetAttr | ++------------------------------+-------------+----------------------------+ + ============================ Error and Exception Handling @@ -535,8 +658,7 @@ Error and Exception Handling .. note:: Function pointers * Require the same exception value specification as it's user has declared. - * Use cases here are when used as parameters and when assigned to a variable - * Example:: + * Use cases here are when used as parameters and when assigned to a variable:: int (*grail)(int, char *) except -1 @@ -548,7 +670,7 @@ Error and Exception Handling .. note:: C++ - For exceptions from C++ compiled programs, see **Wrapping C++ Classes** + * For exceptions from C++ compiled programs, see **Wrapping C++ Classes** Checking return values for non-Cython functions.. ================================================= @@ -558,7 +680,7 @@ Checking return values for non-Cython functions.. cdef extern FILE *fopen(char *filename, char *mode) except NULL # WRONG! * The except clause does not work that way. - * It's only purpose is to propagate Python exceptions that have already been raised, either by... + * It's only purpose is to propagate Python exceptions that have already been raised by either... * A Cython function * A C function that calls Python/C API routines. @@ -570,21 +692,75 @@ Checking return values for non-Cython functions.. if p == NULL: raise SpamError("Couldn't open the spam file") - - ======================= Conditional Compilation ======================= +* The expressions in the following sub-sections must be valid compile-time expressions. +* They can evaluate to any Python value. +* The *truth* of the result is determined in the usual Python way. Compile-Time Definitions ========================= +* Defined using the ``DEF`` statement:: + + DEF FavouriteFood = "spam" + DEF ArraySize = 42 + DEF OtherArraySize = 2 * ArraySize + 17 + +* The right hand side must be a valid compile-time expression made up of either: + + * Literal values + * Names defined by other ``DEF`` statements + +* They can be combined using any of the Python expression syntax +* Cython provides the following pre-defined names + + * Corresponding to the values returned by ``os.uname()`` + + * UNAME_SYSNAME + * UNAME_NODENAME + * UNAME_RELEASE + * UNAME_VERSION + * UNAME_MACHINE + +* A name defined by ``DEF`` can appear anywhere an identifier can appear. +* Cython replaces the name with the literal value before compilation. + + * The compile-time expression, in this case, must eveluate to a Python value of ``int``, ``long``, ``float``, or ``str``:: + + cdef int a1[ArraySize] + cdef int a2[OtherArraySize] + print "I like", FavouriteFood + Conditional Statements ======================= +* Similiar semantics of the C pre-processor +* The following statements can be used to conditinally include or exclude sections of code to compile. + + * ``IF`` + * ``ELIF`` + * ``ELSE`` + +:: + + IF UNAME_SYSNAME == "Windows": + include "icky_definitions.pxi" + ELIF UNAME_SYSNAME == "Darwin": + include "nice_definitions.pxi" + ELIF UNAME_SYSNAME == "Linux": + include "penguin_definitions.pxi" + ELSE: + include "other_definitions.pxi" + +* ``ELIF`` and ``ELSE`` are optional. +* ``IF`` can appear anywhere that a normal statement or declaration can appear +* It can contain any statements or declarations that would be valid in that context. + * This includes other ``IF`` and ``DEF`` statements