A module is a file; the name of the module is the file name. The
.py extension on the file name is required by the
operating system, and gracefully ignored by Python. We can create a file
named roulette.py, include numerous definitions of
classes and functions related to the game of roulette.
Note that a module name must be a valid Python name. Operating
system file names don't have the same restrictions on their names. The
rules for variable names are in the section called “Variables”. A
module's name is limited to letters, digits and _'s.
The first line of a module is usually a #! comment;
this is typically #!/usr/bin/env python. The next few lines
are a triple-quoted module doc string that defines the contents of the
module file. As with other Python doc strings, the first line of the
string is a summary of the module. This is followed by a more complete
definition of the module's contents, purpose and usage.
For example, we can create the following module, called
dicedefs.py
Example 28.1. dice.py
#!/usr/bin/env python
"""dice - basic definitions for Die and Dice.
Die - a single die
Dice - a collection of one or more dice
roll - a function to roll a pair of dice"""
from random import *
class Die( object ):
"""Simulate a 6-sided die."""
def __init__( self ):
self.value= None
def roll( self ):
self.value= randrange(6)+1
def total( self ):
return self.value
class Dice:
"""Simulate a pair of 6-sided dice."""
def __init__( self ):
self.value = ( Die(), Die() )
def roll( self ):
map( lambda d: d.roll(), self.value )
def dice( self ):
return tuple( [d.value for d in self.value] )
pair= Dice()
def roll():
pair.roll()
return pair.dice()
|
A "main" script file must include the shell escape to run
nicely in a Posix or Mac OS environment. Other files, even if
they aren't main scripts, can include this to mark them as
Python.
|
|
Our docstring is a minimal summary. Well-written
docstrings provide more information on the classes, variables
and functions that are defined by the module.
|
|
Many modules depends on other modules. Note that Python
optimizes these imports; if some other module has already
imported a given module, it is simply made available to our
module. If the module has not been imported already, it is
imported for use by our module.
|
|
As is typical of many modules, this module provides some
class definitions.
|
|
This module defines a module-global variable. This
variable is part of the module; it appears global to all classes
and functions within this module. It is also available to every
client of this module. Since this variable is part of the
module, every client is sharing a single variable.
|
|
This module defines a handy function,
roll, which uses the module global
variable.
|
Conspicuous by its absence is any main script. This module is a
pure library module.
