16.2 Module Usage

Clients can use the module file we just wrote by running import or from statements. Both find, compile, and run a module file's code if it hasn't yet been loaded. The chief difference is that import fetches the module as a whole, so you must qualify to fetch its names; instead, from fetches (or copies) specific names out of the module.

Let's see what this means in terms of code. All of the following examples wind up calling the printer function defined in the external module file module1.py, but in different ways.

16.2.1 The import Statement

In the first example, the name module1 serves two different purposes. It identifies an external file to be loaded and becomes a variable in the script, which references the module object after the file is loaded:

>>> import module1                    # Get module as a whole.
>>> module1.printer('Hello world!')   # Qualify to get names.
Hello world!

Because import gives a name that refers to the whole module object, we must go through the module name to fetch its attributes (e.g., module1.printer).

16.2.2 The from statement

By contrast, because from also copies names from one file over to another scope, we instead use the copied names directly without going through the module (e.g., printer):

>>> from module1 import printer       # Copy out one variable.
>>> printer('Hello world!')           # No need to qualify name.
Hello world!

16.2.3 The from * statement

Finally, the next example uses a special form of from: when we use a *, we get copies of all the names assigned at the top level of the referenced module. Here again, we use the copied name, and don't go through the module name:

>>> from module1 import *             # Copy out all variables.
>>> printer('Hello world!')
Hello world!

Technically, both import and from statements invoke the same import operation; from simply adds an extra copy-out step.

And that's it; modules really are simple to use. But to give you a better understanding of what really happens when you define and use modules, let's move on to look at some of their properties in more detail.

16.2.4 Imports Happen Only Once

One of the most common questions beginners seem to ask when using modules is: why won't my imports keep working? The first import works fine, but later imports during an interactive session (or program run) seem to have no effect. They're not supposed to, and here's why.

Modules are loaded and run on the first import or from. However, the import operation only happens on the first import, on purpose—since this is an expensive operation, Python does it just once per process by default. Later import operations simply fetch an already loaded module object.

As one consequence, because top-level code in a module file is usually executed only once, you can use it to initialize variables. Consider the file simple.py, for example:

print 'hello'
spam = 1                   # Initialize variable.

In this example, the print and = statements run the first time the module is imported, and variable spam is initialized at import time:

% python
>>> import simple          # First import: loads and runs file's code
hello
>>> simple.spam            # Assignment makes an attribute.
1

However, second and later imports don't rerun the module's code, but just fetch the already created module object in Python's internal modules table—variable spam is not reinitialized:

>>> simple.spam = 2        # Change attribute in module.
>>> import simple          # Just fetches already-loaded module.
>>> simple.spam            # Code wasn't rerun: attribute unchanged.
2

Of course, sometimes you really want a module's code to be rerun; we'll see how to do it with the reload built-in function later in this chapter.

16.2.5 import and from Are Assignments

Just like def, import and from are executable statements, not compile-time declarations. They may be nested in if tests, appear in function defs, and so on, and are not resolved or run until Python reaches them while your program executes. Imported modules and names are never available until import statements run. Also like def, import and from are implicit assignments:

• import assigns an entire module object to a single name.

• from assigns one or more names to objects of the same name in another module.

All the things we've already said about assignment apply to module access, too. For instance, names copied with a from become references to shared objects; like function arguments, reassigning a fetched name has no effect on the module it was copied from, but changing a fetched mutable object can change it in the module it was imported from. File small.py illustrates:

x = 1
y = [1, 2]

% python
>>> from small import x, y      # Copy two names out.
>>> x = 42                      # Changes local x only
>>> y[0] = 42                   # Changes shared mutable in-place

Here, we change a shared mutable object we got with the from assignment: name y in the importer and importee reference the same list object, so changing it from one place changes it in the other:

>>> import small                # Get module name (from doesn't).
>>> small.x                     # Small's x is not my x.
1
>>> small.y                     # But we share a changed mutable.
[42, 2]

In fact, for a graphical picture of what from assignments do, flip back to Figure 13-2 (function argument passing). Mentally replace "caller" and "function" with "imported" and "importer" to see what from assignments do with references. It's the exact same effect, except that here we're dealing with names in modules, not functions. Assignment works the same everywhere in Python.

16.2.6 Cross-File Name Changes

Note in the prior example how the assignment to x in the interactive session changes name x in that scope only, not the x in the file—there is no link from a name copied with from back to the file it came from. To really change a global name in another file, you must use import:

% python
>>> from small import x, y      # Copy two names out.
>>> x = 42                      # Changes my x only
  
>>> import small                # Get module name.
>>> small.x = 42                # Changes x in other module

Because changing variables in other modules like this is commonly confused (and often a bad design choice), we'll revisit this technique again later in this chapter. The change to y[0] in the prior session changes an object, not a name.

16.2.7 import and from Equivalence

Incidentally, notice that we also have to execute an import statement in the prior example after the from, in order to gain access to the small module name at all; from only copies names from one module to another, and does not assign the module name itself. At least conceptually, a from statement like this one:

from module import name1, name2     # Copy these two names out (only).

is equivalent to this sequence:

import module                       # Fetch the module object.
name1 = module.name1                # Copy names out by assignment.
name2 = module.name2
del module                          # Get rid of the module name.

Like all assignments, the from statement creates new variables in the importer, which initially refer to objects of the same name in the imported file. We only get the names copied out, though, not the module itself.