Modules are a critical organizational tool for final delivery of Python programming. Python software is delivered as a set of module files. Often a large application will have one or more module files plus a main script that initiates the application. There are several conventions for naming and documenting module files.

Module names are python identifiers as well as file names. Consequently, they can only use "_" as a punctuation mark. Most modules have names that are mixedCase, beginning with lowercase letters. This conforms to the useage on most file systems. MacOS users would do well to keep their module names to a single word, and end with .py. This promotes portability to operating systems where file names are more typically single words. Windows, in particular, can have trouble with spaces in file names.

Some Python modules are a wrapper for a C-language module. In this case the C/C++ module is named in all lowercase and has a leading underscore (e.g. _socket).

A module's contents start with a docstring. After the docstring comes any version control information. The bulk of a module is typically a series of definitions for classes, exceptions and functions.

A module's docstring should begin with a one-line pithy summary of the module. This is usually followed by in inventory of the public classes, exceptions and functions this module creates. Detailed change history does not belong here, but in a separate block of comments or an additional docstring.

If you use CVS to track the versions of your source files, following style is recommended. This makes the version information available as a string, and visible in the .py source as well as any .pyc working files.

"""My Demo Module.

This module is just a demonstration of some common styles."""

__version__ = "$Revision: 1.3 "

Note that the module's name will qualift everything created in the module, it is never necessary to have a prefix in front of each name inside the module to show its origin. For example, consider a module that contains classes and functions related to statistical analysis, called stats.py. The stats module might contain a class for tracking individual samples.

Poor Names. We don't include extra name prefixes like statsSample or stats_sample.

Better Names. We would call our internal sample class Sample. A client application that contains an import stats statement, would refer to the class as stats.Sample.

This needless over-qualification of names sometimes devolves to sillines, with class names beginning with c_, function names beginning with f_, the expected data type indicated with a letter, and the scope (global variables, local variables and function parameters) all identified with various leading and trailing letters. This is not done in Python programming. Class names begin with uppercase letters, functions begin with lowercase. Global variables are identified explicitly in global statements. Most functions are kept short enough that that the parameter names are quite obvious.

Any element of a module with a name that begins with _single_leading_underscore is not created in the namespace of the client module. When we use from stats import * , these names that begin with _ are not inserted in the global namespace. While usable within the module, these names are not visible to client modules, making them the equivalent of Java's private declaration.

A common feature of modules is to create a module-wide exception class. The usuall approach looks like the following. Within a module, you would define an Error class as follows:

class Error( Exception ): pass

You can then raise your module-specific exception with the following.

raise Error, "additional notes"

A client module or program can then reference the module's exception in a try statement as module.Error. For example:

import aModule

try:
    aModule.aFunction()
except: aModule.Error, ex:
    print "problem", ex
    raise

With this style, the origin of the error is shown clearly.