diff --git a/Demos/Readme_demos.rst b/Demos/README.rst similarity index 62% rename from Demos/Readme_demos.rst rename to Demos/README.rst index f0eb8c1376f..959b71f3853 100644 --- a/Demos/Readme_demos.rst +++ b/Demos/README.rst @@ -1,25 +1,25 @@ -* To run demos do:: +To run demos do:: cd Demos make test - which runs run_primes.py, run_numeric_demo.py, run_spam.py, - integrate_timing.py, callback/runcheese.py and embed/embedded +which runs ``run_primes.py``, ``run_numeric_demo.py``, ``run_spam.py``, +``integrate_timing.py``, ``callback/runcheese.py`` and ``embed/embedded`` -* For other demos:: +For other demos:: cd libraries python setup.py build_ext --inplace python -c 'import call_mymath;print(call_mymath.call_sinc(1))' - To run one of the benchmarks for 10 iterations to compare cython and python timings:: +To run one of the benchmarks for 10 iterations to compare cython and python timings:: cd benchmarks python setup.py build_ext --inplace python nqueens.py -n 10 python -c 'import nqueens;print(nqueens.test_n_queens(10))' - To demo cython/bin/cython_freeze:: +To demo ``cython/bin/cython_freeze``:: make ./nCr 10 5 diff --git a/Demos/callback/README.txt b/Demos/callback/README.rst similarity index 60% rename from Demos/callback/README.txt rename to Demos/callback/README.rst index 8e8abdf29f5..00036688f59 100644 --- a/Demos/callback/README.txt +++ b/Demos/callback/README.rst @@ -2,11 +2,11 @@ This example demonstrates how you can wrap a C API that has a callback interface, so that you can pass Python functions to it as callbacks. -The files cheesefinder.h and cheesefinder.c +The files ``cheesefinder.h`` and ``cheesefinder.c`` represent the C library to be wrapped. -The file cheese.pyx is the Pyrex module +The file ``cheese.pyx`` is the Cython module which wraps it. -The file run_cheese.py demonstrates how to +The file ``run_cheese.py`` demonstrates how to call the wrapper. diff --git a/Demos/embed/README b/Demos/embed/README.rst similarity index 74% rename from Demos/embed/README rename to Demos/embed/README.rst index 9a16c8ed52a..4cf30db85eb 100644 --- a/Demos/embed/README +++ b/Demos/embed/README.rst @@ -2,4 +2,4 @@ This example demonstrates how Cython-generated code can be called directly from a main program written in C. The Windows makefiles were contributed by -Duncan Booth . +Duncan Booth: Duncan.Booth@SuttonCourtenay.org.uk. diff --git a/Demos/freeze/README.txt b/Demos/freeze/README.rst similarity index 86% rename from Demos/freeze/README.txt rename to Demos/freeze/README.rst index 18e045237c6..31c4b4c129c 100644 --- a/Demos/freeze/README.txt +++ b/Demos/freeze/README.rst @@ -1,13 +1,14 @@ NAME ==== -cython_freeze - create a C file for embedding Cython modules +**cython_freeze** - create a C file for embedding Cython modules SYNOPSIS ======== +:: -cython_freeze [-o outfile] [-p] module [...] + cython_freeze [-o outfile] [-p] module [...] DESCRIPTION @@ -32,21 +33,20 @@ modules, but it requires another C source file to be created. OPTIONS ======= +:: --o FILE, --outfile=FILE write output to FILE instead of standard output --p, --pymain do not automatically run the first module as __main__ + -o FILE, --outfile=FILE write output to FILE instead of standard output + -p, --pymain do not automatically run the first module as __main__ EXAMPLE ======= -In the Demos/freeze directory, there exist two Cython modules: +In the ``Demos/freeze`` directory, there exist two Cython modules: -lcmath.pyx - A module that interfaces with the -lm library. +* ``lcmath.pyx``: A module that interfaces with the -lm library. -combinatorics.pyx - A module that implements n-choose-r using lcmath. +* ``combinatorics.pyx``: A module that implements n-choose-r using lcmath. Both modules have the Python idiom ``if __name__ == "__main__"``, which only execute if that module is the "main" module. If run as main, lcmath prints the diff --git a/bin/cython_freeze b/bin/cython_freeze index f22e072246d..e5cef758b17 100755 --- a/bin/cython_freeze +++ b/bin/cython_freeze @@ -3,7 +3,7 @@ Create a C file for embedding one or more Cython source files. Requires Cython 0.11.2 (or perhaps newer). -See Demos/freeze/README.txt for more details. +See Demos/freeze/README.rst for more details. """ from __future__ import print_function diff --git a/pyximport/README b/pyximport/README deleted file mode 100644 index 9395974237e..00000000000 --- a/pyximport/README +++ /dev/null @@ -1,73 +0,0 @@ - == Pyximport == - -Download: pyx-import-1.0.tar.gz - - -Pyrex is a compiler. Therefore it is natural that people tend to go -through an edit/compile/test cycle with Pyrex modules. But my personal -opinion is that one of the deep insights in Python's implementation is -that a language can be compiled (Python modules are compiled to .pyc) -files and hide that compilation process from the end-user so that they -do not have to worry about it. Pyximport does this for Pyrex modules. -For instance if you write a Pyrex module called "foo.pyx", with -Pyximport you can import it in a regular Python module like this: - - -import pyximport; pyximport.install() -import foo - -Doing so will result in the compilation of foo.pyx (with appropriate -exceptions if it has an error in it). - -If you would always like to import pyrex files without building them -specially, you can also add the first line above to your sitecustomize.py. -That will install the hook every time you run Python. Then you can use -Pyrex modules just with simple import statements. I like to test my -Pyrex modules like this: - - -python -c "import foo" - -See help(pyximport.install) to learn its options for controlling the -default behavior of "import" and "reload". - - == Dependency Handling == - -In Pyximport 1.1 it is possible to declare that your module depends on -multiple files, (likely ".h" and ".pxd" files). If your Pyrex module is -named "foo" and thus has the filename "foo.pyx" then you should make -another file in the same directory called "foo.pyxdep". The -"modname.pyxdep" file can be a list of filenames or "globs" (like -"*.pxd" or "include/*.h"). Each filename or glob must be on a separate -line. Pyximport will check the file date for each of those files before -deciding whether to rebuild the module. In order to keep track of the -fact that the dependency has been handled, Pyximport updates the -modification time of your ".pyx" source file. Future versions may do -something more sophisticated like informing distutils of the -dependencies directly. - - == Limitations == - -Pyximport does not give you any control over how your Pyrex file is -compiled. Usually the defaults are fine. You might run into problems if -you wanted to write your program in half-C, half-Pyrex and build them -into a single library. Pyximport 1.2 will probably do this. - -Pyximport does not hide the Distutils/GCC warnings and errors generated -by the import process. Arguably this will give you better feedback if -something went wrong and why. And if nothing went wrong it will give you -the warm fuzzy that pyximport really did rebuild your module as it was -supposed to. - - == For further thought and discussion == - -"setup.py install" does not modify sitecustomize.py for you. Should it? -Modifying Python's "standard interpreter" behaviour may be more than -most people expect of a package they install.. - -Pyximport puts your ".c" file beside your ".pyx" file (analogous to -".pyc" beside ".py"). But it puts the platform-specific binary in a -build directory as per normal for Distutils. If I could wave a magic -wand and get Pyrex or distutils or whoever to put the build directory I -might do it but not necessarily: having it at the top level is VERY -HELPFUL for debugging Pyrex problems. diff --git a/pyximport/README.rst b/pyximport/README.rst new file mode 100644 index 00000000000..0e91ac47601 --- /dev/null +++ b/pyximport/README.rst @@ -0,0 +1,71 @@ +Pyximport +========= + +Cython is a compiler. Therefore it is natural that people tend to go +through an edit/compile/test cycle with Cython modules. But my personal +opinion is that one of the deep insights in Python's implementation is +that a language can be compiled (Python modules are compiled to .pyc) +files and hide that compilation process from the end-user so that they +do not have to worry about it. Pyximport does this for Cython modules. +For instance if you write a Cython module called ``foo.pyx``, with +Pyximport you can import it in a regular Python module like this:: + + import pyximport; pyximport.install() + import foo + +Doing so will result in the compilation of ``foo.pyx`` (with appropriate +exceptions if it has an error in it). + +If you would always like to import Cython files without building them +specially, you can also add the first line above to your sitecustomize.py. +That will install the hook every time you run Python. Then you can use +Cython modules just with simple import statements. I like to test my +Cython modules like this:: + + python -c "import foo" + +See help(pyximport.install) to learn its options for controlling the +default behavior of ``import`` and ``reload``. + +Dependency Handling +------------------- + +In Pyximport 1.1 it is possible to declare that your module depends on +multiple files, (likely ``.h`` and ``.pxd`` files). If your Cython module is +named ``foo`` and thus has the filename ``foo.pyx`` then you should make +another file in the same directory called ``foo.pyxdep``. The +``modname.pyxdep`` file can be a list of filenames or ``globs`` (like +``*.pxd`` or ``include/*.h``). Each filename or glob must be on a separate +line. Pyximport will check the file date for each of those files before +deciding whether to rebuild the module. In order to keep track of the +fact that the dependency has been handled, Pyximport updates the +modification time of your ``.pyx`` source file. Future versions may do +something more sophisticated like informing distutils of the +dependencies directly. + +Limitations +----------- +Pyximport does not give you any control over how your Cython file is +compiled. Usually the defaults are fine. You might run into problems if +you wanted to write your program in half-C, half-Cython and build them +into a single library. Pyximport 1.2 will probably do this. + +Pyximport does not hide the Distutils/GCC warnings and errors generated +by the import process. Arguably this will give you better feedback if +something went wrong and why. And if nothing went wrong it will give you +the warm fuzzy that pyximport really did rebuild your module as it was +supposed to. + +For further thought and discussion +---------------------------------- + +``setup.py install`` does not modify ``sitecustomize.py`` for you. Should it? +Modifying Python's "standard interpreter" behaviour may be more than +most people expect of a package they install.. + +Pyximport puts your ``.c`` file beside your ``.pyx`` file (analogous to +``.pyc`` beside ``.py``). But it puts the platform-specific binary in a +build directory as per normal for Distutils. If I could wave a magic +wand and get Cython or distutils or whoever to put the build directory I +might do it but not necessarily: having it at the top level is VERY +HELPFUL for debugging Cython problems.