Key Takeaways: Modules, Packages, and the Python Ecosystem

One-Sentence Summary

Modules and packages let you organize code across multiple files, reuse code without duplication, and tap into Python's enormous ecosystem of pre-built tools — transforming single-file scripts into maintainable, professional projects.

Three Import Styles

Style Syntax When to Use
Full import import math You use many items from the module; clarity matters
Selective import from math import sqrt, pi You use 1-3 items; no name conflicts
Aliased import import datetime as dt Module name is long or has a community convention
Avoid from math import * Pollutes namespace — almost never appropriate

Standard Library Greatest Hits

Module What It Does Example
datetime Dates, times, durations datetime.now(), timedelta(days=7)
random Random numbers and selections randint(1, 6), choice(items)
collections Specialized containers Counter(data), defaultdict(list)
pathlib Modern file path handling Path("data") / "file.txt"
math Mathematical functions sqrt(), ceil(), pi
os / sys System interaction os.getcwd(), sys.path

Module vs. Package

Concept What It Is On Disk
Module A single .py file grading.py
Package A directory of related modules grading/ with __init__.py

Inside a package, modules can import each other with a relative import (from .calculations import letter_grade) or an absolute one (from grading.calculations import letter_grade). Relative imports fail if you run that file directly, so start the program from its entry point (python main.py).

The __name__ Guard

if __name__ == "__main__":
    # Only runs when this file is executed directly
    # Skipped when this file is imported by another file
  • Run directly: __name__ is "__main__"
  • Imported: __name__ is the module's name (e.g., "grading")

Finding and Installing Modules

  • Search order: Python checks already-loaded modules (sys.modules) and built-in modules, then searches the directories in sys.path in order: the running script's folder, PYTHONPATH, the standard library, then site-packages. The first match wins.
  • Third-party packages come from PyPI: pip install requests (or python -m pip install requests to be sure which Python you're installing for). Pin versions and isolate projects with virtual environments, covered in Chapter 23.

Key Rules

  1. Never name your files after standard library modules. A random.py, json.py, or datetime.py in your project folder is found first on sys.path and shadows the real module.
  2. Avoid circular imports. If A imports B and B imports A, one of them sees the other half-loaded. Restructure, move shared code to a third module, or import inside a function.
  3. A module runs once per program. The first import executes the file and caches it in sys.modules; later imports reuse the cached module.
  4. Keep side effects out of module-level code — put initialization inside functions or __name__ guards.
  5. One responsibility per module — if you describe it with "and," split it.
  6. Check the standard library first — before writing a utility function, someone probably already wrote it better.

TaskFlow v1.1 Structure

File Responsibility
models.py Task creation, completion, search
storage.py JSON load/save
display.py Formatting and output
cli.py Menu and user input
main.py Entry point — orchestrates everything

What's Next

Chapter 13: Testing and Debugging — write automated tests for your modules. The modular structure you built here makes testing dramatically easier.