Source

Appendix A: Using Other Tools with Jython - Draft

The primary focus of this appendix is to provide information on using some external
python packages with Jython. In some circumstances, the tools must be used or installed
a bit differently on Jython than on CPython, and those differences will be noted. Since there
is a good deal of documentation on the usage of these tools available on the web, this appendix
will focus on using the tool specifically with Jython. However, relevant URLs will be cited
for finding more documentation on each of the topics.

setuptools

Setuptools is a library that builds upon distutils, the standard Python
distribution facility. It offers some advanced tools like easy_install, a
command to automatically download and install a given Python package and its
dependencies.

As you can read on the output, the easy_install script has been installed to the
bin directory of the Jython installation (/home/lsoto/jython2.5.0/bin in
the example above). If you work frequently with Jython it's a good idea to
prepend this directory to the PATH environment variable, so you don't have
to type the whole path each time you want to use easy_install or other
scripts installed to this directory. From now on I'll assume that this is the
case. If you don't want to prepend Jython's bin directory to your PATH for
any reason, remember to type the complete path on each example (i.e., type
/path/to/jython/bin/easy_install when I say easy_install).

OK, so now you have easy_install. What's next? Let's grab a Python library
with it! For example, let's say that we need to access twitter from a program
written in Jython and we want to use python-twitter project, located at
http://code.google.com/p/python-twitter/.

Without easy_install you would go to that URL, read the building
instructions and after downloading the latest version and executing a few
commands you should be ready to go. Except that libraries often depend on other
libraries (as the case with python-twitter which depends on simplejson)
so you would have to repeat this boring process a few times.

We asked for "python-twitter", which is looked up on PyPI, the Python Package
Index which lists all the Python packages produced by the community. The version
0.6 was selected since it was the most recent version at the time I ran the
command.

The warnings are produced because the simplejson installation tries to
compile a C extension which for obvious reasons only works with CPython and not
with Jython.

Finally, we see:

Finished processing dependencies for python-twitter

Which signals the end of the automated installation process for
python-twitter. You can test that it was successfully installed by running
Jython and doing an import twitter on the interactive interpreter.

As noted above easy_install will try to get the latest version for the
library you specify. If you want a particular version, for example the 0.5
release of python-twitter then you can specify it in this way:

$ easy_install python-twitter==0.5

Warning

Note that it's not a good idea to have two version of the same library
installed at the same time. Take a look at the virtualenv section below for
a solution to the problem of running different programs requiring different
versions of the same library.

For debugging purposes is always useful to know where the bits installed using
easy_install go. As you can stop of the install output, they are installed
into <path-to-jython>/Lib/site-packages/<name_of_library>-<version>.egg
which may be a directory or a compressed zip file. Also, easy_install adds
an entry to the file <path-to-jython>/Lib/site-packages/easy-install.pth,
which ends up adding the directory or zip file to sys.path by default.

Unfortunately setuptools don't provide any automated way to uninstall
packages. You will have to manually delete the package egg directory or zip file
and remove the associated line on easy-install.pth.

virtualenv

Oftentimes it is nice to have separate versions of tools running on the same machine. The virtualenv tool
provides a way to create a virtual Python environment that can be used for various purposes including installation
of different package versions. Virtual environments can also be nice for those who do not have administrative
access for a particular Python installation but still need to have the ability to install packages to it, such is often
the case when working with domain hosts. Whatever the case may be, the virtualenv tool provides a means for creating
one or more virtual environments for a particular Python installation so that the libraries can be installed into controlled
environments other than the global site-packages area for your Python or Jython installation. The release of Jython 2.5.0 opened new doors
for the possibility of using such tools as virtualenv.

To use virtualenv with Jython, we first need to obtain it. The easiest way to do so is via the Python Package
Index. As you had learned in the previous section, easy_install is the way to install packages from the PyPI. The following
example shows how to install virtualenv using easy_install with Jython.

::

jython easy_install.py virtualenv

Once installed, it is quite easy to use the tool for creation of a virtual environment. The virtual environment
will include a Jython executable along with an installation of setuptools and it's own site-packages directory.
This was done so that you have
the ability to install different packages from the PyPI to your virtual environment. Let's create an enviroment
named JY2.5.1Env using the virtualenv.py module that exists within our Jython environment.

Now a new directory named JY2.5.1Env should have been created within your current working directory. You can run
Jython from this virtual environment by simply invoking the executable that was created. The virtualenv tool allows
us the ability to open a terminal and disignate it to be used for our virutal Jython environment exclusively via the
use of the activate command. To do so, open up a terminal and type the following:

source <path-to-virtual-environment/JY2.5.1Env/bin/activate

Once this is done, you should notice that the command line is preceeded with the name of the virutal environment that
you have activated. Any Jython shell or tool used in this terminal will now be using the virtual environment. This is an
excellent way to run a tool using two different versions of a particular libarary or for running a production and development
environment side-by-side. If you run the easy_install.py tool within the activated virtual environment terminal then the tool(s)
will be installed into the virtual environment. There can be an unlimited number of virtual environments installed
on a particular machine. To stop using the virtual environment within the terminal, simply type:

deactivate

Now your terminal should go back to normal use and default to the global Jython installation. Once deactivated any of the Jython
references made will call the global installation or libraries within the global site-packages area. It should be noted that
when you create a virtual environment, it automatically inherits all of the packages used by the global installation. Therefore
if you have a library installed in your global site-packages area then it can be used from the virtual environment right away.
A good practice is to install only essential libraries into your global Jython environment and then install one-offs or test
libraies into virtual environments.

It is useful to have the ability to list installations that are in use within a particular environment. One way
to do this is to install the yolk utility and make use of it's -l command. In order to install yolk, you must
grab a copy of the latest version of Jython beyond 2.5.1 as there has been a patch submitted that corrects some functionaility
which is used by yolk. You must also be running with JDK 1.6 or above as the patched version of Jython makes use
of the webbrowser module. The webbrowser module makes use of some java.awt.Desktop features that are only available
in JDK 1.6 and beyond. To install yolk, use the ez_install.py script as we've shown previously.

jython ez_install.py yolk

Once installed you can list the package installations for your Jython installations by issuing the -l command as follows:

As you can see, all installed packages will be listed. If you are using yolk from within a virtual environment then
you will see all packages installed in that virtual environment as well as those installed into the global
environment.

Similarly to setuptools, there is no way to automatically uninstall virtualenv. You must also manually delete the
package egg directory or zip file as well as remove references within easy-install.pth.