OUTDATED, DO NOT USE: This tutorial was written in 1999 and was based on Python 1.5.2, which today is a really old version. I would not recommend using this tutorial to learn modern Python as the language has changed significantly. This page is left here in it's mostly-original form for historic reference only. Please consult the Python website for current documentation.

Importing modules

• Modules are typically stored as individual *.py files. They must be imported (included) before they can be used, usually with,

  import sys   # imports the module named "sys"
  

• Don't put the *.py or *.pyc filename extension on the import statement.
• Python searches for the modules according to you $PYTHONPATH environment variable, then in it's builtin list of modules.
• A module is "executed" when it is first imported. The usual effect is to define functions and/or classes, but it can really do anything.
• Reimporting a module does nothing. Use the reload() function to force a module to be reloaded again.

  import mymodule    # loads and runs your module
  import mymodule    # does nothing useful
  reload( mymodule ) # forces it to be loaded and run again
  

• You are always in a module. Even when typing in python statements interactively, you are in the special module named "__main__".

Test code

As mentioned, a module file is actually executed when imported. Although it typically defines functions and classes, it can also do anything extra it wants. One typical application is to create a module that when imported from a python program just defines some functions, but when it is called itself as the main program it executes some self-test code. This is usually done like,

#!/usr/bin/env python
# module mymod2.py

def cube(n):
   return n ** 3

if __name__ == '__main__':
   if cube(15) != 3375:
      print "Error, cube(15) is not correct"

Namespaces

Unlike the C #include directive, when you import a module everything defined in that module is put into its own namespace. This helps prevent name collisions between two different modules, which both may decide to define a "resize" function.

For the purposes of the examples, suppose we have the following module file:

#/usr/bin/env python
# Module file "mymod1.py"

def fact( n ):
   p=1L
   for i in xrange(1,n):
      p = p*i
   return p

def fact_squared( n ):
   return fact(n) ** 2

• If you use the basic import form you must qualify names to see them,

  import mymod1
  fact(10)         --> Error, fact not defined
  mymod1.fact(10)  --> 362880
  

• Notice that within the module, references to other names within the same module are not qualified.
• One module may import another module for its own internal use, but the outermost namespace will not see those names.
• You can also import a module into your own current namespace rather than into its own namespace. You may have the chance of name conflicts, but in some cases it is more convienient.

  from mymod1 import *
  fact(10)  --> 362880
  fact_squared(5) --> 576
  

• You can also just import a small set of names from a module into your own namespace so any others will not conflict. Use a comma-separated list of names (in this case, just "fact").

  from mymod1 import fact
  fact(10)         --> 362880
  fact_squared(5)  --> Error, fact_squared not defined
  

• When writing a module file, any names which are private and should not be directly visible to the importing program should start with an underscore.

The LGB Rule

• Local namespaces are also created inside of functions (with the def statement) and classes (with the class statement). But namespaces do not arbitarily nest. When Python attempts to resolve a variable name, it always looks in three different namespaces:
  1. Local namespace: the namespace inside a function or class
  2. Global namespace: the global namespace of the current module
  3. Builtin namespace: the predefined Python functions
  This is called the "LGB" rule in Python, and is perhaps the single most source of confusion for Python newcomers.
• Any assignment to a variable within a function will make that a local variable. Just referencing a variable will not. This means that the following is in error

  n = 1
  
  def func():
     print n  --> Error, n referenced before assigned
     n = 2    # creates local 'n' which hides global 'n'
  

• You can use the global keyword for force a reference to a variable to be outside the local namespace. Otherwise, Python will treat the variable as local. Compare these examples:

  n = 1
  
  def func1():
     n = 2
     print n
  
  def func2():
     global n
     n = 2
     print n
  
  func1()   --> 2
  print n   --> 1
  
  func2()   --> 2
  print n   --> 2
  

• You can nest function definitions, but it may not act as you expect. This is because the def statement is actually executed at runtime and is not like a traditional declaration. This means that namespaces do not nest.

  n = 1
  def A():
     n = 2
     def B():
        print n
     B()
  
  A()  --> 1
  

• This can also cause some interesting results. For instance try creating a recursive function definition inside another,

  def factorial_squared( n ):
     def fac( n, p=1L ):
        return fac( n-1, n* p )
  
     return fac( n ) ** 2
  

  This will result in an error when run, complaining that the function "fac" has not been defined. This is because the name "fac" is only present in the namespace for the "factorial_squared" function. It is not in the global namespace, nor is it in the namespace within the "fac" function itself. Python will not search for it up through the nesting levels; remember the LGB rule!

What does all this mean? It may sound like Python is very confused, but once you understand more about how python works this will really make more sense. So the main advise for the beginner is to not use nested functions.