Namespaces

As discussed in Chapter 7, when you type the name of a variable or function into the Python interpreter, Python discovers what it is by resolving its name in a namespace. Recall that a namespace is a mapping between the names by which you refer to objects in your program, and the location of the object as it's actually stored in the computer. When you write a python program, and refer to a variable called x, that variable is said to be part of the local namespace.

In order to use a module, you must expand the namespace of your program to include the objects which are defined in the module, and there are three ways in which you can do this, each using the import statement. To make these ideas more concrete, let's consider the urllib module, which provides functions for accessing documents on the World Wide Web through their URLs (Universal Resource Locator). The simplest way to access a module is to provide the module's name to the import statement; in our example this would mean using the statement

import urllib

somewhere near the beginning of our program. When you use this form of the import statement, the only name which is imported into the local namespace is the name urllib; in order to access the individual objects within the urllib module, you need to further qualify the urllib reference with the name of the object you wish to access, separated by a period (.) from the name of the module itself. (To find the names of all of the objects defined in a module, you can use the dir function; to actually see the contents of the namespace, you can use the vars function.) You can import more than one module using a single import statement by separating the names of the modules you wish to import with commas.

As an example, one of the functions in the module is called urlopen; you supply this function a character value consisting of any URL, and it returns a file-like object, allowing you to use any of the methods discussed in Chapter 5 to access the content of the URL. After using the import urllib statement, we could create a file object to access the Yahoo web page with the following Python command:

yahoo = urllib.urlopen('http://www.yahoo.com')

One advantage of this method is that it is immediately obvious that the urlopen function comes from the urllib module. If you wanted to get more information about the function, it would be clear where you would need to go to find it.

As an alternative to importing a module name into the local namespace and having to further qualify that module name to access individual objects within the module, you can import the names of the objects you need directly into the local namespace. Following the above example, we could import urlopen directly into the local namespace with the command

from urllib import urlopen

To import more than one object from a module, provide the names of the objects you wish to import as a comma separated list. The import statement above would allow us to refer to urlopen directly:

yahoo = urlopen('http://www.yahoo.com')

While this approach is slightly more efficient than importing an entire module, it eliminates the explicit connection between the urlopen function and the urllib module. In addition, you need to list the name of each function you plan to use on the import statement, instead of being able to use whichever function you need, provided that you qualify its name with the name of the module that contains it.

Finally, you can import all of the objects from a module into the local namespace with a command of the form

from modulename import *

Since this technique may overwrite existing objects (and even built-in objects), it should be used with great care. Generally, the only time this method is useful is when the author of a module has taken care in naming the objects in the module so that they won't clash with existing objects. In these cases, the documentation for the module should make it clear that this technique is appropriate.

Python keeps track of what modules have been imported, and it will not re-import a module which has already been imported. This feature is essential to allow imported modules to verify that the modules they need are in place, without needlessly reprocessing the contents of those modules. When you are interactively testing a module, this feature can be very frustrating, because changes you make to your module will not be reflected when you reissue an import statement. The reload function is provided specifically for this situation. When you use the reload function, python will always read the contents of a module, even if it has already been imported. Note that the reload function only works for entire modules - if you're importing specific objects from a module, you'll need to restart your python session in order to see the changes that you've made to the module.