Modules, packages and the standard library
Modules, packages, and the Python Standard Library: definitions, import system, package structure, common import syntaxes, and practical use with running examples.
Drafted with Aria, reviewed by the AiCanCode.org team · Updated . How we write and check our notes. Spotted an error? Use Give Feedback at the bottom of the page.
Why it matters
Software grows beyond a single file. Engineers split code into reusable pieces called modules and packages, and use the Python Standard Library to avoid reinventing common tasks (files, dates, math, networking, data formats). Understanding how imports work makes projects organized, testable, and efficient in both coursework and industry.
Key ideas
Exact statement: “A module is a Python source file that defines a separate namespace; when imported, the file is executed once and its resulting objects are bound to the module’s namespace.”
Assumptions: The file is readable; Python can find it via the import system.
Definition — Package
- A package is a collection of modules organized in a directory hierarchy, used to structure a large program’s namespaces.
- Classical definition (still common in universities): “A package is a directory that contains an init.py file and one or more module files or subpackages.”
- Modern detail: Since Python 3.3, a namespace package may be a directory without init.py that still acts as a package when found on the import path (advanced; most coursework focuses on classical packages with init.py).
- Assumptions: The package directory is discoverable by the import system.
Import system — how Python finds and loads modules
- Exact statement: “On import, Python locates a module by its name along the import path (sys.path), loads and executes it once, stores it in sys.modules, and reuses the cached object on subsequent imports.”
- Steps (derivation-like explanation):
- You write
import nameorfrom name import obj. - Python’s import machinery searches for a loader via meta path finders, then looks along directories listed in sys.path (which typically includes the script’s directory, standard library paths, and installed site-packages).
- When the module file (or package) is found, Python executes the file at top level, creating the module’s namespace.
- Python inserts the module object into sys.modules under its full name so later imports do not re-execute the file.
- If
from name import objis used, Python bindsobjfrom the module’s namespace to the current scope.
- You write
Module namespace and special attributes
- name: Name of the module. If the file is run as a script,
__name__ == "__main__". When imported,__name__equals the module’s qualified name (e.g.,mylib.utils). - package: Qualified package name for relative imports.
- all (optional): In a module or package, a list of names that
from module import *should import. If not defined,import *imports all names not starting with underscore (in modules), but behavior in packages is governed by the package’s init.py. - sys.modules: A dictionary that caches loaded modules by name.
- name: Name of the module. If the file is run as a script,
Absolute vs relative imports
- Absolute import: Use the full path from the project’s top-level package. Example:
from mylib.utils import area_circle. - Relative import: Use dots to refer to the current package (
.) or parents (..). Example (inside a package module):from .utils import area_circle. Assumption: Relative import only works inside packages; not in top-level scripts.
- Absolute import: Use the full path from the project’s top-level package. Example:
Package initialization
- When importing a classical package, Python executes the package’s init.py once, creating the package namespace. init.py may set
__all__, import submodules for convenience, define version variables, or perform setup (keep it light to avoid slow imports). Importing a package does not automatically import its submodules; import them explicitly (e.g.,import mylib.utils) or expose them from init.py if desired.
- When importing a classical package, Python executes the package’s init.py once, creating the package namespace. init.py may set
Organizing a project — diagram to draw (no image; describe)
- Draw a vertical tree like this, with labels:
- Top: a box labeled “project_root/ (on sys.path)”. Under it, indent:
- “main.py (entry script)” with a note: ‘contains if name == "main"’.
- “mylib/ (package directory)” with a small arrow to:
- “init.py (package initializer; may set all)”
- “utils.py (module: functions)”
- “geometry/ (subpackage)” with:
- “init.py”
- “circle.py (module: area, circumference)”
- “data/ (non-code files)”
- Top: a box labeled “project_root/ (on sys.path)”. Under it, indent:
- Label arrows from main.py to mylib to show imports: absolute imports from main.py to mylib.utils; relative imports within mylib.geometry.circle to
from ..utils import helper.
- Draw a vertical tree like this, with labels:
Python Standard Library (overview; not exhaustive)
- Data and math: math, statistics, random, decimal, fractions.
- Dates and times: datetime, time.
- Files and OS: os, pathlib, shutil, glob, tempfile.
- Data formats: json, csv, pickle.
- Data structures and tools: collections, itertools, functools, heapq.
- Text and regex: re, string.
- System and runtime: sys, argparse, logging.
- Networking and web: urllib, http.
- Concurrency: threading, multiprocessing, asyncio.
- Testing: unittest.
- Rule of thumb: Prefer the Standard Library first before adding external packages; it is well-tested and available by default.
Best practices
- Keep module files focused and small; give descriptive names (avoid clashing with standard modules like naming your file
json.py). - Use absolute imports in applications; use relative imports mainly inside packages.
- Put test or demo code under
if __name__ == "__main__":to avoid side effects on import. - Avoid
from module import *in production code; it pollutes the namespace and hides dependencies.
- Keep module files focused and small; give descriptive names (avoid clashing with standard modules like naming your file
Formulas
For this programming topic, remember these core syntaxes and patterns:
import module- Imports a module; access with
module.name.
- Imports a module; access with
import module as alias- Imports with a short alias (e.g.,
import numpy as npstyle; for stdlib:import statistics as stats).
- Imports with a short alias (e.g.,
from module import name1, name2- Imports specific objects into current scope.
from module import name as alias- Imports a specific object with a local alias.
from package.subpackage import module- Imports a submodule using its full path (absolute import).
from . import sibling_module- Relative import from the same package (only valid inside packages).
from ..subpackage import module- Relative import from parent package (only valid inside packages).
if __name__ == "__main__": main()- Idiom to run code only when the file is executed as a script.
__all__ = ["name1", "name2"]- Controls what
from module import *exports.
- Controls what
- Package structure to remember (directory tree):
mylib/__init__.pyutils.pygeometry/__init__.pycircle.py
- Checking search path and loaded modules (use carefully):
import sys; print(sys.path)import sys; print(sys.modules.keys())
Worked examples
Example 1 — Creating and importing your own module and package at runtime (demonstrates package structure, init.py, import, name) Program:
# Example 1: Create a temporary package and import it
from pathlib import Path
import sys
import importlib.util
import runpy
# 1) Create a temporary directory structure for a package: mylib/utils.py
root = Path("temp_project").resolve()
(root / "mylib").mkdir(parents=True, exist_ok=True)
# 2) Write package initializer
(root / "mylib" / "__init__.py").write_text(
"""
__all__ = ["utils"]
PACKAGE_NAME = "mylib"
""".lstrip(),
encoding="utf-8",
)
# 3) Write a module with a function
(root / "mylib" / "utils.py").write_text(
"""
import math
def area_circle(r):
'''Return area of a circle of radius r (r ≥ 0).'''
return math.pi * r * r
if __name__ == "__main__":
# Demo code inside the module — runs only if module is executed directly
print(f"Demo area (r=2): {area_circle(2):.6f}")
""".lstrip(),
encoding="utf-8",
)
# 4) Ensure Python can find the package by adding root to sys.path
if str(root) not in sys.path:
sys.path.insert(0, str(root))
# 5) Import and use the module
from mylib import utils
r = 3
area = utils.area_circle(r)
print(f"utils.__name__ = {utils.__name__}")
print(f"utils.__package__ = {utils.__package__}")
print(f"Area of circle with r={r}: {area:.6f}")
# 6) Show that running the module as a script executes its demo code
# (this uses runpy to execute the file with __name__ == "__main__" without leaving this script)
module_path = root / "mylib" / "utils.py"
print("Running mylib.utils as a script:")
runpy.run_path(str(module_path), run_name="__main__")
Sample input: (no input)
Exact output:
utils.__name__ = mylib.utils
utils.__package__ = mylib
Area of circle with r=3: 28.274334
Running mylib.utils as a script:
Demo area (r=2): 12.566371
Example 2 — Using the Standard Library: math, statistics, random, datetime, json Program:
# Example 2: Standard Library tour — deterministic with random.seed
import math
import statistics as stats
import random
from datetime import datetime, timezone
import json
# 1) Math constants and functions
radius = 5.0
circumference = 2 * math.pi * radius
area = math.pi * radius * radius
# 2) Reproducible random sampling
random.seed(42)
nums = list(range(1, 11)) # 1 to 10
sample = random.sample(nums, 3) # 3 unique numbers
# 3) Statistics on data
mean_val = stats.mean(nums)
median_val = stats.median(nums)
# 4) Timestamps (UTC) and formatting
now_utc = datetime.now(timezone.utc)
iso_time = now_utc.isoformat(timespec="seconds")
# 5) JSON encoding/decoding
record = {
"radius": radius,
"circumference": round(circumference, 6),
"area": round(area, 6),
"sample": sample,
"summary": {"mean": mean_val, "median": median_val},
"generated_at": iso_time,
}
js = json.dumps(record, separators=(",", ":"))
parsed = json.loads(js)
print(f"circumference={circumference:.6f}")
print(f"area={area:.6f}")
print(f"sample={sample}")
print(f"mean={mean_val:.2f}, median={median_val:.2f}")
print(f"json={js}")
print(f"parsed_mean={parsed['summary']['mean']:.2f}")
Sample input: (no input)
Exact output (except the timestamp part, which is current time in UTC):
circumference=31.415927
area=78.539816
sample=[10, 1, 4]
mean=5.50, median=5.50
json={"radius":5.0,"circumference":31.415927,"area":78.539816,"sample":[10,1,4],"summary":{"mean":5.5,"median":5.5},"generated_at":"YYYY-MM-DDTHH:MM:SS+00:00"}
parsed_mean=5.50
Note: The generated_at field shows the current date and time in ISO 8601 format; values before and after seconds and timezone are stable, but the actual date-time will vary at runtime.
Example 3 — Data tools: collections.Counter and itertools Program:
# Example 3: Counting and combinatorics with Standard Library
from collections import Counter
import itertools
# Word frequency counting
words = "to be or not to be that is the question to be".split()
counts = Counter(words)
# Top 3 most common words
top3 = counts.most_common(3)
# Generate combinations of 2 elements from a list (lexicographic by input order)
items = ["A", "B", "C"]
combos = list(itertools.combinations(items, 2))
print("counts=", dict(counts))
print("top3=", top3)
print("combos=", combos)
Sample input: (no input)
Exact output:
counts= {'to': 3, 'be': 3, 'or': 1, 'not': 1, 'that': 1, 'is': 1, 'the': 1, 'question': 1}
top3= [('to', 3), ('be', 3), ('or', 1)]
combos= [('A', 'B'), ('A', 'C'), ('B', 'C')]
Common mistakes
- Misusing relative imports: Trying
from .utils import fin a top-level script (not inside a package) causes ImportError. Fix: Use absolute imports from the project root in scripts. - Uncontrolled side effects on import: Writing code that runs at top level (opens files, prints, runs computation) and then importing that module. Fix: Protect runnable/demo code under
if __name__ == "__main__":. from module import *: Pollutes namespace and hides where names come from; can also break static analysis. Fix: Import specific names or the module itself.- Circular imports: A imports B, and B imports A at top level, causing partially initialized modules and AttributeError. Fix: Restructure, delay imports inside functions, or merge shared code into a third module.
- Assuming import re-executes code every time: It does not; Python caches modules in sys.modules. Use
importlib.reload(module)if truly needed.
For your exam
- Explain absolute vs relative imports with valid code snippets and when relative imports are allowed.
- Descriptive/theory:
- Describe Python’s import mechanism and search path. Full marks: steps from import statement to execution and caching; mention sys.path and sys.modules.
- Write a short note on Standard Library categories with 6–8 examples and a one-line use case each.
- Diagrams:
- Draw a project directory tree showing a package, subpackage, and modules. Full marks: correct placement of init.py and arrows labeling absolute/relative imports.
- Programs:
- Write a program that defines a function in a separate module and imports it to compute something (e.g., geometry, unit conversion). Full marks: correct module file, import statement,
if __name__ == "__main__":guard, correct output. - Use two or three standard library modules together (e.g., datetime + json + statistics) to process and serialize data. Full marks: correct imports, clear output, no unnecessary dependencies.
- Write a program that defines a function in a separate module and imports it to compute something (e.g., geometry, unit conversion). Full marks: correct module file, import statement,
Quick check
- What is the difference between a module and a package in Python?
- When does
if __name__ == "__main__":evaluate to True, and why is it used? - Write a valid relative import to import
helperfrom a moduleutils.pylocated in the parent package while you are insidemylib/geometry/circle.py(both under packagemylib).
Answers: 1) A module is a single .py file; a package is a directory that organizes modules (classically with an init.py; namespace packages may omit it). 2) It is True when the file is executed as the main script; it is used to run code only on direct execution and avoid side effects on import. 3) from .. import utils then use utils.helper, or from ..utils import helper.
Finished this topic? Mark it so your progress, study plan and readiness keep up.
Stuck on something here?