5.5 Reloading Modules

At the start of the last section, we noted that 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 reload to make your systems more dynamic. In a nutshell:

• Imports load and run a module's code only the first time.

• Later imports use the already loaded module object without rerunning code.

• The reload function forces an already loaded module's code to be reloaded and rerun.

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.^[4]

^[4] We should note that 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 also 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. We should finally note that since this book isn't about C modules, we've probably already noted too much.

5.5.1 General Form

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). 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; because of that, every reference to a module object is automatically effected 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.

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 after a reload .

Reloads impacts future from clients only

Clients that use 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 (we'll say more about this later).

5.5.2 Example

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

% cat changer.py
message = "First version"

def printer():
    print message

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; as you should know by now, the function prints the value of the global variable message:

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

Next, let's keep the interpreter active and edit the module file in another window; here, we change the global message variable, as well as the printer function body:

Modify changer.py without stopping Python

% vi changer.py
% cat changer.py
message = "After editing"

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

Finally, we 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 us a default <module name> representation.

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.