pyximport/README

   1
   2  == Pyximport ==
   3
   4 Download: pyx-import-1.0.tar.gz
   5 <http://www.prescod.net/pyximport/pyximport-1.0.tar.gz>
   6
   7 Pyrex is a compiler. Therefore it is natural that people tend to go
   8 through an edit/compile/test cycle with Pyrex modules. But my personal
   9 opinion is that one of the deep insights in Python's implementation is
  10 that a language can be compiled (Python modules are compiled to .pyc)
  11 files and hide that compilation process from the end-user so that they
  12 do not have to worry about it. Pyximport does this for Pyrex modules.
  13 For instance if you write a Pyrex module called "foo.pyx", with
  14 Pyximport you can import it in a regular Python module like this:
  15
  16
  17 import pyximport; pyximport.install()
  18 import foo
  19
  20 Doing so will result in the compilation of foo.pyx (with appropriate
  21 exceptions if it has an error in it).
  22
  23 If you would always like to import pyrex files without building them
  24 specially, you can also the first line above to your sitecustomize.py.
  25 That will install the hook every time you run Python. Then you can use
  26 Pyrex modules just with simple import statements. I like to test my
  27 Pyrex modules like this:
  28
  29
  30 python -c "import foo"
  31
  32  == Dependency Handling ==
  33
  34 In Pyximport 1.1 it is possible to declare that your module depends on
  35 multiple files, (likely ".h" and ".pxd" files). If your Pyrex module is
  36 named "foo" and thus has the filename "foo.pyx" then you should make
  37 another file in the same directory called "foo.pyxdep". The
  38 "modname.pyxdep" file can be a list of filenames or "globs" (like
  39 "*.pxd" or "include/*.h"). Each filename or glob must be on a separate
  40 line. Pyximport will check the file date for each of those files before
  41 deciding whether to rebuild the module. In order to keep track of the
  42 fact that the dependency has been handled, Pyximport updates the
  43 modification time of your ".pyx" source file. Future versions may do
  44 something more sophisticated like informing distutils of the
  45 dependencies directly.
  46
  47  == Limitations ==
  48
  49 Pyximport does not give you any control over how your Pyrex file is
  50 compiled. Usually the defaults are fine. You might run into problems if
  51 you wanted to write your program in half-C, half-Pyrex and build them
  52 into a single library. Pyximport 1.2 will probably do this.
  53
  54 Pyximport does not hide the Distutils/GCC warnings and errors generated
  55 by the import process. Arguably this will give you better feedback if
  56 something went wrong and why. And if nothing went wrong it will give you
  57 the warm fuzzy that pyximport really did rebuild your module as it was
  58 supposed to.
  59
  60  == For further thought and discussion ==
  61
  62 I don't think that Python's "reload" will do anything for changed .SOs
  63 on some (all?) platforms. It would require some (easy) experimentation
  64 that I haven't gotten around to. But reload is rarely used in
  65 applications outside of the Python interactive interpreter and certainly
  66 not used much for C extension modules. Info about Windows
  67 <http://mail.python.org/pipermail/python-list/2001-July/053798.html>
  68
  69 "setup.py install" does not modify sitecustomize.py for you. Should it?
  70 Modifying Python's "standard interpreter" behaviour may be more than
  71 most people expect of a package they install..
  72
  73 Pyximport puts your ".c" file beside your ".pyx" file (analogous to
  74 ".pyc" beside ".py"). But it puts the platform-specific binary in a
  75 build directory as per normal for Distutils. If I could wave a magic
  76 wand and get Pyrex or distutils or whoever to put the build directory I
  77 might do it but not necessarily: having it at the top level is VERY
  78 HELPFUL for debugging Pyrex problems.
  79