Python Modules and Packages

  1. Overview: Python's module and package mechanism resembles Java's package mechanism.

    1. A module is a python file that ends with .py
    2. A package is a directory with a collection of modules or subpackages.

      1. The name of the package is the name of the directory.
    3. One uses the import statement to import a module or package. For example: 
      import sys           # import the system defined sys module--you can use the
                     #   functions in sys as long as you prefix them with sys.
import foo           # import foo.py. You can use the functions in foo as long as
                     #   you prefix them with foo.
from foo import min  # import the min function from foo into the current namespace.
                     #   You can use min without qualification
from foo import *    # import all functions from foo into the current namespace.
                     #   You can use all functions in foo without qualification
import sounds.effects.echo  # import echo.py from the sounds.effects package
                            # You can use the functions in echo as long as
                            # you prefix them with the full package name
                            # sounds.effects.echo.
from sounds.effects import echo     # You can use the functions in echo as
                                    # long as you prefix them with echo (you no
                                    # longer need the fully qualified package name)

from sounds.effects import *        # assume that effects is a directory. this
                                    # command does not work like you expect. See the
                                    # packages section below for details

  2. Modules

    1. When python imports a module, it compiles the file into byte codes and stores the byte codes in a .pyc file.

      1. This .pyc file does not speed up the execution of a program because the Python interpreter always interprets byte codes
      2. The .pyc file speeds up subsequent imports of the module because the compiler does not need to be invoked a second time
    2. The module search path: Python first searchs for built-in modules and then for modules in directories on the sys.path list

      1. By default, the current directory is the first entry on the sys.path list
      2. The remaining entries are Python libraries defined by the system-dependent default implementation
      3. You can add new directories either to the beginning or end of the list using standard list operations: If you add the directories to the beginning of the list, you will mask the modules in the Python libraries if the new directories contain similarly named modules.
    3. The dir command
      1. dir(module_name): Returns a list of names in the specified module
      2. dir(): Returns a list of names in the current namespace

  3. Packages

    1. __init__.py: Every package directory must have an __init__.py file, even if the file is empty (the current Python tutorial claims that the file must be present but I have seen other sources, such as Stack Overflow, claim that they are no longer needed for Python3.3+). This file tells Python to treat the directory as a package (otherwise Python treats the directory as an unnamed collection of modules). __init__.py can contain initialization code for the package, can load a specified subset of the packages, and can define the __all__list (see next bullet point).

    2. Importing * from a package: To force Python to import all modules in a package, you must add the module names to the __all__ list in __init__.py. For example, suppose your package structure is: 
      silhouette/
  __init__.py
  graphics/
     __init__.py
     rect.py
     circle.py
  events/
     __init__.py
     mouse.py
     keyboard.py
      If you want the command 
      from silhouette.events import *
      to import mouse.py and keyboard.py, then the __init__.py file for events should be: 
      __all__ = ["mouse", "keyboard"]
      Even after importing mouse and keyboard, you will still have to access their functions by qualifying them with either mouse or keyboard. If you omit the __all__ list, then nothing gets imported unless the __init__.py file explicitly imports certain modules

    3. Python also has a newer version of packages called namespace packages which we will not cover in this course.