16.4 Reloading Modules

A module's code is run only once per process by default. To force a module's code to be reloaded and rerun, you need to ask Python explicitly to do so, by calling the reload built-in function. In this section, we'll explore how to use reloads to make your systems more dynamic. In a nutshell:

• Imports (both import and from statements) load and run a module's code only the first time the module is imported in a process.

• Later imports use the already loaded module object without reloading or rerunning the file's code.

• The reload function forces an already loaded module's code to be reloaded and rerun. Assignments in the file's new code change the existing module object in-place.

Why all the fuss about reloading modules? The reload function allows parts of programs to be changed without stopping the whole program. With reload, the effects of changes in components can be observed immediately. Reloading doesn't help in every situation, but where it does, it makes for a much shorter development cycle. For instance, imagine a database program that must connect to a server on startup; since program changes can be tested immediately after reloads, you need to connect only once while debugging.

Because Python is interpreted (more or less), it already gets rid of the compile/link steps you need to go through to get a C program to run: modules are loaded dynamically, when imported by a running program. Reloading adds to this, by allowing you to also change parts of running programs without stopping. We should note that reload currently only works on modules written in Python; C extension modules can be dynamically loaded at runtime too, but they can't be reloaded.

16.4.1 Reload Basics

Unlike import and from:

• reload is a built-in function in Python, not a statement.

• reload is passed an existing module object, not a name.

Because reload expects an object, a module must have been previously imported successfully before you can reload it. In fact, if the import was unsuccessful due to a syntax or other error, you may need to repeat an import before you can reload. Furthermore, the syntax of import statements and reload calls differs: reloads require parenthesis, but imports do not. Reloading looks like this:

import module                # Initial import
...use module.attributes...
...                          # Now, go change the module file.
... 
reload(module)               # Get updated exports.
...use module.attributes...

You typically import a module, then change its source code in a text editor and reload. When you call reload, Python rereads the module file's source code and reruns its top-level statements. But perhaps the most important thing to know about reload is that it changes a module object in-place; it does not delete and recreate the module object. Because of that, every reference to a module object anywhere in your program is automatically affected by a reload. The details:

• reload runs a module file's new code in the module's current namespace. Rerunning a module file's code overwrites its existing namespace, rather than deleting and recreating it.

• Top-level assignments in the file replace names with new values. For instance, rerunning a def statement replaces the prior version of the function in the module's namespace, by reassigning the function name.

• Reloads impact all clients that use import to fetch modules. Because clients that use import qualify to fetch attributes, they'll find new values in the module object after a reload.

• Reloads impact future from clients only. Clients that used from to fetch attributes in the past won't be effected by a reload; they'll still have references to the old objects fetched before the reload.

16.4.2 Reload Example

Here's a more concrete example of reload in action. In the following example, we change and reload a module file without stopping the interactive Python session. Reloads are used in many other scenarios, too (see the sidebar Why You Will Care: Module Reloads), but we'll keep things simple for illustration here. First, let's write a module file named changer.py with the text editor of our choice:

message = "First version"

def printer(  ):
    print message

Why You Will Care: Module Reloads Besides allowing you to reload (and hence rerun) modules at the interactive prompt, module reloads are also useful in larger systems, especially when the cost of restarting the entire application is prohibitive. For instance, systems that must connect to servers over a network on startup are prime candidates for dynamic reloads. They're also useful in GUI work (a widget's callback action can be changed while the GUI remains active) and when Python is used as an embedded language in a C or C++ program (the enclosing program can request a reload of the Python code it runs, without having to stop). See Programming Python for more on reloading GUI callbacks and embedded Python code. More generally, reloads allow programs to provide highly dynamic interfaces. For instance, Python is often used as a customization language for larger systems—users customize products by coding bits of Python code onsite, without having to recompile the entire product (or even having its source code at all). In such worlds, the Python code already adds a dynamic flavor by itself. To be even more dynamic, though, such systems can automatically reload the Python customization code each time it runs—that way, users' changes are picked up while the system is running. There is no need to stop and restart each time the Python code is modified. Not all systems require such a dynamic approach, but some do.

This module creates and exports two names—one bound to a string, and another to a function. Now, start the Python interpreter, import the module, and call the function it exports; the function prints the value of the global variable message:

% python
>>> import changer
>>> changer.printer(  )
First version
>>>

Next, keep the interpreter active and edit the module file in another window:

...modify changer.py without stopping Python...
% vi changer.py

Here, change the global message variable, as well as the printer function body:

message = "After editing"

def printer(  ):
    print 'reloaded:', message

Finally, come back to the Python window and reload the module to fetch the new code we just changed. Notice that importing the module again has no effect; we get the original message even though the file's been changed. We have to call reload in order to get the new version:

...back to the Python interpreter/program...

>>> import changer
>>> changer.printer(  )      # No effect: uses loaded module
First version

>>> reload(changer)          # Forces new code to load/run
<module 'changer'>
>>> changer.printer(  )      # Runs the new version now
reloaded: After editing

Notice that reload actually returns the module object for us; its result is usually ignored, but since expression results are printed at the interactive prompt, Python shows a default <module name> representation.