| paul@122 | 1 | Class Search Paths
|
| paul@122 | 2 | ------------------
|
| paul@122 | 3 |
|
| paul@122 | 4 | Java classes belonging to packages are located using sys.path or PYTHONPATH
|
| paul@122 | 5 | in the same way that they would be located using the Java classpath (or
|
| paul@122 | 6 | CLASSPATH environment variable). Thus, the rules for locating package
|
| paul@122 | 7 | classes are as follows:
|
| paul@122 | 8 |
|
| paul@122 | 9 | * Classes residing within plain directories which represent a package
|
| paul@122 | 10 | hierarchy can be accessed by putting the parent directory of the top of
|
| paul@122 | 11 | the package hierarchy on the PYTHONPATH (or sys.path). For example, a
|
| paul@122 | 12 | package called mypackage, represented by a directory of the same name at
|
| paul@122 | 13 | /home/java/classes/mypackage, would be made accessible by adding the
|
| paul@122 | 14 | /home/java/classes directory to the PYTHONPATH.
|
| paul@122 | 15 |
|
| paul@122 | 16 | * Classes residing within .jar files can be accessed by putting the path to
|
| paul@122 | 17 | each .jar file on the PYTHONPATH. For example, a package called
|
| paul@122 | 18 | mypackage, represented by a file located at /home/java/lib/mypackage.jar,
|
| paul@122 | 19 | would be made accessible by adding the /home/java/lib/mypackage.jar file
|
| paul@122 | 20 | to the PYTHONPATH.
|
| paul@122 | 21 |
|
| paul@122 | 22 | Note that classes not belonging to a package cannot be accessed via such
|
| paul@122 | 23 | search paths and are made available using a special module (see "Non-package
|
| paul@122 | 24 | Classes" below).
|
| paul@122 | 25 |
|
| paul@122 | 26 | Importing Classes
|
| paul@122 | 27 | -----------------
|
| paul@99 | 28 |
|
| paul@99 | 29 | The classhook.py import hook needs to be made available before imports from
|
| paul@99 | 30 | Java classes and libraries (.jar files) can take place. This can be done
|
| paul@99 | 31 | by either...
|
| paul@99 | 32 |
|
| paul@122 | 33 | * Running the classhook.py file directly and then using the interactive
|
| paul@122 | 34 | interpreter:
|
| paul@99 | 35 |
|
| paul@122 | 36 | python -i classhook.py
|
| paul@99 | 37 |
|
| paul@122 | 38 | * Putting classhook.py in sys.path or PYTHONPATH and importing the
|
| paul@122 | 39 | classhook module before any code importing Java classes and packages.
|
| paul@99 | 40 |
|
| paul@122 | 41 | Importing Non-package Classes
|
| paul@122 | 42 | -----------------------------
|
| paul@99 | 43 |
|
| paul@122 | 44 | Classes which do not belong to a package are only accessible when residing
|
| paul@122 | 45 | in the current working directory of any program attempting to use them. Such
|
| paul@122 | 46 | classes will not be made available automatically, but must be imported from
|
| paul@122 | 47 | a special module called __this__.
|
| paul@99 | 48 |
|
| paul@122 | 49 | * Usage of the "import __this__" statement will cause all classes in the
|
| paul@122 | 50 | current directory to be made available within the __this__ module.
|
| paul@99 | 51 |
|
| paul@122 | 52 | * Usage of the "from __this__ import" construct will cause all classes in
|
| paul@122 | 53 | the current directory to be processsed, but only named classes will be
|
| paul@122 | 54 | made available in the global namespace unless "*" was specified (which
|
| paul@122 | 55 | will, as usual, result in all such classes being made available).
|
| paul@99 | 56 |
|
| paul@122 | 57 | Running Java Classes
|
| paul@122 | 58 | --------------------
|
| paul@99 | 59 |
|
| paul@122 | 60 | Java classes with a public, static main method can be run directly using the
|
| paul@122 | 61 | runclass.py program.
|
| paul@99 | 62 |
|
| paul@122 | 63 | * Free-standing classes (ie. not belonging to packages) can be run from
|
| paul@122 | 64 | the directory in which they reside. For example, suitable classes in the
|
| paul@122 | 65 | tests directory would be run as follows:
|
| paul@99 | 66 |
|
| paul@122 | 67 | cd tests
|
| paul@122 | 68 | python ../runclass.py MainTest hello world
|
| paul@99 | 69 |
|
| paul@122 | 70 | If runclass.py is executable and on the PATH, then the following can be
|
| paul@122 | 71 | used instead:
|
| paul@99 | 72 |
|
| paul@122 | 73 | cd tests
|
| paul@122 | 74 | runclass.py MainTest hello world
|
| paul@122 | 75 |
|
| paul@122 | 76 | * Classes residing in packages can be run by ensuring that the packages
|
| paul@122 | 77 | are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
|
| paul@122 | 78 | the testpackage.MainTest class (for example) would be run as follows:
|
| paul@99 | 79 |
|
| paul@122 | 80 | python runclass.py testpackage.MainTest hello world
|
| paul@99 | 81 |
|
| paul@122 | 82 | If runclass.py is executable and on the PATH, then the following can be
|
| paul@122 | 83 | used instead:
|
| paul@99 | 84 |
|
| paul@122 | 85 | runclass.py testpackage.MainTest hello world
|
| paul@99 | 86 |
|
| paul@99 | 87 | Accessing Python Libraries from Java
|
| paul@99 | 88 | ------------------------------------
|
| paul@99 | 89 |
|
| paul@99 | 90 | To wrap Python libraries for use with Java, skeleton classes need to be
|
| paul@99 | 91 | compiled corresponding to each of the wrapped classes. Each of the methods
|
| paul@99 | 92 | in the skeleton classes can be empty (or return any permissible value) since
|
| paul@99 | 93 | the only purpose they serve is to provide the Java compiler with information
|
| paul@99 | 94 | about the Python libraries.
|
| paul@99 | 95 |
|
| paul@99 | 96 | 1. Compile the skeleton classes:
|
| paul@99 | 97 |
|
| paul@99 | 98 | javac examples/Qt/qtjava/QWidget.java
|
| paul@99 | 99 |
|
| paul@99 | 100 | 2. Compile the Java classes which use the wrapped Python libraries:
|
| paul@99 | 101 |
|
| paul@99 | 102 | javac -classpath examples/Qt examples/Qt/WidgetTest.java
|
| paul@99 | 103 |
|
| paul@99 | 104 | 3. Run the wrap.py tool on the directory where the skeleton class files
|
| paul@99 | 105 | reside, providing the name of the Python package or module being
|
| paul@99 | 106 | wrapped. This converts the directory into a Python package:
|
| paul@99 | 107 |
|
| paul@99 | 108 | PYTHONPATH=. python tools/wrap.py examples/Qt/qtjava qt
|
| paul@99 | 109 |
|
| paul@99 | 110 | Since the Java class files, if left in the processed directory, would
|
| paul@99 | 111 | be detected and imported using the classhook.py import hook, and since
|
| paul@99 | 112 | this would result in two conflicting implementations being imported
|
| paul@99 | 113 | (with possibly the non-functional Java classes being made available
|
| paul@99 | 114 | instead of the generated wrapper classes), the wrap.py tool removes all
|
| paul@99 | 115 | processed class files, leaving only Python source files in the
|
| paul@99 | 116 | processed directory.
|
| paul@99 | 117 |
|
| paul@99 | 118 | 4. The Java classes which use the wrapped Python libraries can now be
|
| paul@122 | 119 | imported and used as described above. The wrapper package (qtjava in
|
| paul@122 | 120 | the above example) needs to reside in sys.path or PYTHONPATH, as must
|
| paul@122 | 121 | the wrapped library (qt in the above example).
|
| paul@99 | 122 |
|
| paul@99 | 123 | Issues
|
| paul@99 | 124 | ------
|
| paul@99 | 125 |
|
| paul@92 | 126 | Investigate better exception raising. Currently, exceptions have to be
|
| paul@92 | 127 | derived from object so that object.__new__ can be used upon them. However,
|
| paul@92 | 128 | this seems to prevent them from being raised, and they need to be wrapped
|
| paul@92 | 129 | within Exception so that the information can be transmitted to the
|
| paul@92 | 130 | exception's handler.
|
| paul@92 | 131 |
|
| paul@92 | 132 | Consider nicer ways of writing the method names in Python, perhaps using a
|
| paul@92 | 133 | function which takes the individual parameter types as arguments.
|
