A First Module - Page 3

The best way to learn about modules is probably to make one, so… Create a text file called mymath.py, and in that text file, enter the following Python code (if you are using IDLE, just select New window (figure 11.1) from the File menu and start typing):

""" mymath -our example math module"""
pi = 3.14159

def area( r):
  """ area( r): return the area of a circle with radius r."""
  global pi
  return( pi * r * r)

Figure 11.1 An IDLE edit window provides the same editing functionality as the shell window including automatic indentation and colorization.

Save this for now in the directory where your Python executable is. This code merely defines a constant and a function. The .py filename suffix is mandatory for all Python code files. It identifies that file to the Python interpreter as consisting of Python source code. As with functions, we have the option of putting in a document string as the first line of our module. Now start up the Python Shell, and type

>>> pi
Traceback (innermost last):
 File "< stdin>", line 1, in ?
NameError: pi
>>> area( 2)
Traceback (innermost last):
 File "< stdin>", line 1, in ?
NameError: area

In other words, Python doesn't have the constant pi or the function area built in. Now, type:

>>> import mymath
>>> pi
Traceback (innermost last):
File "<stdin>", line 1, in ?
NameError: pi
>>> mymath.pi
  3.14159
>>> mymath.area(2)
  12.56636
>>> mymath.__doc__
  'mymath - our example math module'
>>> mymath.area.__doc__
  'area(r): return the area of a circle with radius r.'

We've brought in the definitions for pi and area from the mymath. py file, using the import statement (which automatically adds on the .py suffix when it searches for the file defining the module named "mymath"). However, the new definitions aren't directly accessible; typing pi by itself gave an error, and typing area(2) by itself would give an error. Instead, we access pi and area by prepending them with the name of the module which contains them. This guarantees name safety. There may be another module out there which also defines pi (maybe the author of that module thinks that pi is 3.14, or 3.14159265), but that is of no concern. Even if that other module were imported, its version of pi will be accessed by othermodulename.pi, which is different from mymath.pi. This form of access is often referred to as qualification (i. e., the variable pi is being qualified by the module mymath). We may also refer to pi as an attribute of mymath.

Definitions within a module can access other definitions within that module, without prepending the module name. The mymath.area function accesses the mymath.pi constant as just pi.

If we want to, we can also specifically ask for names from a module to be imported in such a manner that we don't have to prepend them with the module name. Type:

>>> from mymath import pi
>>> pi
  3.14159
>>> area(2)
Traceback (innermost last):
 File "<stdin>", line 1, in ?
NameError: area

The name pi is now directly accessible because we specifically requested it using from module importname.

The function area still needs to be called as mymath.area, though, because it was not explicitly imported.

You may want to use the basic interactive mode or IDLE's Python Shell to incrementally test a module as you are creating it. However, if you change your module on disk, retyping the import command will not cause it to load again. You need to use the reload function for this.

>>> import mymath
>>> reload(mymath)
  <module 'mymath'>

When a module is reloaded (or imported for the first time), all of its code is parsed. So a syntax exception will be raised if an error is found. On the other hand, if everything is okay, a .pyc file (i. e. mymath.pyc) containing Python byte code will be created.

Reloading a module does not put you back into exactly the same situation as when you start a new session and import it for the first time. However, the differences will not normally cause you any problems. If interested, you can look up reload in the built-in functions section of the Python Language Reference to find the details.

Of course, modules don't need to be used from the interactive Python shell. They can also be imported into scripts, or other modules for that matter; just enter suitable import statements at the beginning of your program file. Also, internally to Python, the interactive session and a script are considered modules as well.

To summarize:

• A module is a file defining Python objects.
• If the name of the module file is modulename.py, then the Python name of the module itself is modulename.
• A module named modulename can be brought into use with the "import module-name" statement. After this statement is executed, objects defined in the module can be accessed as modulename.objectname.
• Specific names from a module can be brought directly into your program using the "from modulenameimportobjectname" statement. This makes objectname accessible to your program without needing to prepend it with modulename, and is useful for bringing in names that are often used.

What Is A Module? - Page 2
The Quick Python Book
The Import Statement - Page 4