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