Modules and import

Picture a workshop. The tools you need every day lie on the workbench. Everything else is sorted into boxes on the shelves, and each box is labeled with what it holds. When you need a rare tool, you take the right box off the shelf and put it on the bench.

Python works the same way. The functions print, len and sorted lie on the bench: they are available in any program right away. Square roots, random numbers and reading JSON sit in boxes on the shelf. Such a box is called a module — a .py file with ready-made functions.

You put a box on the bench with the import statement:

import math

print(math.sqrt(16))  # 4.0
print(math.floor(2.7), math.pi > 3)  # 2 True

Let's go through the example line by line:

1. import math puts the box math on the bench: the program gets the name math.
2. math.sqrt(16) takes the function sqrt out of the box and computes the square root of 16.
3. math.floor(2.7) rounds down and gives 2, and math.pi is the number π from the same box.

The dot between the names reads as "from the box math, take sqrt". The modules math, random, collections and json belong to the standard library — they are installed together with Python, and you do not need to download them.

Three forms of import

You can put the whole box on the bench, or take only the tools you need out of it. Let's go through the three forms one by one.

import module

The line import math gives one name — math. Every call is written through the dot: math.sqrt, math.floor. This is the most common form: the call math.sqrt shows at once where the function came from.

from module import name

The from … import form, familiar from data classes, takes single names out of a module. You write them without the module name. After from math import sqrt, the program has only sqrt, and no name math. This is handy for names that appear often in the program.

import module as another name

The word as gives a module or a function another name. Usually it shortens a long module name. All three forms in one program:

from math import sqrt, floor
import statistics as st

print(sqrt(25), floor(-2.5))  # 5.0 -3
print(st.mean([2, 4, 9]))  # 5

floor rounds down, toward the smaller integer, so -2.5 becomes -3. The mean function of statistics computes the average: the sum 15 divided by 3 items is 5. The line from random import choice gives the function choice the same way; it returns a random element of a list.

Interviewers like to ask this: "How does import math differ from from math import sqrt?" The answer: the first form creates the module's name, the second only the function's name.

How a module runs

Your own module is any .py file. Say greet.py with a function hello sits next to the program. The program loads it with the line import greet and calls greet.hello(). A module's name is its file name without .py.

The interpreter looks for a module first in the folder of the running program, then in the standard library. On the first import, it runs the module's file from top to bottom and creates a module object.

Here the box analogy stops working. You can bring a real box twice and end up with two boxes. A repeated import does not read the file again and returns the same object: after import math and import math as m, the expression m is math gives True. So a print outside any function in greet.py fires once, no matter how many times the module is imported.

Modules are grouped into packages. A package is a folder with modules and an __init__.py file, which may be empty. A module from a package is loaded through a dot:

• import shop.cart runs the file shop/cart.py, and calls are written through shop.cart;
• from shop import cart gives the short name cart.

Common mistake

The whole module was imported, but the function is called without its name:

import math

print(sqrt(16))  # ✗

NameError: name 'sqrt' is not defined

import math creates only the name math, and sqrt stays inside the box. Write math.sqrt(16) or import the function with the line from math import sqrt.

Key points

• A module is a .py file with ready-made functions, loaded with the import statement.
• import math gives the name math, from math import sqrt gives only sqrt, and as gives another name.
• A module's file runs on the first import; a repeated one returns the same object.
• A package is a folder with modules and an __init__.py file.