Initial checkin of gRPC to third_party/

third_party/grpc/src/python/grpcio/grpc/_cython/README.rst

Index: third_party/grpc/src/python/grpcio/grpc/_cython/README.rst
diff --git a/third_party/grpc/src/python/grpcio/grpc/_cython/README.rst b/third_party/grpc/src/python/grpcio/grpc/_cython/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c0e66734e875a3254c5981e94c0ccc8ea511a0d1
--- /dev/null
+++ b/third_party/grpc/src/python/grpcio/grpc/_cython/README.rst
@@ -0,0 +1,52 @@
+GRPC Python Cython layer
+========================
+
+Package for the GRPC Python Cython layer.
+
+What is Cython?
+---------------
+
+Cython is both a superset of the Python language with extensions for dealing
+with C types and a tool that transpiles this superset into C code. It provides
+convenient means of statically typing expressions and of converting Python
+strings to pointers (among other niceties), thus dramatically smoothing the
+Python/C interop by allowing fluid use of APIs in both from the same source.
+See the wonderful `Cython website`_.
+
+Why Cython?
+-----------
+
+- **Python 2 and 3 support**
+  Cython generated C code has precompiler macros to target both Python 2 and
+  Python 3 C APIs, even while acting as a superset of just the Python 2
+  language (e.g. using ``basestring``).
+- **Significantly less semantic noise**
+  A lot of CPython code is just glue, especially human-error-prone
+  ``Py_INCREF``-ing and ``Py_DECREF``-ing around error handlers and such.
+  Cython takes care of that automagically.
+- **Possible PyPy support**
+  One of the major developments in Cython over the past few years was the
+  addition of support for PyPy. We might soon be able to provide such support
+  ourselves through our use of Cython.
+- **Less Python glue code**
+  There existed several adapter layers in and around the original CPython code
+  to smooth the surface exposed to Python due to how much trouble it was to
+  make such a smooth surface via the CPython API alone. Cython makes writing
+  such a surface incredibly easy, so these adapter layers may be removed.
+
+Implications for Users
+----------------------
+
+Nothing additional will be required for users. PyPI packages will contain
+Cython generated C code and thus not necessitate a Cython installation.
+
+Implications for GRPC Developers
+--------------------------------
+
+A typical edit-compile-debug cycle now requires Cython. We install Cython in
+the ``virtualenv`` generated for the Python tests in this repository, so
+initial test runs may take an extra 2+ minutes to complete.  Subsequent test
+runs won't reinstall ``Cython`` (unless required versions change and the
+``virtualenv`` doesn't have installed versions that satisfy the change).
+
+.. _`Cython website`: http://cython.org/