Python Modules and Packages


Teaching: min
Exercises: min
  • How to make Python code more reusable?

  • Be able to create Python modules

  • Be able to create Python package

  • Know how to make installable Python package


Python has a way to put definitions in a file and use them in a script or in an interactive instance of the interpreter. Such a file is called a module; definitions from a module can be imported into other modules or into the main module (the collection of variables that you have access to in a script executed at the top level and in calculator mode).

Example of the module

# Fibonacci numbers module

def fib(n):    # write Fibonacci series up to n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b

def fib2(n):   # return Fibonacci series up to n
    result = []
    a, b = 0, 1
    while a < n:
        a, b = b, a+b
    return result

Import this module in the interpreter.

import fibo

# assign local name
fib = fibo.fib

It is customary to put import statements at the beginning of the file.

You can import names from the module directly.

from fibo import fib, fib2
# `fibo` will not be defined

You can import all the names that a module defines.

from fibo import *
# all names except those begining with underscore `_` will be imported

Python programmers do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some things you have already defined.

If the module name is followed by as, then the name following as is bound directly to the imported module.

import fibo as fib

from fibo import fib as fibonacci

Executing modules as scripts

Running Python mdule with: python <arguments> the code in the module will be executed, just as if you imported it, but with the __name__ set to "__main__".

You can access first argument send to the script like that:

import sys
# be careful, the arguments are strings

Excercise: modify fibo module so that it can be executed as script, take the argument and passes it to funtion fib()

You can make a the file usable as a script by adding following at the end of the module:

if __name__ == "__main__":
    import sys

Execute the file as script with arguments

python 50

When you import the module, this code is not run.

The dir() function

The built-in function dir() is used to find out which names a module defines.

import fibo, sys

Without arguments, dir() lists the names you have defined currently:

a = [1,2,3,4,5,6,7]
import fibo
fib = fibo.fib

dir() does not list the names of built-in functions and variables. If you want a list of those, they are defined in the standard module builtins:

import builtins


Packages are a way of structuring Python’s module namespace by using “dotted module names”. For example, the module name A.B designates a submodule named B in a package named A.

Example of the package structure:

sound/                          Top-level package               Initialize the sound package
      formats/                  Subpackage for file format conversions
      effects/                  Subpackage for sound effects
      filters/                  Subpackage for filters
              ... files are required to make Python treat the directories as containing packages. In the simplest case, can just be an empty file.

Excercise: modify the fibo module to make it into a package.

Importting * from a package

By default nothing will be imported from package with *. It’s up to the developer to define which modules from the package will be imported. This can by done in file:

__all__ = ["module1", "module2"]

Excercise: Update fibo package to allow import of the module with *.

Intra-package references

When having submodules, we can refer to other modules:

from . import echo
from .. import formats
from ..filter import equalizer


So far we can only use modules located in the current working directory. In order to access it across your whole system it needs to be installed.

How to make a package into something that can be installed?

Put file in the same direcotry as your package (not the modules!).

Example of the file:

from setuptools import setup

      description='The funniest joke in the world',
      author='Flying Circus',

Excercise: add file to fibonacci package

Now we can install the pockage in our system with:

pip install .

and access it from wherever we want.

Creating a distribution

python sdist

This will create dist/funniest-0.1.tar.gz inside our top-level directory. If you like, copy that file to another host and try unpacking it and install it, just to verify that it works for you.


This lesson is based on:

  1. Python Docs Moules Chapter
  2. Python Packaging Guide

Key Points