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
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
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
"""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,
module might contain a class for tracking individual samples.
Poor Names. We don't include extra name prefixes like
Better Names. We would call our internal sample class
Sample. A client application that contains an
statement, would refer to the class as
This needless over-qualification of names sometimes devolves to
sillines, with class names beginning with
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
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
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
class Error( Exception ): pass
You can then raise your module-specific exception with the
raise Error, "additional notes"
A client module or program can then reference the module's
exception in a
module.Error. For example:
except: aModule.Error, ex:
print "problem", ex
With this style, the origin of the error is shown clearly.