README.rst
1GRPC Python Cython layer
2========================
3
4Package for the GRPC Python Cython layer.
5
6What is Cython?
7---------------
8
9Cython is both a superset of the Python language with extensions for dealing
10with C types and a tool that transpiles this superset into C code. It provides
11convenient means of statically typing expressions and of converting Python
12strings to pointers (among other niceties), thus dramatically smoothing the
13Python/C interop by allowing fluid use of APIs in both from the same source.
14See the wonderful `Cython website`_.
15
16Why Cython?
17-----------
18
19- **Python 2 and 3 support**
20 Cython generated C code has precompiler macros to target both Python 2 and
21 Python 3 C APIs, even while acting as a superset of just the Python 2
22 language (e.g. using ``basestring``).
23- **Significantly less semantic noise**
24 A lot of CPython code is just glue, especially human-error-prone
25 ``Py_INCREF``-ing and ``Py_DECREF``-ing around error handlers and such.
26 Cython takes care of that automagically.
27- **Possible PyPy support**
28 One of the major developments in Cython over the past few years was the
29 addition of support for PyPy. We might soon be able to provide such support
30 ourselves through our use of Cython.
31- **Less Python glue code**
32 There existed several adapter layers in and around the original CPython code
33 to smooth the surface exposed to Python due to how much trouble it was to
34 make such a smooth surface via the CPython API alone. Cython makes writing
35 such a surface incredibly easy, so these adapter layers may be removed.
36
37Implications for Users
38----------------------
39
40Nothing additional will be required for users. PyPI packages will contain
41Cython generated C code and thus not necessitate a Cython installation.
42
43Implications for GRPC Developers
44--------------------------------
45
46A typical edit-compile-debug cycle now requires Cython. We install Cython in
47the ``virtualenv`` generated for the Python tests in this repository, so
48initial test runs may take an extra 2+ minutes to complete. Subsequent test
49runs won't reinstall ``Cython`` (unless required versions change and the
50``virtualenv`` doesn't have installed versions that satisfy the change).
51
52.. _`Cython website`: http://cython.org/
53