diff options
Diffstat (limited to 'docs/src/quickstart/build.rst')
| -rw-r--r-- | docs/src/quickstart/build.rst | 68 |
1 files changed, 45 insertions, 23 deletions
diff --git a/docs/src/quickstart/build.rst b/docs/src/quickstart/build.rst index 628ed2604..3cbcfa087 100644 --- a/docs/src/quickstart/build.rst +++ b/docs/src/quickstart/build.rst @@ -3,23 +3,27 @@ Building Cython code Cython code must, unlike Python, be compiled. This happens in two stages: - - A ``.pyx`` file is compiled by Cython to a ``.c`` file, containing + - A ``.pyx`` or ``.py`` file is compiled by Cython to a ``.c`` file, containing the code of a Python extension module. - The ``.c`` file is compiled by a C compiler to a ``.so`` file (or ``.pyd`` on Windows) which can be ``import``-ed directly into a Python session. - Distutils or setuptools take care of this part. + `setuptools <https://setuptools.readthedocs.io/>`_ takes care of this part. Although Cython can call them for you in certain cases. - -To understand fully the Cython + distutils/setuptools build process, + +To understand fully the Cython + setuptools build process, one may want to read more about `distributing Python modules <https://docs.python.org/3/distributing/index.html>`_. There are several ways to build Cython code: - - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way. + - Write a setuptools ``setup.py``. This is the normal and recommended way. + - Run the ``cythonize`` command-line utility. This is a good approach for + compiling a single Cython source file directly to an extension. + A source file can be built "in place" (so that the extension module is created + next to the source file, ready to be imported) with ``cythonize -i filename.pyx``. - Use :ref:`Pyximport<pyximport>`, importing Cython ``.pyx`` files as if they - were ``.py`` files (using distutils to compile and build in the background). + were ``.py`` files (using setuptools to compile and build in the background). This method is easier than writing a ``setup.py``, but is not very flexible. So you'll need to write a ``setup.py`` if, for example, you need certain compilations options. - Run the ``cython`` command-line utility manually to produce the ``.c`` file @@ -30,12 +34,12 @@ There are several ways to build Cython code: both of which allow Cython code inline. This is the easiest way to get started writing Cython code and running it. -Currently, using distutils or setuptools is the most common way Cython files are built and distributed. +Currently, using setuptools is the most common way Cython files are built and distributed. The other methods are described in more detail in the :ref:`compilation` section of the reference manual. -Building a Cython module using distutils ----------------------------------------- +Building a Cython module using setuptools +----------------------------------------- Imagine a simple "hello world" script in a file ``hello.pyx``: @@ -49,11 +53,10 @@ To build, run ``python setup.py build_ext --inplace``. Then simply start a Python session and do ``from hello import say_hello_to`` and use the imported function as you see fit. -One caveat if you use setuptools instead of distutils, the default -action when running ``python setup.py install`` is to create a zipped -``egg`` file which will not work with ``cimport`` for ``pxd`` files -when you try to use them from a dependent package. -To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``. +One caveat: the default action when running ``python setup.py install`` is to +create a zipped ``egg`` file which will not work with ``cimport`` for ``pxd`` +files when you try to use them from a dependent package. To prevent this, +include ``zip_safe=False`` in the arguments to ``setup()``. .. _jupyter-notebook: @@ -64,7 +67,7 @@ Cython can be used conveniently and interactively from a web browser through the Jupyter notebook. To install Jupyter notebook, e.g. into a virtualenv, use pip: -.. sourcecode:: bash +.. code-block:: bash (venv)$ pip install jupyter (venv)$ jupyter notebook @@ -74,14 +77,32 @@ and load the ``Cython`` extension from within the Jupyter notebook:: %load_ext Cython -Then, prefix a cell with the ``%%cython`` marker to compile it:: +Then, prefix a cell with the ``%%cython`` marker to compile it + +.. tabs:: + + .. group-tab:: Pure Python + + .. code-block:: python + + %%cython + + a: cython.int = 0 + for i in range(10): + a += i + print(a) + + + .. group-tab:: Cython + + .. code-block:: python - %%cython + %%cython - cdef int a = 0 - for i in range(10): - a += i - print(a) + cdef int a = 0 + for i in range(10): + a += i + print(a) You can show Cython's code analysis by passing the ``--annotate`` option:: @@ -104,5 +125,6 @@ Using the Sage notebook functions defined in a Cython cell imported into the running session. -.. [Jupyter] http://jupyter.org/ -.. [Sage] W. Stein et al., Sage Mathematics Software, http://www.sagemath.org/ +.. [Jupyter] https://jupyter.org/ +.. + [Sage] W. Stein et al., Sage Mathematics Software, https://www.sagemath.org/ |