Free Handbook · Runs in your browser

Modules & Packages

Importing and writing modules, how packages and __init__.py fit together, what if __name__ == "__main__" is for, pip and virtual environments the way professionals use them, and a tour of the standard library you should know exists — plus ModuleNotFoundError and the circular import.

0 / 108 lessons🔥 0 day streak

ShareX LinkedIn

Module 05 · what you'll be able to do

Import in all its forms and know which one to use
Split a program into modules and a package
Explain the __main__ guard and why every script has one
Create a virtual environment, install packages with pip, and pin them in requirements.txt
Reach for the right standard-library module before installing anything

Modules and import

A module is a .py file. import math runs math.py once (top to bottom), then gives you a module object whose attributes are everything the file defined. Any file you write is a module too — import helpers looks for helpers.py next to your script, then along sys.path.

pythonEdit it. ⌘/Ctrl + Enter runs.

import math                       # the module; access with a dot
print(math.sqrt(2))

from math import pi, floor        # pull specific names in
print(floor(pi))

import datetime as dt             # alias, the norm for long names
print(dt.date(2026, 1, 1).strftime("%A"))

from collections import Counter   # from a package
print(Counter("mississippi").most_common(1))

# A module is an object. Introspect it.
import json
print(type(json).__name__, json.__name__)
print([n for n in dir(json) if n.startswith("l")])   # names it defines

You should see

1.4142135623730951
3
Thursday
[('i', 4)]
module json
['load', 'loads']

Your turn

Import random and print five random integers between 1 and 6. Then from random import randint and do it again.

Avoid

from os.path import * — pulls in unknown names, shadows your own
Importing inside a loop
Importing a module for one constant you could copy

Prefer

import os then os.path.join(...) — the reader sees where it came from
All imports at the top: standard library, then third-party, then your own
from x import y for a few names you use constantly

Error you will hit

ModuleNotFoundError: No module named 'requests'

python

import requests
print(requests.get("https://example.com").status_code)

Traceback (most recent call last):
  File "your code", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

Why the interpreter said that

Python searched every directory on sys.path and found no requests. Three causes, in order of likelihood: (1) the package is not installed in this interpreter — you installed it in a different Python or a different virtual environment; (2) a typo in the name; (3) your own module is not on the path. In this browser page, only the standard library and a few bundled packages exist — the same error you would get on a fresh machine.

The fix

Install it into the environment you are running: python3 -m pip install requests. Using python3 -m pip instead of bare pip guarantees the same interpreter.

Packages

A package is a directory of modules with an __init__.py file (it can be empty). Dots in an import walk the directories: from shop.payments import charge means shop/payments.py, function charge. Inside a package you can import siblings relatively: from . import models.

texta project layout that scales

shop/
├── __init__.py          # makes "shop" a package; can expose a public API
├── models.py            # Product, Order
├── payments.py          # charge(), refund()
└── db/
    ├── __init__.py
    └── postgres.py
main.py                  # entry point: from shop.payments import charge
tests/
└── test_payments.py

pythonshop/__init__.py

"""The shop package. Import the public API here so callers write
`from shop import charge` instead of reaching into submodules."""
from .payments import charge, refund
from .models import Product, Order

__all__ = ["charge", "refund", "Product", "Order"]

__all__ defines what from shop import * exports and, more usefully, documents the public surface.

Error you will hit

ImportError: cannot import name 'charge' from partially initialized module (circular import)

python

# shop/payments.py
from shop.orders import Order      # payments needs orders...

# shop/orders.py
from shop.payments import charge   # ...and orders needs payments

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from shop.payments import charge
  File "shop/payments.py", line 2, in <module>
    from shop.orders import Order
  File "shop/orders.py", line 2, in <module>
    from shop.payments import charge
ImportError: cannot import name 'charge' from partially initialized module 'shop.payments' (most likely due to a circular import)

Why the interpreter said that

Importing payments starts running it; on line 2 it imports orders, which on ITS line 2 asks for charge from payments — but payments is still on line 2 and has not defined charge yet. Two modules that each need the other at import time cannot both go first.

The fix

Usually a design smell: move the shared thing into a third module both import, or import inside the function that needs it (so it runs at call time, not import time).

python

# shop/orders.py
class Order: ...

def pay(order):
    from shop.payments import charge   # deferred: runs when pay() is called
    return charge(order)

if name == "main"

Every module has a __name__. When you run a file directly, its __name__ is "__main__"; when another file imports it, __name__ is the module's name. The guard lets one file be both a library (importable, nothing runs) and a script (run it, and the block executes). Without it, importing your module would also run its demo code, tests, or worse.

pythonEdit it. ⌘/Ctrl + Enter runs.

def slugify(title):
    return "-".join(title.lower().split())

print("this module's __name__ is", __name__)

if __name__ == "__main__":
    # Only runs when executed directly, never on import.
    print(slugify("Hello World From Python"))

You should see

this module's __name__ is __main__
hello-world-from-python

In this page the code runs as the main program, so the guard is true. Save it as slug.py, then in another file import slug — the print inside the guard will not run.

The shape of every script

Functions at the top, a main() that wires them together, and if __name__ == "__main__": main() at the bottom. Testable, importable, and readable from the bottom up.

pip and virtual environments

Third-party packages come from PyPI via pip. Installing them globally is how you end up with project A needing pandas 1.x and project B needing 2.x. A virtual environment is a private copy of Python plus its own packages, one per project. Every professional Python project uses one; every CI system expects one.

shellterminal — the four commands you need

# 1. create it, once, inside the project folder
python3 -m venv .venv

# 2. activate it (each new terminal)
source .venv/bin/activate          # macOS / Linux
.venv\Scripts\activate             # Windows PowerShell

# 3. install what the project needs
python -m pip install requests pandas

# 4. freeze the exact versions so others (and CI) get the same ones
python -m pip freeze > requirements.txt
# …and on another machine:
python -m pip install -r requirements.txt

Add .venv/ to .gitignore. The environment is rebuilt from requirements.txt; it is never committed.

Tool	What it is	When you meet it
`venv` + `pip`	Built in. Enough for most projects.	Now
`requirements.txt`	A plain list of pinned packages	Every deploy, every Dockerfile
`pyproject.toml`	The modern project file (name, version, dependencies)	Publishing a package, or any tool below
`uv` / `poetry`	Faster, lockfile-based managers on top of the same ideas	Team projects
`conda`	Environments that also manage non-Python binaries	Data science, ML

Quick check

pip install pandas succeeded, but import pandas in your script says ModuleNotFoundError. Most likely cause?

Two interpreters, two sets of packages. python -m pip install … using the same python that runs your script removes the ambiguity, and activating the virtual environment makes both the same by default.

Standard library tour

"Batteries included" is Python's slogan for a reason. Before you pip install anything, check whether the standard library already does it. These are the modules working engineers use every week; the ones with their own lessons later are linked.

pythonEdit it. ⌘/Ctrl + Enter runs.

import os, sys, pathlib, json, csv, re, datetime, random, itertools, functools, collections, statistics, textwrap

print(sys.version_info.major, sys.version_info.minor >= 10)  # which Python
print(pathlib.Path("data/raw/file.csv").suffix)         # paths as objects (Module 06)
print(json.dumps({"ok": True, "n": 3}))                 # JSON (Module 06)
print(re.findall(r"\d+", "order 66 shipped 2 items"))   # regex (Module 10)
print(datetime.date(2026, 12, 25).isoformat())          # dates (Module 10)
random.seed(7); print(random.choice(["a", "b", "c"]))   # random
print(list(itertools.combinations("ABC", 2)))           # combinatorics
print(statistics.mean([2, 4, 9]), statistics.median([2, 4, 9]))
print(textwrap.shorten("a fairly long sentence that needs trimming", 24))
print(functools.reduce(lambda a, b: a * b, [1, 2, 3, 4]))
print(os.name in ("posix", "nt"))                       # OS interaction

You should see

3 True
.csv
{"ok": true, "n": 3}
['66', '2']
2026-12-25
b
[('A', 'B'), ('A', 'C'), ('B', 'C')]
5 4
a fairly long [...]
24
True

Need	Module	Instead of installing
Files, directories, paths	`pathlib`, `os`, `shutil`	—
CSV, JSON, config	`csv`, `json`, `tomllib`, `configparser`	pandas, for small files
HTTP (simple)	`urllib.request`	requests — though requests is nicer
Dates, times	`datetime`, `zoneinfo`	pytz
Command-line arguments	`argparse`	click, typer
Logging	`logging`	print()
Testing	`unittest`	pytest — which most teams still install
Concurrency	`threading`, `asyncio`, `concurrent.futures`	—
Databases	`sqlite3`	anything, for a local database
Hashing, secrets	`hashlib`, `secrets`, `uuid`	—

← Module 04Functions Module 06 →Files & Data

Finish the Python handbook, then get hired

Sit the exam for your certificate, run your resume through the ATS checker, and see the jobs that ask for exactly this.

Check my resume

Found this course useful? Share it.

ShareX LinkedIn

Comments

Join the conversation. Sign in to leave a comment — we'd love to hear your thoughts.