5.2 Module Basics

Python modules are easy to create; they're just files of Python program code, created with your favorite text editor. You don't need to write special syntax to tell Python you're making a module; almost any text file will do. Because Python handles all the details of finding and loading modules, modules are also easy to use; clients simply import a module or specific names a module defines and use the objects they reference. Here's an overview of the basics:

Creating modules: Python files, C extensions

Modules can actually be coded as either Python files or C extensions. We won't be studying C extensions in this book, but we'll use a few along the way. Many of Python's built-in tools are really imported C extension modules; to their clients, they look identical to Python file modules.

Using modules: import, from, reload()

As we'll see in a moment, clients can load modules with either import or from statements. By calling the reload built-in function, they may also reload a module's code without stopping programs that use it. Module files can also be run as top-level programs from the system prompt, as we saw in Chapter 1.

Module search path: PYTHONPATH

As we also saw in Chapter 1, Python searches for imported module files by inspecting all directories listed on the PYTHONPATH environment variable. You can store modules anywhere, so long as you add all your source directories to this variable.

5.2.1 Definition

Let's look at a simple example of module basics in action. To define a module, use your text editor to type Python code into a text file. Names assigned at the top level of the module become its attributes (names associated with the module object), and are exported for clients to use. For instance, if we type the def below into a file called module1.py, we create a module with one attribute—the name printer, which happens to be a reference to a function object:

def printer(x):           # module attribute
    print x

A word on filenames: you can call modules just about anything you like, but module filenames should end in a .py suffix if you plan to import them. Since their names become variables inside a Python program without the .py, they should also follow the variable naming rules in Chapter 3. For instance, a module named if.py won't work, because if is a reserved word (you'll get a syntax error). When modules are imported, Python maps the internal module name to an external filename, by adding directory paths in the PYTHONPATH variable to the front and a .py at the end: a module name M maps to the external file <directory-path>/M.py which stores our code.^[2]

^[2] It can also map to <directory-path>/M.pyc if there's already a compiled version of the module lying around; more on this later. Dynamically loaded C extension modules are found on PYTHONPATH too, but that's outside this book's scope.

5.2.2 Usage

Clients can use the module file we just wrote by running import or from statements. Both load the module file's code; the chief difference is that import fetches the module as a whole (so you must qualify to fetch its names out), but from fetches specific names out of the module. Here are three clients of the module at work:

% python
>>> import module1                    # get module
>>> module1.printer('Hello world!')   # qualify to get names (module.name)
Hello world!

>>> from module1 import printer       # get an export
>>> printer('Hello world!')           # no need to qualify name
Hello world!

>>> from module1 import *             # get all exports
>>> printer('Hello world!')
Hello world!

The last 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. In each of the three cases, we wind up calling the printer function defined in the external module file. 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 look at some of their properties in more detail.