welcome.rst 3.48 KB
Newer Older
Peter Alexander's avatar
Peter Alexander committed
1 2 3 4 5
.. highlight:: cython

.. _overview:

********
Peter Alexander's avatar
Peter Alexander committed
6
Welcome!
Peter Alexander's avatar
Peter Alexander committed
7 8 9 10 11 12 13 14 15 16 17 18 19
********

===============
What is Cython?
===============

Cython is a programming language based on Python
with extra syntax to provide static type declarations.

================
What Does It Do?
================

20
It takes advantage of the benefits of Python while allowing one to achieve the speed of C.
Peter Alexander's avatar
Peter Alexander committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

============================
How Exactly Does It Do That?
============================

The source code gets translated into optimized C/C++
code and compiled as Python extension modules.

This allows for both very fast program execution and tight
integration with external C libraries, while keeping
up the high *programmer productivity* for which the
Python language is well known.

=============
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
41 42 43 44 45
C. Other major implementations use:

:Java: Jython [#Jython]_
:C#: IronPython [#IronPython]_)
:Python itself: PyPy [#PyPy]_
Peter Alexander's avatar
Peter Alexander committed
46 47 48

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
49
C, especially for programmers who are more fluent in a
Peter Alexander's avatar
Peter Alexander committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
high-level language like Python than in a do-it-yourself
language like C.

Originally based on the well-known Pyrex [#Pyrex]_, the
Cython project has approached this problem by means
of a source code compiler that translates Python code
to equivalent C code. This code is executed within the
CPython runtime environment, but at the speed of
compiled C and with the ability to call directly into C
libraries.

At the same time, it keeps the original interface of the Python source code, which makes it directly
usable from Python code. These two-fold characteristics enable Cython’s two major use cases:

#. Extending the CPython interpreter with fast binary modules, and
#. Interfacing Python code with external C libraries.

While Cython can compile (most) regular Python
code, the generated C code usually gains major (and
sometime impressive) speed improvements from optional static type declarations for both Python and
C types. These allow Cython to assign C semantics to
71
parts of the code, and to translate them into very efficient C code.
Peter Alexander's avatar
Peter Alexander committed
72 73 74 75 76

Type declarations can therefore be used
for two purposes:

#. For moving code sections from dynamic Python semantics into static-and-fast C semantics, but also for..
77
#. Directly manipulating types defined in external libraries. Cython thus merges the two worlds into a very broadly applicable programming language.
Peter Alexander's avatar
Peter Alexander committed
78 79 80 81 82 83 84

==================
Where Do I Get It?
==================

Well.. at `cython.org <http://cython.org>`_.. of course!

Peter Alexander's avatar
Peter Alexander committed
85
======================
86 87 88
How Do I Report a Bug?
======================

Peter Alexander's avatar
Peter Alexander committed
89
=================================
90 91 92
I Want To Make A Feature Request!
=================================

Peter Alexander's avatar
Peter Alexander committed
93 94 95
============================================
Is There a Mail List? How Do I Contact You?
============================================
96 97 98



Peter Alexander's avatar
Peter Alexander committed
99 100
.. rubric:: Footnotes

101
.. [#Jython] **Jython:** \J. Huginin, B. Warsaw, F. Bock, et al., Jython: Python for the Java platform, http://www.jython.org
Peter Alexander's avatar
Peter Alexander committed
102 103 104 105

.. [#IronPython] **IronPython:** Jim Hugunin et al., http://www.codeplex.com/IronPython.


106
.. [#PyPy] **PyPy:** The PyPy Group, PyPy: a Python implementation written in Python, http://pypy.org
Peter Alexander's avatar
Peter Alexander committed
107 108 109 110 111

.. [#Pyrex] **Pyrex:** G. Ewing, Pyrex: C-Extensions for Python, http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/



112 113 114 115 116 117 118 119 120 121