1.1 --- a/README.txt Thu Jan 13 18:36:42 2005 +0100
1.2 +++ b/README.txt Thu Jan 13 19:44:15 2005 +0100
1.3 @@ -1,61 +1,88 @@
1.4 -Importing Java Classes and Libraries
1.5 -------------------------------------
1.6 +Class Search Paths
1.7 +------------------
1.8 +
1.9 +Java classes belonging to packages are located using sys.path or PYTHONPATH
1.10 +in the same way that they would be located using the Java classpath (or
1.11 +CLASSPATH environment variable). Thus, the rules for locating package
1.12 +classes are as follows:
1.13 +
1.14 + * Classes residing within plain directories which represent a package
1.15 + hierarchy can be accessed by putting the parent directory of the top of
1.16 + the package hierarchy on the PYTHONPATH (or sys.path). For example, a
1.17 + package called mypackage, represented by a directory of the same name at
1.18 + /home/java/classes/mypackage, would be made accessible by adding the
1.19 + /home/java/classes directory to the PYTHONPATH.
1.20 +
1.21 + * Classes residing within .jar files can be accessed by putting the path to
1.22 + each .jar file on the PYTHONPATH. For example, a package called
1.23 + mypackage, represented by a file located at /home/java/lib/mypackage.jar,
1.24 + would be made accessible by adding the /home/java/lib/mypackage.jar file
1.25 + to the PYTHONPATH.
1.26 +
1.27 +Note that classes not belonging to a package cannot be accessed via such
1.28 +search paths and are made available using a special module (see "Non-package
1.29 +Classes" below).
1.30 +
1.31 +Importing Classes
1.32 +-----------------
1.33
1.34 The classhook.py import hook needs to be made available before imports from
1.35 Java classes and libraries (.jar files) can take place. This can be done
1.36 by either...
1.37
1.38 - 1. Running the classhook.py file directly and then using the interactive
1.39 - interpreter:
1.40 + * Running the classhook.py file directly and then using the interactive
1.41 + interpreter:
1.42
1.43 - python -i classhook.py
1.44 + python -i classhook.py
1.45
1.46 - 2. Putting classhook.py in sys.path or PYTHONPATH and importing the
1.47 - classhook module before any code importing Java classes and packages.
1.48 + * Putting classhook.py in sys.path or PYTHONPATH and importing the
1.49 + classhook module before any code importing Java classes and packages.
1.50
1.51 -Java classes are located using sys.path or PYTHONPATH in the same way that
1.52 -they would be located using the Java classpath (or CLASSPATH environment
1.53 -variable).
1.54 +Importing Non-package Classes
1.55 +-----------------------------
1.56
1.57 - * Directories representing packages and containing Java class files must
1.58 - reside within directories specified on the PYTHONPATH. For example, the
1.59 - directory mypackage residing within /home/paulb/java would be used as
1.60 - follows:
1.61 +Classes which do not belong to a package are only accessible when residing
1.62 +in the current working directory of any program attempting to use them. Such
1.63 +classes will not be made available automatically, but must be imported from
1.64 +a special module called __this__.
1.65
1.66 - PYTHONPATH=/home/paulb/java python -i classhook.py
1.67 + * Usage of the "import __this__" statement will cause all classes in the
1.68 + current directory to be made available within the __this__ module.
1.69
1.70 - And within Python:
1.71 + * Usage of the "from __this__ import" construct will cause all classes in
1.72 + the current directory to be processsed, but only named classes will be
1.73 + made available in the global namespace unless "*" was specified (which
1.74 + will, as usual, result in all such classes being made available).
1.75
1.76 - import mypackage
1.77 -
1.78 - Note that the classes within the directory should be assigned to the
1.79 - package mypackage.
1.80 +Running Java Classes
1.81 +--------------------
1.82
1.83 - * Free-standing Java class files must reside in the current directory.
1.84 - For example, a collection of class files in /home/paulb/classes would be
1.85 - used as follows:
1.86 +Java classes with a public, static main method can be run directly using the
1.87 +runclass.py program.
1.88
1.89 - cd /home/paulb/classes
1.90 - python -i /home/paulb/python/classhook.py
1.91 + * Free-standing classes (ie. not belonging to packages) can be run from
1.92 + the directory in which they reside. For example, suitable classes in the
1.93 + tests directory would be run as follows:
1.94
1.95 - And within Python:
1.96 + cd tests
1.97 + python ../runclass.py MainTest hello world
1.98
1.99 - import __this__
1.100 + If runclass.py is executable and on the PATH, then the following can be
1.101 + used instead:
1.102
1.103 - Note that such free-standing classes should not be assigned to any
1.104 - package and must therefore appear within the special package __this__
1.105 - and be imported under such special conditions.
1.106 + cd tests
1.107 + runclass.py MainTest hello world
1.108 +
1.109 + * Classes residing in packages can be run by ensuring that the packages
1.110 + are registered on the PYTHONPATH (see "Class Search Paths" above). Then,
1.111 + the testpackage.MainTest class (for example) would be run as follows:
1.112
1.113 - * Libraries contained within .jar files must be specified directly on the
1.114 - PYTHONPATH as if they were directories containing package hierarchies.
1.115 - For example, the library archive.jar, residing within /home/paulb/java
1.116 - and containing the package mypackage, would be used as follows:
1.117 + python runclass.py testpackage.MainTest hello world
1.118
1.119 - PYTHONPATH=/home/paulb/java/archive.jar python -i classhook.py
1.120 + If runclass.py is executable and on the PATH, then the following can be
1.121 + used instead:
1.122
1.123 - And within Python:
1.124 -
1.125 - import mypackage
1.126 + runclass.py testpackage.MainTest hello world
1.127
1.128 Accessing Python Libraries from Java
1.129 ------------------------------------
1.130 @@ -89,8 +116,9 @@
1.131 processed directory.
1.132
1.133 4. The Java classes which use the wrapped Python libraries can now be
1.134 - imported and used as described above. The wrapper package needs to
1.135 - reside in sys.path or PYTHONPATH, as must the wrapped library.
1.136 + imported and used as described above. The wrapper package (qtjava in
1.137 + the above example) needs to reside in sys.path or PYTHONPATH, as must
1.138 + the wrapped library (qt in the above example).
1.139
1.140 Issues
1.141 ------