From: ggellner@encolpuis Date: Tue, 30 Sep 2008 01:24:48 +0000 (-0400) Subject: Fixed javascript suffix issue that broke search. Added pyximport to compilation docs... X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=40f8bf81d9ee00bcfcd8644b06fef5d87c502107;p=cython.git Fixed javascript suffix issue that broke search. Added pyximport to compilation docs. Removed module and index links. --- diff --git a/conf.py b/conf.py index 1a0ea082..a86633d4 100644 --- a/conf.py +++ b/conf.py @@ -32,7 +32,7 @@ import cython_highlighting extensions = ['ipython_console_highlighting', 'cython_highlighting'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] +templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -42,7 +42,7 @@ master_doc = 'index' # General substitutions. project = 'Cython' -copyright = '2008, Stefan Behnel, Robert Bradshaw, William Stein, Gary Furnish, Dag Seljebotn, Gabriel Gellner, Greg Ewing' +copyright = '2008, Stefan Behnel, Robert Bradshaw, Grew Ewing, William Stein, Gary Furnish, Dag Seljebotn, Gabriel Gellner' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -50,7 +50,7 @@ copyright = '2008, Stefan Behnel, Robert Bradshaw, William Stein, Gary Furnish, # The short X.Y version. version = '0.9.8.1' # The full version, including alpha/beta/rc tags. -release = '0.9.8.1' +release = '0.9.8.1.1' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -79,6 +79,9 @@ pygments_style = 'sphinx' # Options for HTML output # ----------------------- +# suffix for generated files +html_file_suffix = '.html' + # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. @@ -114,7 +117,10 @@ html_favicon = '_static/favicon.ico' #html_additional_pages = {} # If false, no module index is generated. -#html_use_modindex = True +html_use_modindex = False + +# Don't generate and index +html_use_index = False # If true, the reST sources are included in the HTML build as _sources/. #html_copy_source = True diff --git a/docs/source_files_and_compilation.rst b/docs/source_files_and_compilation.rst index c5535613..9ce98973 100644 --- a/docs/source_files_and_compilation.rst +++ b/docs/source_files_and_compilation.rst @@ -102,3 +102,87 @@ we would have instead:: ext_modules = [Extension("example", ["example.c"])] ) + +.. _pyximport: + +Pyximport +=========== + +.. TODO add some text about how this is Paul Prescods code. Also change the + tone to be more universal (i.e. remove all the I statements) + +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 :file:`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 :file:`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 the first line above to your :file:`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" + +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 :file:`foo.pyx` then you should make +another file in the same directory called :file:`foo.pyxdep`. The +:file:`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 +------------------------------------ + +I don't think that Python's :func:`reload` will do anything for changed +``.so``'s on some (all?) platforms. It would require some (easy) +experimentation that I haven't gotten around to. But reload is rarely used in +applications outside of the Python interactive interpreter and certainly not +used much for C extension modules. Info about Windows +``_ + +``setup.py install`` does not modify :file:`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. + diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 3ffdd5ae..d13d814a 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -65,6 +65,10 @@ Congratulations! You now know how to build a Cython extension. But So Far this example doesn't really give a feeling why one would ever want to use Cython, so lets create a more realistic example. +:mod:`pyximport`: Cython Compilation the Easy Way +================================================== + + Fibonacci Fun ============== diff --git a/examples/tutorial/great_circle/c1.pyx b/examples/tutorial/great_circle/c1.pyx new file mode 100644 index 00000000..c0694a23 --- /dev/null +++ b/examples/tutorial/great_circle/c1.pyx @@ -0,0 +1,12 @@ +import math + +def great_circle(lon1, lat1, lon2, lat2): + radius = 3956 # miles + x = math.pi/180.0 + + a = (90.0 - lat1)*x + b = (90.0 - lat2)*x + theta = (lon2 - lon1)*x + c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta)) + + return radius*c diff --git a/examples/tutorial/great_circle/c2.pyx b/examples/tutorial/great_circle/c2.pyx new file mode 100644 index 00000000..eb4915ca --- /dev/null +++ b/examples/tutorial/great_circle/c2.pyx @@ -0,0 +1,13 @@ +import math + +def great_circle(double lon1, double lat1, double lon2, double lat2): + cdef double radius = 3956 # miles + cdef double x = math.pi/180.0 + cdef double a, b, theta, c + + a = (90.0 - lat1)*x + b = (90.0 - lat2)*x + theta = (lon2 - lon1)*x + c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta)) + + return radius*c diff --git a/examples/tutorial/great_circle/p1.py b/examples/tutorial/great_circle/p1.py new file mode 100644 index 00000000..c0694a23 --- /dev/null +++ b/examples/tutorial/great_circle/p1.py @@ -0,0 +1,12 @@ +import math + +def great_circle(lon1, lat1, lon2, lat2): + radius = 3956 # miles + x = math.pi/180.0 + + a = (90.0 - lat1)*x + b = (90.0 - lat2)*x + theta = (lon2 - lon1)*x + c = math.acos(math.cos(a)*math.cos(b) + math.sin(a)*math.sin(b)*math.cos(theta)) + + return radius*c