Annotated README.txt

2005-01-18 Paul Boddie Added more test programs.
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 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 file directly and then using the interactive
paul@122 34
paul@99 35
paul@122 36
    python -i
paul@99 37
paul@122 38
  * Putting 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 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 ../ MainTest hello world
paul@99 69
paul@122 70
    If 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 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 testpackage.MainTest hello world
paul@99 81
paul@122 82
    If is executable and on the PATH, then the following can be
paul@122 83
    used instead:
paul@99 84
paul@122 85 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/
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/
paul@99 103
paul@99 104
  3. Run the 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/ 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 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 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
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.