Importing modules

Suppose a warehouse app needs the square root of a number, a rounded-up count of delivery boxes and the average of some ratings. You could write each of those yourself — or you could use code that already exists, has been tested by millions of people and ships with every copy of Python.

That code lives in modules. A module is a file of Python code (functions, constants, classes) that other programs can use. Python comes with a large collection of them called the standard library. To use one, you import it.

import module

The simplest form imports the whole module. You then reach inside it with a dot: module.name.

import math

print(math.sqrt(81))
print(math.pi)
print(math.ceil(17 / 5))   # round UP: 3.4 becomes 4

import math creates one new name in your program: math. Everything the module provides stays inside it, so math.sqrt and math.pi say exactly where each name comes from. That is the main advantage of this form: a reader never has to guess where sqrt was defined.

from module import name

When you use one or two names a lot, you can copy them straight into your program:

from math import sqrt, ceil

print(sqrt(144))
print(ceil(2.1))

Now sqrt and ceil are names in your program, but math itself is not — from math import sqrt does not create the name math.

Aliases with as

as gives an imported module or name a different name in your program. Some aliases are so common they are a convention (import statistics as stats, and later import pandas as pd). Use aliases to shorten long names or to avoid a clash with a name you already use — not to invent cryptic abbreviations.

import statistics as stats
from math import factorial as fact

ratings = [4, 5, 3, 5, 4]
print(stats.mean(ratings))
print(fact(5))

What an import actually does

The first time a program imports a module, Python:

1. finds the module: first among the few modules compiled into Python itself (such as sys), then as a file in your program's folder, then in the standard library and installed packages;
2. runs the module's code from top to bottom, creating its functions and variables;
3. wraps the result in a module object and stores it in a cache called sys.modules;
4. binds a name in your program to that object.

Every later import of the same module finds it in the cache and skips steps 1–3. The example below uses a small module file, greeting.py, that prints a line when its code runs. Watch how often that line appears.

import greeting
import greeting
from greeting import welcome

print(welcome("Dana"))
print(greeting.WELCOME)

import math as m

print(m.floor(7.8), m.ceil(7.2))
print(m.__name__)

Exploring a module: dir() and help()

A module is an object, and its contents are attributes. Two built-in functions let you look inside:

• dir(module) returns a sorted list of the names the module defines. Names that start with an underscore are internal by convention.
• help(thing) prints the documentation for a module or function — what it does and what arguments it takes.

Every module also has a few standard attributes, such as __name__ (its name) and __doc__ (its documentation string).

import math

names = [n for n in dir(math) if not n.startswith("_")]
print(len(names) > 40)
print(names[:6])
help(math.isqrt)

circle_area(1)     # 3.14
circle_area(2.5)   # 19.63
circle_area(10)    # 314.16

boxes_needed(10, 4)   # 3  (4 + 4 + 2)
boxes_needed(8, 4)    # 2
boxes_needed(0, 6)    # 0

import math
public_names(math, "is")    # ['isclose', 'isfinite', 'isinf', 'isnan', 'isqrt']
public_names(math, "zzz")   # []

rating_summary([4, 5, 3, 5, 3])   # (4.0, 0.89)