From 90b64b51306688e1a111a660582f5c273dbda1f2 Mon Sep 17 00:00:00 2001 From: William Stein Date: Sat, 28 Jul 2007 13:43:42 -0700 Subject: [PATCH] More Pyrex/SageX --> Cython changes --- CHANGES.txt => CHANGES_pyrex.txt | 0 COPYING.txt | 2 + Demos/Setup.py | 2 +- Demos/callback/Makefile.nodistutils | 2 +- Demos/callback/Setup.py | 2 +- Doc/About.html | 2 +- Doc/FAQ.html | 10 +- Doc/extension_types.html | 48 ++++----- Doc/index.html | 2 +- Doc/overview.html | 160 ++++++++++++++-------------- Doc/sharing.html | 20 ++-- Doc/special_methods.html | 6 +- MANIFEST.in | 6 +- Makefile | 10 +- README.txt | 17 ++- ToDo.txt | 2 + USAGE.txt | 34 +++--- cython.py | 4 +- 18 files changed, 170 insertions(+), 159 deletions(-) rename CHANGES.txt => CHANGES_pyrex.txt (100%) diff --git a/CHANGES.txt b/CHANGES_pyrex.txt similarity index 100% rename from CHANGES.txt rename to CHANGES_pyrex.txt diff --git a/COPYING.txt b/COPYING.txt index f266bada..31469485 100644 --- a/COPYING.txt +++ b/COPYING.txt @@ -8,4 +8,6 @@ Cython, which derives from Pyrex, is licensed under the Python Software Foundation License. More precisely, all modifications made to go from Pyrex to Cython are so licensed. +See LICENSE.txt for more details. + diff --git a/Demos/Setup.py b/Demos/Setup.py index 658a44c3..cd49628a 100644 --- a/Demos/Setup.py +++ b/Demos/Setup.py @@ -1,6 +1,6 @@ from distutils.core import setup from distutils.extension import Extension -from Pyrex.Distutils import build_ext +from Cython.Distutils import build_ext setup( name = 'Demos', diff --git a/Demos/callback/Makefile.nodistutils b/Demos/callback/Makefile.nodistutils index 012c1a86..5df2f187 100644 --- a/Demos/callback/Makefile.nodistutils +++ b/Demos/callback/Makefile.nodistutils @@ -4,7 +4,7 @@ PYINCLUDE = \ -I$(PYHOME)/$(ARCH)/include/python2.2 %.c: %.pyx - ../../bin/pyrexc $< + ../../bin/cython $< %.o: %.c gcc -c -fPIC $(PYINCLUDE) $< diff --git a/Demos/callback/Setup.py b/Demos/callback/Setup.py index 5e48206a..3f4bf6fc 100644 --- a/Demos/callback/Setup.py +++ b/Demos/callback/Setup.py @@ -1,6 +1,6 @@ from distutils.core import setup from distutils.extension import Extension -from Pyrex.Distutils import build_ext +from Cython.Distutils import build_ext setup( name = 'callback', diff --git a/Doc/About.html b/Doc/About.html index 057d05a3..37cfb2ec 100644 --- a/Doc/About.html +++ b/Doc/About.html @@ -1 +1 @@ - About Pyrex

Pyrex

A language for writing Python extension modules

What is Pyrex all about?

Pyrex 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.

Pyrex aims to go far beyond what any of these previous tools provides. Pyrex 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, Pyrex 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 Pyrex

The fundamental nature of Pyrex can be summed up as follows: Pyrex is Python with C data types.

Pyrex is Python: Almost any piece of Python code is also valid Pyrex code. (There are a few limitations, but this approximation will serve for now.) The Pyrex compiler will convert it into C code which makes equivalent calls to the Python/C API. In this respect, Pyrex is similar to the former Python2C project (to which I would supply a reference except that it no longer seems to exist).

...with C data types. But Pyrex 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.

primes.pyx
 1  def primes(int kmax):
 2      cdef int n, k, i
 3      cdef int p[1000]
 4      result = []
 5      if kmax > 1000:
 6          kmax = 1000
 7      k = 0
 8      n = 2
 9      while k < kmax:
10          i = 0
11          while i < k and n % p[i] <> 0:
12              i = i + 1
13          if i == k:
14             p[k] = n
15             k = k + 1
16             result.append(n)
17          n = n + 1
18      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 Pyrex 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 Pyrex has saved you, take a look at the C code generated for this module .

Language Details

For more about the Pyrex language, see the Language Overview .

Future Plans

Pyrex is not finished. Substantial tasks remaining include: \ No newline at end of file + About Cython

Cython

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 limitations, 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. In this respect, Cython is similar to the former Python2C project (to which I would supply a reference except that it no longer seems to exist).

...with C data types. 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.

primes.pyx
 1  def primes(int kmax):
 2      cdef int n, k, i
 3      cdef int p[1000]
 4      result = []
 5      if kmax > 1000:
 6          kmax = 1000
 7      k = 0
 8      n = 2
 9      while k < kmax:
10          i = 0
11          while i < k and n % p[i] <> 0:
12              i = i + 1
13          if i == k:
14             p[k] = n
15             k = k + 1
16             result.append(n)
17          n = n + 1
18      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 the Language Overview .

Future Plans

Cython is not finished. Substantial tasks remaining include: \ No newline at end of file diff --git a/Doc/FAQ.html b/Doc/FAQ.html index ad09c262..445b4dfe 100644 --- a/Doc/FAQ.html +++ b/Doc/FAQ.html @@ -4,7 +4,7 @@ FAQ.html -

Pyrex FAQ +

Cython FAQ

Contents

@@ -14,7 +14,7 @@ bytes to a Python string?
  • How do I access the data inside a Numeric array object?
    • -
  • Pyrex says my extension type object has no attribute +
  • Cython says my extension type object has no attribute 'rhubarb', but I know it does. What gives?
  • Python says my extension type has no method called 'quack', but I know it does. What gives?
    • @@ -55,10 +55,10 @@ bytes to a Python string? section of the "Extension Types" documentation page.

    -

    Pyrex says my extension type object has no attribute +

    Cython says my extension type object has no attribute 'rhubarb', but I know it does. What gives?

    -You're probably trying to access it through a reference which Pyrex thinks -is a generic Python object. You need to tell Pyrex that it's a reference +You're probably trying to access it through a reference which Cython thinks +is a generic Python object. You need to tell Cython that it's a reference to your extension type by means of a declaration,
    for example,
    cdef class Vegetables:
    diff --git a/Doc/extension_types.html b/Doc/extension_types.html index cda6377e..ae7a6bb1 100644 --- a/Doc/extension_types.html +++ b/Doc/extension_types.html @@ -31,7 +31,7 @@

    Introduction

    As well as creating normal user-defined classes with the Python class -statement, Pyrex also lets you create new built-in Python types, known as +statement, Cython also lets you create new built-in Python types, known as extension types. You define an extension type using the cdef class statement. Here's an example:
    cdef class Shrubbery:

        cdef int width, height

        def __init__(self, w, h):
    @@ -43,7 +43,7 @@ self.width, \
                "by", self.height, "cubits."

    - As you can see, a Pyrex extension type definition looks a lot like a Python + As you can see, a Cython extension type definition looks a lot like a Python class definition. Within it, you use the def statement to define methods that can be called from Python code. You can even define many of the special methods such as __init__ as you would in Python. @@ -59,9 +59,9 @@ to an extension type instance at run time simply by assigning to them, as you could with a Python class instance. (You can subclass the extension type in Python and add attributes to instances of the subclass, however.)

    There are two ways that attributes of an extension type can be accessed: - by Python attribute lookup, or by direct access to the C struct from Pyrex + by Python attribute lookup, or by direct access to the C struct from Cython code. Python code is only able to access attributes of an extension type -by the first method, but Pyrex code can use either method.

    +by the first method, but Cython code can use either method.

    By default, extension type attributes are only accessible by direct access, not Python access, which means that they are not accessible from Python code. To make them accessible from Python code, you need to declare them as public or readonly. For example,

    @@ -79,7 +79,7 @@ To make them accessible from Python code, you need to declare them as public

    Note also that the public and readonly options apply only to Python access, not direct access. All the attributes of an extension type are always readable and writable by direct access.

    -

    Howerver, for direct access to be possible, the Pyrex compiler must know +

    Howerver, for direct access to be possible, the Cython compiler must know that you have an instance of that type, and not just a generic Python object. It knows this already in the case of the "self" parameter of the methods of that type, but in other cases you will have to tell it by means of a declaration. @@ -87,19 +87,19 @@ For example,

    cdef widen_shrubbery(Shrubbery sh, extra_width):
        sh.width = sh.width + extra_width
    If you attempt to access an extension type attribute through a generic -object reference, Pyrex will use a Python attribute lookup. If the attribute +object reference, Cython will use a Python attribute lookup. If the attribute is exposed for Python access (using public or readonly) then this will work, but it will be much slower than direct access.

    Extension types and None

    When you declare a parameter or C variable as being of an extension type, - Pyrex will allow it to take on the value None as well as values of its declared + Cython will allow it to take on the value None as well as values of its declared type. This is analogous to the way a C pointer can take on the value NULL, and you need to exercise the same caution because of it. There is no problem as long as you are performing Python operations on it, because full dynamic type checking will be applied. However, when you access C attributes of an extension type (as in the widen_shrubbery function above), it's up to you to make sure the reference you're using is not None -- in the interests -of efficiency, Pyrex does not check this. +of efficiency, Cython does not check this.

    You need to be particularly careful when exposing Python functions which take extension types as arguments. If we wanted to make widen_shrubbery a Python function, for example, if we simply wrote

    @@ -113,7 +113,7 @@ parameter.     if sh is None:
            raise TypeError
        sh.width = sh.width + extra_width
    - but since this is anticipated to be such a frequent requirement, Pyrex + but since this is anticipated to be such a frequent requirement, Cython provides a more convenient way. Parameters of a Python function declared as an extension type can have a not None clause:
    def widen_shrubbery(Shrubbery sh not None, extra_width): @@ -223,14 +223,14 @@ type:     ...


    - A complete definition of the base type must be available to Pyrex, so if + A complete definition of the base type must be available to Cython, so if the base type is a built-in type, it must have been previously declared as -an extern extension type. If the base type is defined in another Pyrex +an extern extension type. If the base type is defined in another Cython module, it must either be declared as an extern extension type or imported using the cimport statement.

    An extension type can only have one base class (no multiple inheritance).

    -

    Pyrex extension types can also be subclassed in Python. A Python class +

    Cython extension types can also be subclassed in Python. A Python class can inherit from multiple extension types provided that the usual Python rules for multiple inheritance are followed (i.e. the C layouts of all the base classes must be compatible).
    @@ -316,18 +316,18 @@ type object called Public and external extension types Extension types can be declared extern or public. An extern extension type declaration makes -an extension type defined in external C code available to a Pyrex module. -A public extension type declaration makes an extension type defined in a Pyrex module available to external C +an extension type defined in external C code available to a Cython module. +A public extension type declaration makes an extension type defined in a Cython module available to external C code.

    External extension types

    An extern extension type allows you to gain access to the internals - of Python objects defined in the Python core or in a non-Pyrex extension + of Python objects defined in the Python core or in a non-Cython extension module. -
    NOTE: In Pyrex versions before 0.8, extern extension - types were also used to reference extension types defined in another Pyrex - module. While you can still do that, Pyrex 0.8 and later provides a better +
    NOTE: In Cython versions before 0.8, extern extension + types were also used to reference extension types defined in another Cython + module. While you can still do that, Cython 0.8 and later provides a better mechanism for this. See Sharing C Declarations Between - Pyrex Modules.
    + Cython Modules.
    Here is an example which will let you get at the C-level members of the built-in complex object.
    cdef extern from "complexobject.h":

        struct Py_complex:
    @@ -365,11 +365,11 @@ if your extension class declaration is inside a cdef extern from block,

    Implicit importing

    Backwards Incompatibility Note: -You will have to update any pre-0.8 Pyrex modules you have which use extern +You will have to update any pre-0.8 Cython modules you have which use extern extension types. I apologise for this, but for complicated reasons it proved to be too difficult to continue supporting the old way of doing these while introducing the new features that I wanted.
    - Pyrex 0.8 and later requires you to include a module name in an extern + Cython 0.8 and later requires you to include a module name in an extern extension class declaration, for example,
    cdef extern class MyModule.Spam:
        ...
    @@ -394,7 +394,7 @@ using an as clause, for example, 
    from My.Nested.Package import Spam as Yummy

    Type names vs. constructor names

    - Inside a Pyrex module, the name of an extension type serves two distinct + Inside a Cython module, the name of an extension type serves two distinct purposes. When used in an expression, it refers to a module-level global variable holding the type's constructor (i.e. its type-object). However, it can also be used as a C type name to declare variables, arguments and @@ -429,12 +429,12 @@ struct, and type_object_name is the name to assume for the type's statically declared type object. (The object and type clauses can be written in either order.)

    If the extension type declaration is inside a cdef extern from -block, the object clause is required, because Pyrex must be able to +block, the object clause is required, because Cython must be able to generate code that is compatible with the declarations in the header file. Otherwise, for extern extension types, the object clause is optional.

    For public extension types, the object and type clauses -are both required, because Pyrex must be able to generate code that is compatible +are both required, because Cython must be able to generate code that is compatible with external C code.


    diff --git a/Doc/index.html b/Doc/index.html index 6a262e3b..635085d6 100644 --- a/Doc/index.html +++ b/Doc/index.html @@ -1 +1 @@ - Pyrex - Front Page  
    Pyrex A smooth blend of the finest Python 
    with the unsurpassed power 
    of raw C.
    Welcome to Pyrex, a language for writing Python extension modules. Pyrex makes creating an extension module is almost as easy as creating a Python module! To find out more, consult one of the edifying documents below.

    Documentation

    About Pyrex

    Read this to find out what Pyrex is all about and what it can do for you.

    Language Overview

    A description of all the features of the Pyrex language. This is the closest thing to a reference manual in existence yet.

    FAQ

    Want to know how to do something in Pyrex? Check here first.

    Other Resources

    Michael's Quick Guide to Pyrex

    This tutorial-style presentation will take you through the steps of creating some Pyrex modules to wrap existing C libraries. Contributed by Michael JasonSmith.

    Mail to the Author

    If you have a question that's not answered by anything here, you're not sure about something, or you have a bug to report or a suggestion to make, or anything at all to say about Pyrex, feel free to email me: greg@cosc.canterbury.ac.nz
    \ No newline at end of file + Cython - Front Page  
    Cython A smooth blend of the finest Python 
    with the unsurpassed power 
    of raw C.
    Welcome to Cython, a language for writing Python extension modules. Cython makes creating an extension module is almost as easy as creating a Python module! To find out more, consult one of the edifying documents below.

    Documentation

    About Cython

    Read this to find out what Cython is all about and what it can do for you.

    Language Overview

    A description of all the features of the Cython language. This is the closest thing to a reference manual in existence yet.

    FAQ

    Want to know how to do something in Cython? Check here first.

    Other Resources

    Michael's Quick Guide to Cython

    This tutorial-style presentation will take you through the steps of creating some Cython modules to wrap existing C libraries. Contributed by Michael JasonSmith.

    Mail to the Author

    If you have a question that's not answered by anything here, you're not sure about something, or you have a bug to report or a suggestion to make, or anything at all to say about Cython, feel free to email me: greg@cosc.canterbury.ac.nz
    \ No newline at end of file diff --git a/Doc/overview.html b/Doc/overview.html index d50eeb6e..36ca8173 100644 --- a/Doc/overview.html +++ b/Doc/overview.html @@ -5,14 +5,14 @@ - Pyrex Language Overview + Cython Language Overview -

    Overview of the Pyrex Language 

    +

    Overview of the Cython Language 

    This document informally describes the extensions to the Python language - made by Pyrex. Some day there will be a reference manual covering everything + made by Cython. Some day there will be a reference manual covering everything in more detail.
      @@ -33,14 +33,14 @@
  • Scope rules
  • Statements and expressions
  • Error return values
  • The include statement
    • @@ -57,13 +57,13 @@ expressions
  • Public declarations
  • Extension Types (Section revised in 0.9)
    • -
  • Sharing Declarations Between Pyrex Modules +
  • Sharing Declarations Between Cython Modules (NEW in 0.8)
  • Limitations
    • @@ -72,13 +72,13 @@ expressions

    Basics

    - This section describes the basic features of the Pyrex language. The facilities + This section describes the basic features of the Cython language. The facilities covered in this section allow you to create Python-callable functions that manipulate C data structures and convert between Python and C data types. - Later sections will cover facilities for wrapping external C code, creating new Python types and cooperation between Pyrex modules. + Later sections will cover facilities for wrapping external C code, creating new Python types and cooperation between Cython modules.

    Python functions vs. C functions

    - There are two kinds of function definition in Pyrex: + There are two kinds of function definition in Cython:

    Python functions are defined using the def statement, as in Python. They take Python objects as parameters and return Python objects.

    @@ -89,10 +89,10 @@ expressions
    Python objects or C values.

    -

    Within a Pyrex module, Python functions and C functions can call each other +

    Within a Cython module, Python functions and C functions can call each other freely, but only Python functions can be called from outside the module by interpreted Python code. So, any functions that you want to "export" from - your Pyrex module must be declared as Python functions using def.

    + your Cython module must be declared as Python functions using def.

    Parameters of either type of function can be declared to have C data types, @@ -259,16 +259,16 @@ string.

    -Pyrex detects and prevents some mistakes of this kind. For instance, if you attempt something like
    +Cython detects and prevents some mistakes of this kind. For instance, if you attempt something like

    cdef char *s
    s = pystring1 + pystring2
    -then Pyrex will produce the error message "Obtaining char * from temporary Python value". +then Cython will produce the error message "Obtaining char * from temporary Python value". The reason is that concatenating the two Python strings produces a new Python string object that is referenced only by a temporary internal -variable that Pyrex generates. As soon as the statement has finished, +variable that Cython generates. As soon as the statement has finished, the temporary variable will be decrefed and the Python string -deallocated, leaving s dangling. Since this code could not possibly work, Pyrex refuses to compile it.
    +deallocated, leaving s dangling. Since this code could not possibly work, Cython refuses to compile it.

    @@ -281,7 +281,7 @@ It is then your responsibility to hold the reference Scope rules - Pyrex determines whether a variable belongs to a local scope, the module + Cython determines whether a variable belongs to a local scope, the module scope, or the built-in scope completely statically. As with Python, assigning to a variable which is not otherwise declared implicitly declares it to be a Python variable residing in the scope where it is assigned. Unlike @@ -316,7 +316,7 @@ the builtins module.
    Note: A consequence of these rules is that the module-level scope behaves the same way as a Python local scope if you refer to a variable before assigning to it. In particular, tricks such as the following will not work -in Pyrex:
    +in Cython:
    try:
      x = True
    except NameError:
      True = 1
    @@ -347,21 +347,21 @@ all Python operations are automatically checked for errors, with appropriate action taken.

    -

    Differences between C and Pyrex +

    Differences between C and Cython expressions

    There are some differences in syntax and semantics between C expressions and -Pyrex expressions, particularly in the area of C constructs which have +Cython expressions, particularly in the area of C constructs which have no direct equivalent in Python.
    • An integer literal without an L suffix is treated as a C constant, and will be truncated to whatever size your C compiler thinks appropriate. With an L suffix, it will be converted to Python long integer (even if it would be small enough to fit into a C int).

      • -
    • There is no -> operator in Pyrex. Instead of p->x, +
    • There is no -> operator in Cython. Instead of p->x, use p.x
      • -  
    • There is no * operator in Pyrex. Instead of +  
    • There is no * operator in Cython. Instead of *p, use p[0]
      •  
    • There is an & operator, with the same semantics @@ -380,7 +380,7 @@ example:
      • cdef char *p, float *q
      p = <char*>q
    Warning: Don't attempt to use a typecast to convert between -Python and C data types -- it won't do the right thing. Leave Pyrex to perform +Python and C data types -- it won't do the right thing. Leave Cython to perform the conversion automatically. @@ -393,12 +393,12 @@ the conversion automatically. won't be very fast, even if i and n are declared as C integers, because range is a Python function. For iterating over -ranges of integers, Pyrex has another form of for-loop: +ranges of integers, Cython has another form of for-loop:
    for i from 0 <= i < n:
        ...
    If the loop variable and the lower and upper bounds are all C integers, -this form of loop will be much faster, because Pyrex will translate it into +this form of loop will be much faster, because Cython will translate it into pure C code.

    Some things to note about the for-from loop:

    @@ -446,7 +446,7 @@ of exception value declaration:

    cdef int spam() except? -1:
        ...
    - The "?" indicates that the value -1 only indicates a possible error. In this case, Pyrex generates a call to PyErr_Occurredif the + The "?" indicates that the value -1 only indicates a possible error. In this case, Cython generates a call to PyErr_Occurredif the exception value is returned, to make sure it really is an error.

    There is also a third form of exception value declaration:

    @@ -454,7 +454,7 @@ exception value is returned, to make sure it really is an error.
    cdef int spam() except *:
        ...
    - This form causes Pyrex to generate a call to PyErr_Occurred after + This form causes Cython to generate a call to PyErr_Occurred after every call to spam, regardless of what value it returns. If you have a function returning void that needs to propagate errors, you will have to use this form, since there isn't any return value to test. @@ -484,7 +484,7 @@ is an example of a pointer-to-function declaration with an exception value: -

    Checking return values of non-Pyrex +

    Checking return values of non-Cython functions

    It's important to understand that the except clause does not cause an error to be raised when the specified value is returned. For @@ -495,7 +495,7 @@ example, you can't write something like and expect an exception to be automatically raised if a call to fopen returns NULL. The except clause doesn't work that way; its only purpose is for propagating exceptions that have already been raised, either -by a Pyrex function or a C function that calls Python/C API routines. To +by a Cython function or a C function that calls Python/C API routines. To get an exception from a non-Python-aware function such as fopen, you will have to check the return value and raise it yourself, for example, 
    cdef FILE *p
    p = fopen("spam.txt", "r")
    if p == NULL:
        raise SpamError("Couldn't open the spam file")
    @@ -507,20 +507,20 @@ have to check the return value and raise it yourself, for example,

    The include statement

    - For convenience, a large Pyrex module can be split up into a number of + For convenience, a large Cython module can be split up into a number of files which are put together using the include statement, for example 
    include "spamstuff.pxi"
    The contents of the named file are textually included at that point. The - included file can contain any complete top-level Pyrex statements, including + included file can contain any complete top-level Cython statements, including other include statements. The include statement itself can only appear at the top level of a file.

    The include statement can also be used in conjunction with public declarations to make C functions and - variables defined in one Pyrex module accessible to another. However, note + variables defined in one Cython module accessible to another. However, note that some of these uses have been superseded by the facilities described -in Sharing Declarations Between Pyrex Modules, +in Sharing Declarations Between Cython Modules, and it is expected that use of the include statement for this purpose will be phased out altogether in future versions.

    @@ -529,14 +529,14 @@ will be phased out altogether in future versions.

    C Code
    - One of the main uses of Pyrex is wrapping existing libraries of C code. + One of the main uses of Cython is wrapping existing libraries of C code. This is achieved by using external declarations to declare the C functions and variables from the library that you want to use.

    You can also use public declarations to make - C functions and variables defined in a Pyrex module available to external + C functions and variables defined in a Cython module available to external C code. The need for this is expected to be less frequent, but you might want to do it, for example, if you are embedding Python in another application - as a scripting language. Just as a Pyrex module can be used as a bridge to + as a scripting language. Just as a Cython module can be used as a bridge to allow Python code to call C code, it can also be used to allow C code to call Python code.

    @@ -558,12 +558,12 @@ can also be declared extern to specify that they are defined elsewhere,

    Referencing C header files

    When you use an extern definition on its own as in the examples above, -Pyrex includes a declaration for it in the generated C file. This can cause +Cython includes a declaration for it in the generated C file. This can cause problems if the declaration doesn't exactly match the declaration that will be seen by other C code. If you're wrapping an existing C library, for example, it's important that the generated C code is compiled with exactly the same declarations as the rest of the library. -

    To achieve this, you can tell Pyrex that the declarations are to be found +

    To achieve this, you can tell Cython that the declarations are to be found in a C header file, like this:

    @@ -575,10 +575,10 @@ declarations as the rest of the library. The cdef extern from clause does three things:
      -
    1. It directs Pyrex to place a #include statement for the named +
    2. It directs Cython to place a #include statement for the named header file in the generated C code.
      3. -  
    3. It prevents Pyrex from generating any C code for the declarations +  
    4. It prevents Cython from generating any C code for the declarations found in the associated block.
      5.  
    5. It treats all declarations within the block as though they @@ -586,14 +586,14 @@ started with cdef extern.
    - It's important to understand that Pyrex does not itself read the -C header file, so you still need to provide Pyrex versions of any declarations - from it that you use. However, the Pyrex declarations don't always have to + It's important to understand that Cython does not itself read the +C header file, so you still need to provide Cython versions of any declarations + from it that you use. However, the Cython declarations don't always have to exactly match the C ones, and in some cases they shouldn't or can't. In particular:
      -
    1. Don't use const. Pyrex doesn't know anything about const, +
    2. Don't use const. Cython doesn't know anything about const, so just leave it out. Most of the time this shouldn't cause any problem, although on rare occasions you might have to use a cast. 1
      3. @@ -673,21 +673,21 @@ name: There are two main ways that structs, unions and enums can be declared in C header files: using a tag name, or using a typedef. There are also some variations based on various combinations of these. -

      It's important to make the Pyrex declarations match the style used in the -header file, so that Pyrex can emit the right sort of references to the type -in the code it generates. To make this possible, Pyrex provides two different +

      It's important to make the Cython declarations match the style used in the +header file, so that Cython can emit the right sort of references to the type +in the code it generates. To make this possible, Cython provides two different syntaxes for declaring a struct, union or enum type. The style introduced above corresponds to the use of a tag name. To get the other style, you prefix the declaration with ctypedef, as illustrated below.

      The following table shows the various possible styles that can be found - in a header file, and the corresponding Pyrex declaration that you should + in a header file, and the corresponding Cython declaration that you should put in the cdef exern from block. Struct declarations are used as an example; the same applies equally to union and enum declarations.

      -

      Note that in all the cases below, you refer to the type in Pyrex code simply +

      Note that in all the cases below, you refer to the type in Cython code simply as Foo, not struct Foo.
        @@ -696,7 +696,7 @@ as Foo, not struct Foo  +Cython code @@ -706,7 +706,7 @@ Pyrex code }; - @@ -716,7 +716,7 @@ Pyrex code } Foo; - @@ -729,7 +729,7 @@ foo {
        ...
      ctypedef foo Foo #optional @@ -767,19 +767,19 @@ necessary.

      Resolving naming conflicts - C name specifications

      - Each Pyrex module has a single module-level namespace for both Python + Each Cython module has a single module-level namespace for both Python and C names. This can be inconvenient if you want to wrap some external C functions and provide the Python user with Python functions of the same names. -

      Pyrex 0.8 provides a couple of different ways of solving this problem. +

      Cython 0.8 provides a couple of different ways of solving this problem. The best way, especially if you have many C functions to wrap, is probably to put the extern C function declarations into a different namespace using the facilities described in the section on sharing - declarations between Pyrex modules.

      + declarations between Cython modules.

      The other way is to use a c name specification to give different - Pyrex and C names to the C function. Suppose, for example, that you want + Cython and C names to the C function. Suppose, for example, that you want to wrap an external function called eject_tomato. If you declare it as

      @@ -787,7 +787,7 @@ it as 

      cdef extern void c_eject_tomato "eject_tomato" (float speed)
      - then its name inside the Pyrex module will be c_eject_tomato, + then its name inside the Cython module will be c_eject_tomato, whereas its name in C will be eject_tomato. You can then wrap it with 
      def eject_tomato(speed):
        c_eject_tomato(speed)
      @@ -796,8 +796,8 @@ with so that users of your module can refer to it as eject_tomato.

      Another use for this feature is referring to external names that happen - to be Pyrex keywords. For example, if you want to call an external function - called print, you can rename it to something else in your Pyrex + to be Cython keywords. For example, if you want to call an external function + called print, you can rename it to something else in your Cython module.

      @@ -814,16 +814,16 @@ module.

      Public Declarations

      - You can make C variables and functions defined in a Pyrex module accessible - to external C code (or another Pyrex module) using the public keyword, as follows: + You can make C variables and functions defined in a Cython module accessible + to external C code (or another Cython module) using the public keyword, as follows:
      cdef public int spam # public variable declaration

      cdef public void grail(int num_nuns): # public function declaration
          ...

      - If there are any public declarations in a Pyrex module, a .h file is generated containing equivalent C declarations for inclusion in other + If there are any public declarations in a Cython module, a .h file is generated containing equivalent C declarations for inclusion in other C code. -

      Pyrex also generates a .pxi file containing Pyrex versions of the - declarations for inclusion in another Pyrex module using the include statement. If you use this, you +

      Cython also generates a .pxi file containing Cython versions of the + declarations for inclusion in another Cython module using the include statement. If you use this, you will need to arrange for the module using the declarations to be linked against the module defining them, and for both modules to be available to the dynamic linker at run time. I haven't tested this, so I can't say how @@ -832,22 +832,22 @@ well it will work on the various platforms.

      NOTE: If all you want to export is an extension type, there is now a better way -- see Sharing Declarations Between - Pyrex Modules.
      + Cython Modules.

      Extension Types

      - One of the most powerful features of Pyrex is the ability to easily create + One of the most powerful features of Cython is the ability to easily create new built-in Python types, called extension types. This is a major topic in itself, so there is a  separate page devoted to it. -

      Sharing Declarations Between Pyrex Modules +

      Sharing Declarations Between Cython Modules

      - Pyrex 0.8 introduces a substantial new set of facilities allowing a Pyrex + Cython 0.8 introduces a substantial new set of facilities allowing a Cython module to easily import and use C declarations and extension types from another -Pyrex module. You can now create a set of co-operating Pyrex modules just +Cython module. You can now create a set of co-operating Cython modules just as easily as you can create a set of co-operating Python modules. There is a separate page devoted to this topic.

      Limitations @@ -856,7 +856,7 @@ a separate page devoted to this topic.

      Unsupported Python features

      - Pyrex is not quite a full superset of Python. The following restrictions + Cython is not quite a full superset of Python. The following restrictions apply:
    3. Function definitions (whether using def or cdef) cannot be nested within other function definitions.
      @@ -867,7 +867,7 @@ a separate page devoted to this topic.  
    4. The import * form of import is not allowed anywhere (other forms of the import statement are fine, though).
      5. -  
    5. Generators cannot be defined in Pyrex.
      +  
    6. Generators cannot be defined in Cython.

    7. The globals() and locals() functions cannot be @@ -875,7 +875,7 @@ used.
      8. The above restrictions will most likely remain, since removing them would - be difficult and they're not really needed for Pyrex's intended applications. + 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:

      @@ -895,26 +895,26 @@ docstrings.

    8. The use of string literals as comments is not recommended at present, - because Pyrex doesn't optimize them away, and won't even accept them in + because Cython doesn't optimize them away, and won't even accept them in places where executable statements are not allowed.

      9. Semantic differences between Python - and Pyrex

      + 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 Pyrex it yields an unbound method2. A consequence of this is that the + in Cython it yields an unbound method2. 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 Pyrex. This can be worked around by defining the function + 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):
        ...
      @@ -947,10 +947,10 @@ casting away the constness:
      2. The reason for the different behaviour -of class scopes is that Pyrex-defined Python functions are PyCFunction objects, +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, Pyrex wraps each method in an unbound method object itself before +around this, Cython wraps each method in an unbound method object itself before storing it in the class's dictionary.
       
      diff --git a/Doc/sharing.html b/Doc/sharing.html index a92856e2..29237bf2 100644 --- a/Doc/sharing.html +++ b/Doc/sharing.html @@ -1,14 +1,14 @@ - Sharing Declarations Between Pyrex Modules + Sharing Declarations Between Cython Modules -

      Sharing Declarations Between Pyrex Modules +

      Sharing Declarations Between Cython Modules

      - This section describes a new set of facilities introduced in Pyrex 0.8 -for making C declarations and extension types in one Pyrex module available -for use in another Pyrex module. These facilities are closely modelled on + This section describes a new set of facilities introduced in Cython 0.8 +for making C declarations 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.

      Contents

      @@ -27,9 +27,9 @@ naming conflicts
    9. Sharing extension types

      10. Definition and Implementation files

      - A Pyrex module can be split into two parts: a definition file with + 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 Pyrex modules, and an implementation file with a .pyx + 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 cimport statement.

      What a Definition File contains

      @@ -44,11 +44,11 @@ declared in another module's definition file, it imports it using the What an Implementation File contains - An implementation file can contain any kind of Pyrex statement, although + 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). @@ -101,7 +101,7 @@ name under which you imported it. Using cimport to import extension types is covered in more detail below.

      Search paths for definition files

      - When you cimport a module called modulename, the Pyrex + When you cimport a module called modulename, the Cython compiler searches for a file called modulename.pxd along the search path for include files, as specified by -I command line options.

      Also, whenever you compile a file modulename.pyx, the corresponding diff --git a/Doc/special_methods.html b/Doc/special_methods.html index b5ef495e..ecde87ee 100644 --- a/Doc/special_methods.html +++ b/Doc/special_methods.html @@ -5,7 +5,7 @@

      Special Methods of Extension Types

      - This page describes the special methods currently supported by Pyrex extension + This page describes the special methods currently supported by Cython extension types. A complete list of all the special methods appears in the table at the bottom. Some of these methods behave differently from their Python counterparts or have no direct Python counterparts, and require special mention. @@ -73,11 +73,11 @@ touch the object. In particular, don't call any other methods of the object or do anything which might cause the object to be resurrected. It's best if you stick to just deallocating C data.

      You don't need to worry about deallocating Python attributes of your object, -because that will be done for you by Pyrex after your __dealloc__ +because that will be done for you by Cython after your __dealloc__ method returns.

      Note: There is no __del__ method for extension types. (Earlier -versions of the Pyrex documentation stated that there was, but this turned +versions of the Cython documentation stated that there was, but this turned out to be incorrect.)

      Arithmetic methods

      diff --git a/MANIFEST.in b/MANIFEST.in index 7710f3e0..6d633f04 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,7 +1,7 @@ include MANIFEST.in README.txt INSTALL.txt CHANGES.txt ToDo.txt USAGE.txt include setup.py -include bin/pyrexc -include pyrexc.py -include Pyrex/Compiler/Lexicon.pickle +include bin/cython +include cython.py +include Cython/Compiler/Lexicon.pickle include Doc/* include Demos/* diff --git a/Makefile b/Makefile index 099ccfb8..4ec14f3f 100644 --- a/Makefile +++ b/Makefile @@ -1,14 +1,8 @@ -VERSION = 0.9.4.1 +VERSION = 0.9.6 version: @echo "Setting version to $(VERSION)" - @echo "version = '$(VERSION)'" > Pyrex/Compiler/Version.py - -#check_contents: -# @if [ ! -d Pyrex/Distutils ]; then \ -# echo Pyrex/Distutils missing; \ -# exit 1; \ -# fi + @echo "version = '$(VERSION)'" > Cython/Compiler/Version.py clean: @echo Cleaning Source diff --git a/README.txt b/README.txt index 4a70f7c2..a1f52b90 100644 --- a/README.txt +++ b/README.txt @@ -1,8 +1,8 @@ Welcome to Cython! ================= -Cython (http://www.cython.org) is based on Pyrex, but -supports more cutting edge functionality and optimizations. +Cython (http://www.cython.org) is based on Pyrex, but supports more +cutting edge functionality and optimizations. LICENSE: @@ -14,17 +14,24 @@ below). Cython itself is licensed under the +-------------------------- +There are TWO mercurial (hg) repositories included with Cython: --------------------------- + * Various project files, documentation, etc. (in the top level directory) + * The main codebase itself (in Cython/) + +We keep these separate for easier merging with the Pyrex project. -To see the change history, go to the Pyrex directory and type +To see the change history for Cython code itself, go to the Cython +directory and type $ hg log This requires that you have installed Mercurial. - -- William Stein (wstein@gmail.com) + +-- William Stein (wstein@gmail.com) xxxx diff --git a/ToDo.txt b/ToDo.txt index 5b5701b9..33926819 100644 --- a/ToDo.txt +++ b/ToDo.txt @@ -1,3 +1,5 @@ +-- The Original Pyrex Todo List -- + DONE - Pointer-to-function types. DONE - Nested declarators. diff --git a/USAGE.txt b/USAGE.txt index 3128cd01..50d06a19 100644 --- a/USAGE.txt +++ b/USAGE.txt @@ -1,11 +1,11 @@ -Pyrex - Usage Instructions +Cython - Usage Instructions ========================== -Building Pyrex extensions using distutils +Building Cython extensions using distutils ----------------------------------------- -Pyrex comes with an experimental distutils extension for compiling -Pyrex modules, contributed by Graham Fawcett of the University of +Cython comes with an experimental distutils extension for compiling +Cython modules, contributed by Graham Fawcett of the University of Windsor (fawcett@uwindsor.ca). The Demos directory contains a setup.py file demonstrating its use. To @@ -30,17 +30,17 @@ Try out the extensions with: python run_numeric_demo.py -Building Pyrex extensions by hand +Building Cython extensions by hand --------------------------------- -You can also invoke the Pyrex compiler on its own to translate a .pyx +You can also invoke the Cython compiler on its own to translate a .pyx file to a .c file. On Unix, - pyrexc filename.pyx + cython filename.pyx On other platforms, - python pyrexc.py filename.pyx + python cython.py filename.pyx It's then up to you to compile and link the .c file using whatever procedure is appropriate for your platform. The file @@ -51,19 +51,25 @@ one particular Unix system. Command line options -------------------- -The pyrexc command supports the following options: +The cython command supports the following options: Short Long Argument Description ----------------------------------------------------------------------------- - -v --version Display version number of pyrex compiler + -v --version Display version number of cython compiler -l --create-listing Write error messages to a .lis file -I --include-dir Search for include files in named - directory (may be repeated) + directory (may be repeated) -o --output-file Specify name of generated C file (only - one source file allowed if this is used) + one source file allowed if this is used) + -p, --embed-positions If specified, the positions in Cython files of each + function definition is embedded in its docstring. + -z, --pre-import If specified, assume undeclared names in this + module. Emulates the behavior of putting + "from import *" at the top of the file. -Anything else is taken as the name of a Pyrex source file and compiled -to a C source file. Multiple Pyrex source files can be specified + +Anything else is taken as the name of a Cython source file and compiled +to a C source file. Multiple Cython source files can be specified (unless -o is used), in which case each source file is treated as the source of a distinct extension module and compiled separately to produce its own C file. diff --git a/cython.py b/cython.py index f32cf153..f96c5779 100644 --- a/cython.py +++ b/cython.py @@ -1,6 +1,6 @@ # -# Pyrex -- Main Program, generic +# Cython -- Main Program, generic # -from Pyrex.Compiler.Main import main +from Cython.Compiler.Main import main main(command_line = 1) -- 2.26.2
      C code Possibilities for corresponding -Pyrex codeComments
      cdef struct Foo:
        ...      		Pyrex will refer to the type as struct Foo in the generated + Cython will refer to the type as struct Foo in the generated C code.
      ctypedef struct Foo:
        ...      		Pyrex will refer to the type simply as Foo + Cython will refer to the type simply as Foo in the generated C code.
      If the C header uses both a tag and a typedef - with different names, you can use either form of declaration in Pyrex + with different names, you can use either form of declaration in Cython (although if you need to forward reference the type, you'll have to use the first form).