This is the first of the basic forms of the import statement. This is similar to Java’s import statement in appearance, but it binds the leftmost name. This is opposite of Java’s import which binds the rightmost name in the dotted package. class hierarchy. An example Java import could be:

import java.awt.TextComponent; 

This Java import statement allows you to directly use the name TextComponent, or the rightmost name, without any package names qualifying it. In Jython, however, a similar import binds the name java within the namespace in which the import occurred so that all following references to TextComponent must be qualified with java.awt. Inspecting the namespace with the dir() function shows how the name binding works in Jython:

>>> import java.awt.TextComponent 
>>> dir() 
['__doc__', '__name__', 'java'] 

If a module named b existed within package A, its import statement could be as follows:

import A.b 

The name bound, however, is the name A. The use of module b would require the package name A to qualify b. This means function c within module b is referenced as follows:

import A.b 
A.b.c() # call function c 

The module sys is a Jython module that is not part of a package, so it does not require any dot notation during import:

>>> import sys 

After the module sys is imported, you access contents with dot notation. This means accessing the variable path requires the following:

>>> import sys 
>>> sys.path 
['', '.', '/jython/Lib'] 

The sys.path variable is the Python version of Java’s classpath. This example also serves as an opportunity to check your sys.path variable. The sys.path does depend on your installation directory and is most likely different from the results above.

This form of the import statement also accepts a comma-separated list of modules or packages to import. The modules os and sys are Jython modules, while java is the root package of Java proper. To import these on one line, use a comma-separated list like the following:

>>> import os, sys, java 

Adding the word “as” to the simple import statement allows you to specify the name used to reference the imported item, and allows a direct binding to the rightmost element of the import. Specifying the name is an advantage in that you can avoid naming conflicts. Binding to the rightmost element eliminates the dot-notation required to qualify name.

Let’s look at importing the sys module again, only this time as bound to the name sys_module to avoid naming conflicts with a previously defined variable:

>>> sys = "A variable that creates a name conflict with module sys" 
>>> import sys as sys_module 
>>> dir() 
['__doc__', '__name__', 'sys_module', 'sys'] 
>>> sys 
'A variable that creates a name conflict with module sys' 
>>> s 
sys module 

Let’s revisit the A. b. c scenario stated earlier, where function c is within module b, which resides in package A. To bind module b to a new name, use the import X as Y syntax. This syntax binds the rightmost element of X to the name Y, so binding module b to a new name looks like this:

>>> import A.b as mod_b 
>>> dir(mod_b) 
['__doc__', '__file__', '__name__', 'c'] 
>>>mod_b.c() # call function c 

To extend control beyond packages and modules to actually control selective imports of module contents, you can use the from x import y syntax. This is not restricted to importing only module content—it works equally well with packages, modules, and classes. This syntax allows the import of sub-elements similar to the rightmost binding used with the as modifier, but in addition to sub-elements like sub-packages and sub-modules, it also allows importing selective contents of modules themselves.

Revisiting the A. b. c scenario yet again, you can bind module b by using the following:

from A import b 
b.c() # call function c 

To selectively import variables, functions, or classes from within a module using the from X import Y syntax, add the module name to X and include the desired module contents to Y. This means importing function c from module b, which resides in package A, uses the following:

from A.b import c 
c() # call function c 

As with the simple import statement, a comma-separated list is allowed. You can import multiple sub-elements with the following:

from A.b import c, d, e, f, etc 

Importing module-internal names such as the path variable within the sys module looks like this:

>>> from sys import path 

To import two names from the sys module, use the following:

>>> from sys import path, prefix 

The from X import Y syntax also allows an asterisk in the Y location. The asterisk designates the import of all available items (the definition of all is pliant and is described later). The use of the asterisk in imports is strongly discouraged in Jython—it has historically created numerous problems (such as when using import * with Java packages), so it is best to assume this option doesn’t really exist.

The syntax of the last form of import is as follows:

from X import Y as Z 

Where X is a fully qualified package or module, Y is a package, module, or module-global name, and Z is an arbitrary, user-specified name that Y is bound to. Importing function c as myFunc from module b in package A, looks like this:

from A.b import c as myFunc 

Locating Python modules depends on the sys.path variable. The directories within the sys.path list tell Jython where to search for modules. Trying to import a * . py file that does not reside anywhere in the sys.path raises an ImportError exception. Within this sys.path list is Jython’s Lib directory. This is where Jython’s installed module library resides. To inspect the sys.path variable for your Jython installation, use the following:

>>> import sys 
>>> print sys.path 
['', 'C:\WINDOWS\Desktop\.', 'C:\jython 2.1\Lib', 'C:\jython 2.1'] 

To add a path to the sys.path list, import the sys module and append the required path. To load modules located in the directory /usr/local/jython_work (on *nix), you must add this directory to the sys.path like:

>>> import sys 
>>> sys.path.append("/usr/local/jython_work") 

For the Windows directory C:jython_work, use this code:

>>> import sys 
>>> sys.path.append("c:\jython_work") # notice the double-backslash 
['', 'C:\WINDOWS\Desktop\.', 'C:\jython 2.1a1\Lib', 'C:\jython 
2.1a1', 'c:\jython 2.1a1\Lib\site-python', 'c:\jython_work'] 

Again note that sys.path is installation specific, so the contents of your sys.path may appear different than those in the book.

The backslash designates special characters like tab ( ) and newline ( ), as well as literal characters such as quotations (""") or a literal backslash (\). It is safest to use the double-backslash in windows paths to ensure the backslash is interpreted as a literal backslash rather than the start of a special character. However, in most cases the front slash, /, can be used as a directory separator on Windows within Jython code.

There are other ways to add to the sys.path variable. Jython has a file named registry that is located in Jython’s installation directory. The registry file contains a number of variables, including python.path and python.prepath, which both affect the contents of Jython’s sys.path list. To add the path /usr/local/jython_work to the sys.path without having to explicitly append this path in each module that uses it, just add it to the python.path or python.prepath variable. The difference between these two variables is that python.path appends the path at the end of sys.path, whereas python.prepath pre-pends the designated path before the rest of items in sys.path. The respective *nix and Windows registry entries look like this:

# for windows, use the double-backslash, and the semi-colon 
# path separator. 
python.path = c:\first_directory;d:\another_directory 

# For *nix, use the forward-slash, and the colon path separator 
python.path = /first/directory/to/add:/usr/local/secondDir/ 

Jython and Python also use a file called site.py to help with system paths. The site.py file is a module in Jython’s lib directory that is automatically loaded at Jython’s startup. One important feature of the site.py module is that it automatically looks for and imports the file sitecustomize.py. The sitecustomize.py module is not installed as part of Jython; it is a file that you author and is usually placed in Jython’s Lib directory. The automatic execution of sitecustomize.py at startup makes it useful for site-specific information such as extra library paths. Suppose you have Jython installed in the directory /usr/local/jython-2.1 on a Solaris machine, and you wish to organize user-defined modules in the directory /usr/local/jython-2.1/Lib/site-python. To add this extra directory to sys.path, you can create a sitecustomize.py file in the directory /usr/local/jython-2.1/Lib that includes the following code:

# file sitecustomize.py 
import sys 
sys.path.append(sys.prefix + "/Lib/site-python") 

The sys.prefix variable is a string representing the path to Jython’s installation directory. Actually, it’s the value of the python.home variable, which can be any arbitrary path and is discussed later, but for now it is most practically thought of as the path in which Jython is installed. Jython’s Lib directory is determined as sys.prefix + Lib. When import problems occur, it is often most instructive to print sys.prefix and sys.path to confirm their accuracy.

A module is a file that contains Jython code and has a .py extension. There are no other special syntax or directives required to make it a module. During any previous examples where you placed Jython code within a *.py file, you were actually creating a module. Modules also appear as .class files, or files containing Java bytecode, with names like modulename$py.class. These are the compiled version of modules that have been imported. Subsequent imports use these byte-compile files as an optimization if their associated .py has not changed. Modules are byte-compiled when they are imported or by using Jython’s compiler, jythonc, or by running the module compileall.py (found in Jython’s Lib directory).

Numerous modules are included with the Jython distribution, and they are located in Jython’s Lib directory. These modules are mostly Python modules originally included in the CPython distribution and a part of CPython’s documentation set. Not all of CPython’s modules work with Jython, however. Some of the modules in CPython rely on code written in C. Jython currently cannot make use of modules written in languages other than Java or Python, so these C-dependant modules will not work. Documentation for most of Jython’s modules is in the Python Library Reference currently located at http://www.python.org/doc/current/lib/lib.html, and available in the book Python Essential Reference by David Beazley (New Riders Publishing). Those modules that are unique or missing in Jython have descriptions in Appendix C of that book.

User-defined modules are those *.py files that you or others have written, and are not included in the distribution. These files could be placed in Jython’s Lib directory in order for them to be found and loaded; however, that usually makes it frustrating to upgrade Jython versions. A separate location for these files is more desirable, and a separate location requires an additional item in sys.path. For the remainder of this chapter, it is assumed that newly written modules are placed in a location in the sys.path list. The easiest would be the current working directory, which is automatically in the sys.path. Otherwise, in the directory sys.prefix + /Lib/site-python, which would require that you have added this to the sys.path list as described earlier.

Modules have special variables or “magic” variables. Magic is a colloquial term often ascribed to variables in Jython, and Python, that have two leading and trailing underscores.The magic variables in a module are __doc__, __file__, __name__, and __all__.

The __doc__ variable in a module is similar to the __doc__ string of functions. If a module begins with a string literal, that string literal becomes the module’s __doc__ attribute. This is part of Jython’s self-documentation mechanism. Suppose you need to create a directory-syncing tool. You would likely start out by documenting your intentions in a module’s __doc__ attribute:

# file: dirsync.py 
"""This module provides tools to sync a slave directory to a master 
directory.""" 

After placing the dirsync.py file in somewhere in the sys.path, you can look at the results of this string in the interactive interpreter:

>>> import dirsync 
>>> print dirsync.__doc__ 
This module provides tools to sync a slave directory to a master 
directory. 

The __name__ attribute of a module is the module name. The exception to this is the __main__ module. When Jython starts with a module name supplied as a command-line argument, such as jython test.py, the module supplied on the command line is considered the __main__ module. This introduces an important and useful convention in Jython modules.

Listing 5.1 shows a more complete version of the dirsync.py file. It doesn’t actually sync files, but Listing 5.1 calculates the work required to do so. The final if statement in Listing 5.1 is the useful module convention. First, examine Listing 5.1, beginning with explaining a couple of functions used:

# file: dirsync.py 
"""This module provides tools to sync a slave directory to a master 
directory.""" 

from __future__ import nested_scopes 
import os 
from stat import ST_MTIME 

def __getRequiredUpdates(master, slave): 
    """getRequiredUpdates(master, slave) -> list of files that are old or 
        missing from the slave directory""" 

    needUpdate = [] # holds results 
    def walk(mpath): # recursive function that does the work 
        if os.path.isfile(mpath): 
            spath = mpath.replace(master, slave) 
            if (not os.path.exists(spath) or 
               (os.stat(mpath)[ST_MTIME] > os.stat(spath)[ST_MTIME)): 
                needUpdate.append(mpath.replace(master, "")) 
        if os.path.isdir(mpath): 
            for item in os.listdir(mpath): 
                walk(os.path.join(mpath, item)) 
    walk(master) 
    return needUpdate 

def __getExtraneousFiles(master, slave): 
    """getExtraneousFiles(master, slave) -> list of files in the slave 
        directory which do not exist in the master directory""" 

    extraneous = [] # holds results 
    def walk(spath): # recursive function that does the work 
        mpath = spath.replace(slave, master) 
        if not os.path.exists(mpath): 
            extraneous.append(spath) 
        if os.path.isdir(spath): 
            for item in os.listdir(spath): 
                walk(os.path.join(spath, item)) 
    walk(slave) 
    return extraneous 
def sync(master, slave): 
    updates = __getRequiredUpdates(master, slave) 
    extras = __getExtraneousFiles(master, slave) 
    for item in updates: 
        # copy those files needing updated 
        print os.path.join(master, item), "need copied to slave dir." 
    for item in extras: 
        # delete those files that are extras 
        print item, "should be deleted." 
if __name__ == '__main__': 
    from time import time 
    import sys 
    t1 = time() 
    sync(sys.argv[1], sys.argv[2]) 
    print "Directory sync completed in %f seconds." %% (time()-t1) 

The last if statement in Listing 5.1 tests if the name of the module is __main__. If this is true, it means the module was run with the command jython dirsync.py and is expected to act lake the main script, or similar to what you would expect from methods with the public static void main(String args) signature in a Java program. However, if another script imports this module, __name__ is not __main__ and the associated code is not executed. Many Jython modules make use of this convention, either so that they can function as stand-alone scripts as well as modules, or so that they self-test when they are run as a stand-alone script. In the case of Listing 5.1, the script dirsync.py can be run as a standalone script to determine the work required to sync a master and slave directory that are supplied in the command-line with a command like the following:

jython dirsync.py "c:path	omasterdir" "c:path	oslavedir" 

The variable sys.argv is a list that contains all the command-line parameters used when starting Jython. The actual script running as the main script is always sys.argv[0], so in Listing 5.1, sys.argv[0] is dirsync.py, and sys.argv[1] and sys.argv[2] would be the master and slave directories, respectively. The shell command to run dirsync.py and the respective sys.argv assignments would be as follows:

jython dirsync.py c:mywork c:mybackups 
        argv[0]    argv[1]    argv[2] 

Listing 5.1 introduces another special naming convention: functions that begin with two underscores. Identifiers that begin with two underscores are special in that they are not imported when the from X import * syntax is used. Actually, in Jython 2.1, this should apply to those identifiers starting with one or two underscores, but those with one underscore didn’t work properly at the time this was written, so Listing 5.1 uses two underscores. To test this with the dirsync.py module in Listing 5.1, first ensure that it is in the sys.path, then type:

>>> from dirsync import * 
>>> dir() # look to see which names where imported 
['ST_MTIME', '__doc__', '__name__', 'nested_scopes', 'os', 'sync'] 

The results of the dir() function confirm that no names that begin with two underscores were imported.

The magic variable __all__ further controls the list of names imported from a module.The variable __all__ is a list that contains which names a module exports. If Listing 5.1 had a line like the following, the only name appearing after a from dirsync import * statement would be the name sync.:

__all__ = ['sync'] 

A Python package is a hierarchy of modules contained in a directory tree. The concept is the same as Java packages, except the contents of Python packages are modules, not classes. An excellent example of the package system is Jython’s pawt package found in Jython’s Lib directory.

Figure 5.1 is the directory listing of a Jython installation on a Windows machine. Note that depending on your version of Jython and whether or not you created the site-python directory discussed earlier, your directory, contents could differ. The Lib directory within C:jython-2.1 is where modules and packages distributed with Jython are stored. Within this directory, you’ll find the directory called pawt. It is not just another directory however—it is a Jython package. What makes it a package? It contains a file that initializes it as a package. This file is __init__.py.

Figure 5.1. The pawt Package.

When a package is imported, its __init__.py file is executed. Because pawt is a package, you can import its contents with any of the following statements:

>>> import pawt.colors 

>>> import pawt.swing 

>>> from pawt import colors, swing 

>>> from pawt import * 

You can also import the package itself with this statement:

>>> import pawt 

The unique thing about Python packages is that an import statement actually initializes all parent packages. This means if you have a hierarchy such that package A contains package B, which contains module C, the actual import of module C runs A.__init__.py, then runs B.__init__.py, and then imports module C. Listing 5.2 shows the implementation of this scenario. Three files, A.__init__.py, B.__init__.py, and moduleC, each merely print a message to announce the point of their evaluation. Listing 5.2 continues this example in the interactive interpreter by importing moduleC. The messages printed to the screen confirms the initialization of parent packages.

# file sys.prefix/site-python/A/__init__.py 
"""Root package in a nested package demonstration""" 
print "Initializing package A" 

# file sys.prefix/site-python/A/B/__init__.py 
print "Initializing package B" 


# file sys.prefix/site-python/A/B/moduleC.py 
print "Executing module 'moduleC'" 
import moduleD 

# file sys.prefix/site-python/A/B/moduleD.py 
print "Executing module 'moduleD'" 

>>> # examine packages A, B, and moduleC interactively 
>>> import A.B.moduleC 
Initializing package A 
Initializing package B 
Executing module 'moduleC' 
Executing 'moduleD' 

Listing 5.2 also includes a moduleD.py file to demonstrate how a module can import package-sibling modules without the fully qualified name, meaning moduleC can import moduleD with just its name. Modules in different packages must be qualified, however.

Jython’s self documentation conventions extend to packages in that if a package’s __init__.py file begins with a string literal, the package’s __doc__ attribute is assigned that string as a value. Notice that the file sys.prefix/site-python/A/__init__.py in Listing 5.2 has a string literal. If we revisit this package, we can see how the __doc__ attribute is assigned in this package. Note that you have to restart the interpreter between Listing 5.2 and the following in order for the package initialization to work as shown:

>>> import A 
Initializing package A 
>>> A.__doc__ 
'Root package in a nested package demonstration' 

A package’s __init__.py file can also contain the magic variable __all__, which designates the names that package exports when the from package import * statement is used.

An imported package is similar to a module except that a package has one additional special variable: __path__. The __path__ variable is just as you might guess: the system path to the specified package. Examining the pawt package demonstrates the __path__ variable:

>>> import pawt 
>>> pawt.__path__ 
['C:\jython 2.1a1\Lib\pawt']