Skip to content

C
cython
Commit 73f04523 authored by scoder's avatar scoder Committed by GitHub
Browse files
Options

Merge pull request #1666 from jdemeyer/remove_old_doc 

Remove obsolete documentation
parents 5a1c4958 85065883
Expand all Show whitespace changes
Inline Side-by-side
Showing with 0 additions and 2672 deletions
Doc/About.html deleted 100644 → 0
View file @ 5a1c4958
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]">
<title>About Cython</title>
</head>
<body>
<center>
<h1>
<hr width="100%">Cython</h1></center>
<center><i><font size=+1>A language for writing Python extension modules</font></i>
<hr width="100%"></center>
<h2>
What is Cython all about?</h2>
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.
<p>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?
<p>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.
<p>Various tools have been developed to ease some of the burdens of producing
extension code, of which perhaps <a href="http://www.swig.org">SWIG</a>
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.
<p>What's more, SWIG gives you no help at all if you want to create a new
built-in Python <i>type. </i>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.
<p>Another notable attempt at making it easier to extend Python is <a href="http://pyinline.sourceforge.net/">PyInline</a>
, 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,&nbsp; it doesn't address the creation
of new Python types.
<p>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
<i>anything</i> about the Python/C API. That's right -- <i>nothing at all</i>!
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
<i>built-in</i> Python types just as easily as you can define new classes
in Python.
<p>Sound too good to be true? Read on and find out how it's done.
<h2>
The Basics of Cython</h2>
The fundamental nature of Cython can be summed up as follows: <b>Cython is
Python with C data types</b>.
<p><i>Cython is Python:</i> 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).
<p><i>...with C data types.</i> 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.
<p>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.
<blockquote><b><tt><font size=+1>primes.pyx</font></tt></b></blockquote>
<blockquote>
<pre>&nbsp;1&nbsp; def primes(int kmax):
&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int n, k, i
&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int p[1000]
&nbsp;4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result = []
&nbsp;5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if kmax > 1000:
&nbsp;6&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; kmax = 1000
&nbsp;7&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = 0
&nbsp;8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = 2
&nbsp;9&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while k &lt; kmax:
10&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = 0
11&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while i &lt; k and n % p[i] &lt;> 0:
12&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = i + 1
13&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if i == k:
14&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; p[k] = n
15&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = k + 1
16&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result.append(n)
17&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = n + 1
18&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return result</pre>
</blockquote>
You'll see that it starts out just like a normal Python function definition,
except that the parameter <b>kmax</b> is declared to be of type <b>int</b>
. This means that the object passed will be converted to a C integer (or
a TypeError will be raised if it can't be).
<p>Lines 2 and 3 use the <b>cdef</b> 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 <b>result</b> hasn't been given a type, it is assumed to hold
a Python object.
<p>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.
<p>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 <b>n</b> is automatically converted
to a Python object before being passed to the <b>append</b> method. Finally,
at line 18, a normal Python <b>return</b> statement returns the result
list.
<p>Compiling primes.pyx with the Cython compiler produces an extension module
which we can try out in the interactive interpreter as follows:
<blockquote>
<pre>>>> import primes
>>> primes.primes(10)
[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
>>></pre>
</blockquote>
See, it works! And if you're curious about how much work Cython has saved
you, take a look at the <a href="primes.c">C code generated for this module</a>
.
<h2>
Language Details</h2>
For more about the Cython language, see the <a href="overview.html">Language
Overview</a> .
<h2>
Future Plans</h2>
Cython is not finished. Substantial tasks remaining include:
<ul>
<li>
Support for certain Python language features which are planned but not
yet implemented. See the <a href="overview.html#Limitations">Limitations</a>
section of the <a href="overview.html">Language Overview</a> for a current
list.</li>
</ul>
<ul>
<li>
C++ support. This could be a very big can of worms - careful thought required
before going there.</li>
</ul>
<ul>
<li>
Reading C/C++ header files directly would be very nice, but there are some
severe problems that I will have to find solutions for first, such as what
to do about preprocessor macros. My current thinking is to use a separate
tool to convert .h files into Cython declarations, possibly with some manual
intervention.</li>
</ul>
</body>
</html>
Doc/FAQ.html deleted 100644 → 0
View file @ 5a1c4958
<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>FAQ.html</title></head>
<body>
<center> <h1> <hr width="100%">Cython FAQ
<hr width="100%"></h1>
</center>
<h2> Contents</h2>
<ul>
<li> <b><a href="#CallCAPI">How do I call Python/C API routines?</a></b></li>
<li> <b><a href="#NullBytes">How do I convert a C string containing null
bytes to a Python string?</a></b></li>
<li> <b><a href="#NumericAccess">How do I access the data inside a Numeric
array object?</a></b></li>
<li><b><a href="#Rhubarb">Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</a></b></li><li><a style="font-weight: bold;" href="#Quack">Python says my extension type has no method called 'quack', but I know it does. What gives?</a><br>
</li>
</ul>
<hr width="100%"> <h2> <a name="CallCAPI"></a>How do I call Python/C API routines?</h2>
Declare them as C functions inside a <tt>cdef extern from</tt> block.
Use the type name <tt>object</tt> for any parameters and return types which
are Python object references. Don't use the word <tt>const</tt> anywhere.
Here is an example which defines and uses the <tt>PyString_FromStringAndSize</tt> routine:
<blockquote><tt>cdef extern from "Python.h":</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; object PyString_FromStringAndSize(char *, int)</tt> <p><tt>cdef char buf[42]</tt> <br>
<tt>my_string = PyString_FromStringAndSize(buf, 42)</tt></p>
</blockquote>
<h2> <a name="NullBytes"></a>How do I convert a C string containing null
bytes to a Python string?</h2>
Put in a declaration for the <tt>PyString_FromStringAndSize</tt> API routine
and use that<tt>.</tt> See <a href="#CallCAPI">How do I call Python/C API
routines?</a> <h2> <a name="NumericAccess"></a>How do I access the data inside a Numeric
array object?</h2>
Use a <tt>cdef extern from</tt> block to include the Numeric header file
and declare the array object as an external extension type. The following
code illustrates how to do this:
<blockquote><tt>cdef extern from "Numeric/arrayobject.h":</tt> <p><tt>&nbsp;&nbsp;&nbsp; struct PyArray_Descr:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int type_num, elsize</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char type</tt> </p>
<p><tt>&nbsp;&nbsp;&nbsp; ctypedef class Numeric.ArrayType [object PyArrayObject]</tt><tt>:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef char *data</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int nd</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int *dimensions,
*strides</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef object base</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef PyArray_Descr *descr</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int flags<br>
</tt></p>
</blockquote>
<p>For more information about external extension types, see the <a href="extension_types.html#ExternalExtTypes">"External Extension Types"</a>
section of the <a href="extension_types.html">"Extension Types"</a> documentation
page.<br>
<tt> </tt> </p>
<h2><a name="Rhubarb"></a>Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</h2>
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,<br>
for example,<br>
<blockquote><tt>cdef class Vegetables:</tt><br>
<tt>&nbsp; &nbsp; cdef int rhubarb</tt><br>
<br>
<tt>...</tt><br>
<tt>cdef Vegetables veg</tt><br>
<tt>veg.rhubarb = 42</tt><br>
</blockquote>
Also see the <a href="extension_types.html#ExtTypeAttrs">"Attributes"</a>
section of the <a href="extension_types.html">"Extension
Types"</a> documentation page.<br>
<h2><a name="Quack"></a>Python says my extension type has no method called 'quack', but I know it does. What gives?</h2>
You may have declared the method using <span style="font-family: monospace;">cdef</span> instead of <span style="font-family: monospace;">def</span>. Only functions and methods declared with <span style="font-family: monospace;">def</span> are callable from Python code.<br>
---
</body></html>
\ No newline at end of file
Doc/extension_types.html deleted 100644 → 0
View file @ 5a1c4958
This diff is collapsed.
Doc/index.html deleted 100644 → 0
View file @ 5a1c4958
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]">
<title>Cython - Front Page</title>
</head>
<body>
&nbsp;
<table CELLSPACING=0 CELLPADDING=10 WIDTH="500" >
<tr>
<td VALIGN=TOP BGCOLOR="#FF9218"><font face="Arial,Helvetica"><font size=+4>Cython</font></font></td>
<td ALIGN=RIGHT VALIGN=TOP WIDTH="200" BGCOLOR="#5DBACA"><font face="Arial,Helvetica"><font size=+1>A
smooth blend of the finest Python&nbsp;</font></font>
<br><font face="Arial,Helvetica"><font size=+1>with the unsurpassed power&nbsp;</font></font>
<br><font face="Arial,Helvetica"><font size=+1>of raw C.</font></font></td>
</tr>
</table>
<blockquote><font size=+1>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.</font></blockquote>
<h1>
<font face="Arial,Helvetica"><font size=+2>Documentation</font></font></h1>
<blockquote>
<h2>
<font face="Arial,Helvetica"><font size=+1><a href="About.html">About Cython</a></font></font></h2>
<blockquote><font size=+1>Read this to find out what Cython is all about
and what it can do for you.</font></blockquote>
<h2>
<font face="Arial,Helvetica"><font size=+1><a href="overview.html">Language
Overview</a></font></font></h2>
<blockquote><font size=+1>A description of all the features of the Cython
language. This is the closest thing to a reference manual in existence
yet.</font></blockquote>
<h2>
<font face="Arial,Helvetica"><font size=+1><a href="FAQ.html">FAQ</a></font></font></h2>
<blockquote><font size=+1>Want to know how to do something in Cython? Check
here first<font face="Arial,Helvetica">.</font></font></blockquote>
</blockquote>
<h1>
<font face="Arial,Helvetica"><font size=+2>Other Resources</font></font></h1>
<blockquote>
<h2>
<font face="Arial,Helvetica"><font size=+1><a href="http://www.cosc.canterbury.ac.nz/~greg/python/Cython/mpj17-pyrex-guide/">Michael's
Quick Guide to Cython</a></font></font></h2>
<blockquote><font size=+1>This tutorial-style presentation will take you
through the steps of creating some Cython modules to wrap existing C libraries.
Contributed by <a href="mailto:mpj17@cosc.canterbury.ac.nz">Michael JasonSmith</a>.</font></blockquote>
<h2>
<font face="Arial,Helvetica"><font size=+1><a href="mailto:greg@cosc.canterbury.ac.nz">Mail
to the Author</a></font></font></h2>
<blockquote><font size=+1>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:<font face="Arial,Helvetica"> </font><tt><a href="mailto:greg@cosc.canterbury.ac.nz">greg@cosc.canterbury.ac.nz</a></tt></font></blockquote>
</blockquote>
</body>
</html>
Doc/overview.html deleted 100644 → 0
View file @ 5a1c4958
This diff is collapsed.
Doc/primes.c deleted 100644 → 0
View file @ 5a1c4958
#include "Python.h"
static PyObject *__Pyx_UnpackItem(PyObject *, int);
static int __Pyx_EndUnpack(PyObject *, int);
static int __Pyx_PrintItem(PyObject *);
static int __Pyx_PrintNewline(void);
static void __Pyx_ReRaise(void);
static void __Pyx_RaiseWithTraceback(PyObject *, PyObject *, PyObject *);
static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list);
static PyObject *__Pyx_GetExcValue(void);
static PyObject *__Pyx_GetName(PyObject *dict, char *name);
static PyObject *__pyx_m;
static PyObject *__pyx_d;
static PyObject *__pyx_b;
PyObject *__pyx_f_primes(PyObject *__pyx_self, PyObject *__pyx_args); /*proto*/
PyObject *__pyx_f_primes(PyObject *__pyx_self, PyObject *__pyx_args) {
int __pyx_v_kmax;
int __pyx_v_n;
int __pyx_v_k;
int __pyx_v_i;
int (__pyx_v_p[1000]);
PyObject *__pyx_v_result;
PyObject *__pyx_r;
PyObject *__pyx_1 = 0;
int __pyx_2;
int __pyx_3;
int __pyx_4;
PyObject *__pyx_5 = 0;
PyObject *__pyx_6 = 0;
if (!PyArg_ParseTuple(__pyx_args, "i", &__pyx_v_kmax)) return 0;
__pyx_v_result = Py_None; Py_INCREF(__pyx_v_result);
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":2 */
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":3 */
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":4 */
__pyx_1 = PyList_New(0); if (!__pyx_1) goto __pyx_L1;
Py_DECREF(__pyx_v_result);
__pyx_v_result = __pyx_1;
__pyx_1 = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":5 */
__pyx_2 = (__pyx_v_kmax > 1000);
if (__pyx_2) {
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":6 */
__pyx_v_kmax = 1000;
goto __pyx_L2;
}
__pyx_L2:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":7 */
__pyx_v_k = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":8 */
__pyx_v_n = 2;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":9 */
while (1) {
__pyx_L3:;
__pyx_2 = (__pyx_v_k < __pyx_v_kmax);
if (!__pyx_2) break;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":10 */
__pyx_v_i = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":11 */
while (1) {
__pyx_L5:;
if (__pyx_3 = (__pyx_v_i < __pyx_v_k)) {
__pyx_3 = ((__pyx_v_n % (__pyx_v_p[__pyx_v_i])) != 0);
}
if (!__pyx_3) break;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":12 */
__pyx_v_i = (__pyx_v_i + 1);
}
__pyx_L6:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":13 */
__pyx_4 = (__pyx_v_i == __pyx_v_k);
if (__pyx_4) {
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":14 */
(__pyx_v_p[__pyx_v_k]) = __pyx_v_n;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":15 */
__pyx_v_k = (__pyx_v_k + 1);
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":16 */
__pyx_1 = PyObject_GetAttrString(__pyx_v_result, "append"); if (!__pyx_1) goto __pyx_L1;
__pyx_5 = PyInt_FromLong(__pyx_v_n); if (!__pyx_5) goto __pyx_L1;
__pyx_6 = PyTuple_New(1); if (!__pyx_6) goto __pyx_L1;
PyTuple_SET_ITEM(__pyx_6, 0, __pyx_5);
__pyx_5 = 0;
__pyx_5 = PyObject_CallObject(__pyx_1, __pyx_6); if (!__pyx_5) goto __pyx_L1;
Py_DECREF(__pyx_6); __pyx_6 = 0;
Py_DECREF(__pyx_5); __pyx_5 = 0;
goto __pyx_L7;
}
__pyx_L7:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":17 */
__pyx_v_n = (__pyx_v_n + 1);
}
__pyx_L4:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":18 */
Py_INCREF(__pyx_v_result);
__pyx_r = __pyx_v_result;
goto __pyx_L0;
__pyx_r = Py_None; Py_INCREF(__pyx_r);
goto __pyx_L0;
__pyx_L1:;
Py_XDECREF(__pyx_1);
Py_XDECREF(__pyx_5);
Py_XDECREF(__pyx_6);
__pyx_r = 0;
__pyx_L0:;
Py_DECREF(__pyx_v_result);
return __pyx_r;
}
static struct PyMethodDef __pyx_methods[] = {
{"primes", (PyCFunction)__pyx_f_primes, METH_VARARGS, 0},
{0, 0, 0, 0}
};
void initprimes(void); /*proto*/
void initprimes(void) {
__pyx_m = Py_InitModule4("primes", __pyx_methods, 0, 0, PYTHON_API_VERSION);
__pyx_d = PyModule_GetDict(__pyx_m);
__pyx_b = PyImport_AddModule("__builtin__");
PyDict_SetItemString(__pyx_d, "__builtins__", __pyx_b);
}
/* Runtime support code */
Doc/sharing.html deleted 100644 → 0
View file @ 5a1c4958
This diff is collapsed.
Doc/special_methods.html deleted 100644 → 0
View file @ 5a1c4958
This diff is collapsed.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7