Python Modules, Debugging and Testing Basics

A module holds Python code that another program can reuse. Most modules are .py files. The standard library comes with Python; third-party code needs a separate installation. A package groups related modules, commonly in a folder.

Match the call to the import

An import creates names in your program. The form you choose determines how you call the imported code.

Dot notation means looking up a name inside a module or object. In math.sqrt(16), Python finds sqrt inside math and calls it with 16. The result is 4.0. The constant math.pi needs no call parentheses because it is a value, not a function.

After import math, sqrt(16) alone raises NameError: the program has a name for the module, but no separate name for sqrt. After only from math import sqrt, the reverse mistake, math.sqrt(16), also raises NameError because math was not bound. An alias replaces the imported binding's usual name: import statistics as stats creates stats, not both names.

Work the same calculation two ways

A right triangle has sides 3 and 4. First square the sides and add them; then take the square root.

import math

length = math.sqrt(3**2 + 4**2)
print(length)  # 5.0

The expression inside the call becomes 9 + 16, then 25; sqrt returns 5.0. With from math import sqrt, write length = sqrt(3**2 + 4**2) instead. Using the module prefix makes a function's source visible and keeps its other names out of your program's name space. The binding math itself can still replace an earlier variable called math.

Keep names clear

Avoid from math import *. This wildcard import brings public names into your program without naming them individually. For example, e = 5 followed by that import changes e to 2.718281828459045. An unrelated-looking import can therefore change a later calculation. PEP 8 recommends explicit imports and puts imports at the top, with one module per line: standard library first, third-party packages next, your own modules last.

Python runs a module's top-level code on its first import during a program run. Later imports reuse the loaded module; they do not start it again.

Use the error to choose the fix

In the interactive shell, run import math, then dir(math) to list its names. Run help(math.sqrt) to read a function's documentation. The official Python library reference explains its arguments and result.

The standard library supplies tested tools for calculations and simulations. Choosing a function starts with the result you need: an integer count, a rounded measurement, one random item or a reordered list.

Rounding has several meanings

After import math, math.sqrt(16) returns the float 4.0. math.pi and math.e supply the constants 3.141592653589793 and 2.718281828459045. math.factorial(5) multiplies the whole numbers from 1 through 5 and returns 120.

For 23 square meters of wall and 10 square meters per paint can, division gives 2.3 cans. Buying whole cans requires math.ceil(23 / 10), which returns 3. round(2.3) gives 2 and leaves too little paint.

The built-in round() needs no import. For a circle of radius 2, round(math.pi * 2 ** 2, 2) gives 12.57. Rounding changes a number's precision; it is a different job from buying enough whole containers.

Check domains and float comparisons

math.sqrt(-1) raises ValueError because there is no real square root for that input. Calculated floats also need care: binary storage means 0.1 + 0.2 == 0.3 is False. math.isclose(0.1 + 0.2, 0.3) is True; use it for an approximate comparison of calculated floats.

Select the random operation

The random module uses an algorithm to make pseudo-random results.

Keep random.shuffle(cards) on its own line. Assigning its result back to cards loses the list binding by replacing it with None. Sampling positions is also different from requiring distinct values: random.sample([1, 1], 2) returns [1, 1].

Run a repeatable simulation

import random

sevens = 0
for _ in range(1000):
    if random.randint(1, 6) + random.randint(1, 6) == 7:
        sevens += 1
print(sevens)

Six of 36 equally likely pairs total 7, so the count is usually near 167, but it changes between runs. To reproduce a sequence for debugging, call random.seed(42) before generating the values, using the same Python version and call sequence. For passwords or security tokens, use secrets.

Find other everyday tools

statistics.mean([2, 4, 9]) returns 5; statistics.median([2, 4, 9]) returns 4. datetime.date.today() gives today's date. After import sys, sys.argv holds the script name followed by its arguments: running python greet.py Ada supplies ['greet.py', 'Ada'].

A function becomes easier to reuse when it lives in a focused module. Another program can import that function, and a test can check it without asking a person to run the whole application.

Split the function from its caller

Save this code as geometry.py:

"""Calculations for simple shapes."""
import math

def circle_area(radius):
    """Return the area of a circle with the given radius."""
    return math.pi * radius ** 2

In the same folder, save this caller as main.py:

import geometry

print(geometry.circle_area(2))

Run python main.py. Python finds geometry, creates its function, and then the caller runs that function. The printed result is 12.566370614359172. Import without the .py ending. A valid module name uses letters, digits and underscores with a valid first character; my_tools.py works with import my_tools, while import my-tools is invalid syntax.

The strings at the starts of the module and function are docstrings. They describe the code's purpose and appear in help(geometry) and help(geometry.circle_area).

Understand what importing runs

On the first import, Python executes the module's top-level statements in order. A def statement creates a function; it does not execute that function's body. An unguarded print(circle_area(2)) at the bottom of geometry.py, however, would print during import.

That side effect matters when a module contains input prompts or a program loop. A test that only wants circle_area should not have to start the program and answer its prompts.

Guard the launch, keep the function available

Add this below the reusable function in geometry.py:

def main():
    print(circle_area(2))

if __name__ == "__main__":
    main()

Python sets __name__ for each module. A direct run, python geometry.py, sets it to "__main__", making the condition true and calling main(). Importing geometry sets it to "geometry", so Python skips the call. The definitions above the guard remain available in both cases.

Do not place circle_area itself inside the guard. An importer needs that definition even when the launch condition is false. The guard controls when the application starts; it does not prevent Python from loading the module.

Know where Python searches

Python checks built-in modules such as sys, then the folders in sys.path in order. Normally the running script's folder comes first in that path, followed by standard-library and installed-package folders. Keeping your own files beside the running script is a simple arrangement for a beginner project. A module outside the search path cannot be found by an ordinary import.

This order can also hide a library module. If you save your program as random.py, its import random can load your file instead of the library. A later random.randint(1, 6) then raises AttributeError. Rename the file, for example to dice.py; Python 3.13 and later may include a renaming hint in the error.

A loaded module is reused within the same run. In an interactive shell, editing the file and importing it again keeps the loaded version. Restart the shell before testing your changes.

Third-party packages add code that does not come with Python. PyPI, the Python Package Index at https://pypi.org, hosts these projects. pip downloads and installs them for a particular Python installation.

Use the terminal, then use Python

A terminal command and a Python statement belong in different places. The >>> prompt means you are in Python's interactive shell. Entering pip install requests there gives SyntaxError; Python cannot read it as a statement.

In your terminal, run:

python -m pip install cowsay

Then put this in a Python program:

import cowsay

cowsay.cow("Hello, Ada")

The program prints a text cow beside a speech bubble containing the message. Installation makes the package available; the import creates the program's binding for it.

Match pip to your interpreter

The -m pip form asks the named Python to run its own pip. Use the command that starts your programs: often python3 on macOS or Linux, or py on Windows.

python3 -m pip install cowsay
python3 game.py

Both lines select the same Python command. If an installation reports success but a script still raises ModuleNotFoundError, compare the Python used to install with the one used to run the script. An editor may have selected a different interpreter from your terminal. Use the selected interpreter's pip before changing the import.

Inspect and maintain an installation

An exact version is useful when you need that particular release's behavior. show helps check which location pip actually changed.

Check the name in the documentation

The distribution name typed for pip can differ from the import name. Install beautifulsoup4, then use import bs4; install Pillow, then use import PIL. Repeatedly installing an import name is not a useful fix when the documentation names a different distribution.

Python's standard library, including math, random and unittest, already comes with Python. These modules do not require a pip installation.

Respect a managed installation

Some operating systems and package managers protect their Python with an externally-managed-environment error. This means a direct install is blocked to keep the managed installation consistent. Use a virtual environment, a separate Python and package folder for the project. Do not force the installation with sudo pip install.

Anyone can publish on PyPI. Before installing, check the exact spelling and read the project's page and documentation. Lookalike names can be typosquatting attempts. Prefer established, maintained packages, and install the ones your program actually needs.

A traceback tells you which calls were active when an unhandled exception stopped the program. It gives both a place to begin reading and a path back toward the value that caused the failure.

Start with the final line

Consider this complete program in scores.py:

def average(values):
    return sum(values) / len(values)

def report(scores):
    avg = average(scores)
    print(f"Average: {avg:.1f}")

report([])

The final line of its error report is ZeroDivisionError: division by zero. This names the exception type and describes the failed operation. Start there, then read upward to the code location immediately above it.

A simplified traceback, with expression markers omitted, is:

Traceback (most recent call last):
  File "scores.py", line 8, in <module>
    report([])
  File "scores.py", line 5, in report
    avg = average(scores)
  File "scores.py", line 2, in average
    return sum(values) / len(values)
ZeroDivisionError: division by zero

Read each frame as an active call

A frame gives the file, line number and function, followed by the relevant code. in <module> means top-level code. The oldest call is at the top; the most recent is at the bottom. Reading from the bottom reverses that order so you can ask what failed before asking how execution got there.

1. Line 2 divides by len(values). For that divisor to be zero, values must be empty.
2. Line 5 calls average(scores), so inspect the scores passed by report.
3. Line 8 supplies [], the empty list. That explains how the zero divisor reached the calculation.

The failing line and the cause are related, but they can be in different places. Replacing the division without deciding what an empty list should mean would hide the design question. Either the caller must avoid an empty list or the function needs a defined empty-input behavior.

Use highlights without depending on their exact shape

Python 3.11 and later can add ^ and ~ markers to show the failing part of an expression. They help when one line contains several operations. The exact highlighting varies between versions, but the call locations and exception message still give the reading order.

A traceback can contain frames from the standard library or an installed package. Find the lowest frame in your own code and inspect the arguments you supplied there. A library frame is a location clue; it is not evidence that the library contains the bug.

Recognize a syntax report

A syntax error in the script being started prevents that script from running. Python reports a file, line, marker and message without the usual traceback header. For example, if True is missing its colon; total = sum([1, 2, 3] leaves a parenthesis open.

The marked place is where Python noticed it could not parse the code. When that line looks valid, check the preceding line for an unclosed quote or parenthesis. There is no chain of runtime calls to follow when the starting script has not run.

An ordinary run stops at its first unhandled exception. Fix that problem and run again to expose anything later in the program.

An error's name narrows the search, and its message adds details about the values involved. A program can also be wrong without raising an exception, so checking its expected output remains part of finding errors.

Separate three kinds of problem

IndentationError is a kind of SyntaxError. A function body needs indentation; a missing indented block stops the code before it runs. Also inspect unclosed quotes or parentheses and misspelled keywords.

Read names and types closely

A NameError means the program does not know a name at that point. In prnt("hi"), the intended built-in is print. A name can also be used before assignment, or an import can be missing.

A TypeError means an operation received an unsuitable type or a call received the wrong number of arguments. "Age: " + 30 mixes a string and an integer. Write "Age: " + str(30) or f"Age: {30}". If area needs w and h, area(3) is also a TypeError, this time for a missing argument.

The message distinguishes these causes. In can only concatenate str (not "int") to str, Python names the types that met. After age = input("Age: "), age is text. age + 1 fails; for a whole-number entry, int(age) + 1 performs arithmetic.

A ValueError means the input's type is accepted, but its value is unsuitable. int("12.5") receives a string, which is an accepted input type, but the text does not represent a whole number in the required form. math.sqrt(-1) is another unsuitable value for a real-number calculation.

Check positions, keys and attributes

Zero divisors also fail with // and %. A missing list position is a different lookup from a missing dictionary key, even though both involve asking for something absent.

Detect a result that looks plausible

def total_price(prices):
    total = 0
    for i in range(1, len(prices)):
        total += prices[i]
    return total

For [4, 6, 10], this returns 16 instead of 20. There is no exception: indexes 1 and 2 exist, so every operation is legal. The loop starts too late and misses index 0. The error becomes visible when you compare the output with the intended total.

For an unfamiliar exception, look up its type and the general message in the official Python documentation. Remove your own paths and input values from a search; they rarely explain the general rule.

A bug is a difference between intended behavior and actual behavior. Debugging finds the cause and repairs it. A useful debugging session turns an observation into a testable explanation, then changes the code because of evidence.

Make the failure repeat

Record a specific input and the result it produces. For the price function that starts its loop at index 1, use [4, 6, 10]. The expected total is 20; the actual total is 16. These concrete values let you check whether each investigation still concerns the same bug.

The difference is 4, and the actual result equals 6 + 10. A specific hypothesis is that the first price is skipped. That hypothesis predicts something you can inspect: the loop will never visit index 0.

Follow six steps

1. Reproduce: find an input that shows the bug reliably.
2. State expected and actual results: calculate the expected result independently.
3. Form a hypothesis: name a possible cause and its predicted behavior.
4. Test it: inspect values with prints, a trace table or a debugger.
5. Fix the cause: make one focused change.
6. Retest: run the failing input and earlier working cases.

Print the index inside the loop. For this input, the only indexes are 1 and 2, confirming the prediction. Starting range at 0 fixes the skipped item. Iterating directly over the prices removes the need to manage an index:

def total_price(prices):
    total = 0
    for price in prices:
        total += price
    return total

The repaired function returns 20 for [4, 6, 10], 5 for [5] and 0 for []. The one-item case is useful because the buggy loop previously returned 0 for it.

Adding 4 to every answer would repair the observed total but leave the cause. For [5], that patch would return 4; the missing amount depends on the input. Check whether a proposed fix explains all the evidence before keeping it.

Narrow a larger search

Divide and conquer checks the values that feed the wrong result at a point partway through execution. If a needed value is already wrong, inspect the earlier code that produced it. If the needed values are still right, follow their later processing. Repeat inside the remaining section.

You can also call one function on its own or temporarily remove unrelated code. A minimal reproducible example keeps the shortest code and smallest input that still fail. For a problem first seen in hundreds of records, finding one or two records that trigger it makes every inspection easier.

Check what the data really is

A displayed 5 may be the string "5". "5" + "3" produces "53", while numeric addition gives 8. Inspect type(value) to check the type. Use repr(value) to reveal spaces and newline characters that an ordinary print can hide, such as ' Ada'.

Explain the code aloud, line by line, including what each loop actually visits and what each function returns. This is rubber duck debugging: explaining a step often exposes the gap between the intended operation and the written one.

Change one cause at a time so you can connect the result to the edit. Retest the cases that used to work as well as the one that failed.

A program's final answer hides the path that produced it. Temporary prints, a trace table and a debugger let you see that path and check a specific hypothesis about where it goes wrong.

Print a value at a known moment

Label diagnostic output so a number has a clear meaning. Python 3.8 and later support this f-string form:

print(f"{i=} {total=}")

For the buggy price loop, put it immediately before total += prices[i]. With prices [4, 6, 10], it prints:

i=1 total=0
i=2 total=6

These are totals before each addition. After the first print, the loop adds 6; after the second, it adds 10. A print after the addition would show different totals. Decide which moment answers your question before interpreting the output.

Trace the same code by hand

A trace table records variables step by step. For this loop:

There is no iteration for index 0. Follow the actual start and stop values written in the code, even when you already know what the loop ought to do. A table helps separate what you expect from what happens.

Pause at a breakpoint

A debugger pauses a running program to let you inspect its current state. A breakpoint marks a place to pause. In editors such as Thonny and VS Code, click beside a line number and start debug mode; in IDLE, right-click the line and choose Set Breakpoint.

After pausing, choose a step based on the question you are investigating:

If the caller passes correct arguments but receives a wrong answer, step into the function. If you only need to see the returned result, step over its call. Inspect the values before and after the line that might create the error.

Use Python's text debugger

Insert breakpoint() just before the code you want to inspect. With the default debugger configuration, running the program starts pdb at that point. Type these commands at its (Pdb) prompt:

• p total displays total.
• n steps over the next line.
• s steps into a function call.
• c continues execution.
• q quits the debugging session.

These are debugger commands, not lines to copy into your program.

Separate printed output from returned results

A function can print the right number and still return None because it lacks return total. Inspect the value received by the caller when the failure occurs after the function call. Seeing correct output inside the function does not establish that the caller received that number.

Use prints for quick evidence across loop iterations and the debugger to inspect a particular moment. After repairing the bug, remove temporary prints and breakpoint() calls so the finished program runs normally.

An assertion states something that must be true if your code is working correctly. It can stop a bug close to where it begins or compare a function's result with the value you expect.

Write a condition and an optional message

assert letter_grade(90) == "A", "90 should be an A"

Python evaluates the condition. If letter_grade(90) returns "A", the condition is true and execution continues without output. If it returns "B", Python raises AssertionError with the message 90 should be an A. The traceback points to the failing check.

Without the message, assert letter_grade(90) == "A" still checks the result. The final exception line contains AssertionError, while the traceback shows the expression. A useful message names the expectation that failed; it should help you locate the rule being checked.

Stop an internal mistake early

Suppose an internal calculation requires a nonempty list:

def average(values):
    assert len(values) > 0, "values must not be empty"
    return sum(values) / len(values)

An empty list now triggers the assertion before the division. The check documents the function's internal assumption and points directly to its violation. It does not give an empty list an average or decide how an application should respond to a user's missing data.

Keep user validation active

Python's -O option removes assert statements. A program that relies on an assertion to reject outside input can therefore behave differently when optimized. Check user input and other outside data with ordinary control flow:

def require_score(score):
    if score < 0 or score > 100:
        raise ValueError("score must be 0 to 100")
    return score

Here raise ValueError(...) reports an unsuitable value. The if statement still runs under -O. Choose an assertion for an internal programming assumption and an active input check for data that the outside world can get wrong.

Avoid a check that can never fail

assert is a statement, not a function. Write the condition and message separated by a comma:

assert x > 10, "x too small"

Writing assert (x > 10, "x too small") creates a two-item tuple. A nonempty tuple is true even when its first item is False, so the assertion passes. Python can warn that this assertion is always true. Parentheses around just a condition, as in assert (x > 10), do not create that tuple; the comma inside the parentheses is the problem.

Use == for comparison. assert total = 20 is invalid syntax because = assigns a value.

Compare numbers with the intended precision

For a calculated float, use a closeness check:

import math

assert math.isclose(0.1 + 0.2, 0.3)

An exact comparison fails here because the stored float sum differs slightly from 0.3. A simple automated test applies the same assertion idea to a function: assert total_price([4, 6, 10]) == 20. The expected value comes from the function's rule, so the check can expose a wrong implementation.

A unit test checks a small unit of code, usually one function, with a chosen input and an expected result. Automated tests make the same checks easy to repeat after edits, helping catch bugs that return in previously working behavior.

Start with the specification

Suppose a grading function must return "A" for scores of at least 90, "B" for scores of at least 80 but below 90, and "C" below 80. The buggy first condition is score > 90.

Tests should include several jobs:

• Typical cases check ordinary inputs inside each region, such as 95 and 85.
• Boundary cases check the values where a rule changes, such as 90 and 89, or 80 and 79.
• Edge cases check inputs such as zero or an empty collection when the function's rules allow them.

Work out the expected answer from those rules. Copying the current program's answer into a test can preserve its mistake.

Put the tests beside the module

Save tests in test_grade.py and the function in grade.py. The application launch in grade.py belongs under its __main__ guard, so importing the function does not start the program.

from grade import letter_grade

def test_letter_grade():
    assert letter_grade(95) == "A"
    assert letter_grade(90) == "A"
    assert letter_grade(85) == "B"

For the buggy rule, the first assertion passes. The second fails because 90 is not greater than 90; execution stops there, before the third assertion in this function. Changing the first condition to score >= 90 repairs this boundary. Rerun all tests to check the affected case and the earlier behavior.

Make sure the tests actually run

Defining a test function does not call it. With no test runner, add test_letter_grade() at the bottom of the test file, then run python test_grade.py. To use pytest, install it with python -m pip install pytest, then run pytest test_grade.py in the terminal. It finds the test functions and reports their results. Keep manual calls out when letting a runner manage them.

A test that merely calls letter_grade(90) has no comparison. It can finish successfully while the returned answer is wrong; it fails only if the call raises an unexpected exception. An assertion connects the call to the required behavior.

Test returned values and random properties

A function that only prints a total returns None. A comparison such as assert print_total([4, 6]) == 10 therefore fails even if the screen displays 10. Have the calculation return its answer, then let main handle printing.

Random results need a different expectation. An unseeded die function cannot be required to return one exact face on every call. Check that each of 100 calls returns an allowed value from 1 through 6, or seed before a repeatable sequence. Passing the bounds test checks the bounds for those calls; it does not establish that every face is equally likely.

When a new bug appears, add a test that fails because of it before repairing the function. Keep that regression test so later edits check the same behavior again. Passing tests establish what happened for the tested cases; more inputs can still reveal another bug.

Python includes unittest, a test framework that discovers tests, runs them and reports separate outcomes. It needs no pip installation. Its class structure can be used as a template while you are learning to test functions.

Write independent test methods

For a function in grade.py, put this in test_grade.py:

import unittest
from grade import letter_grade

class TestLetterGrade(unittest.TestCase):
    def test_top(self):
        self.assertEqual(letter_grade(95), "A")

    def test_boundary(self):
        self.assertEqual(letter_grade(90), "A")

    def test_low(self):
        self.assertEqual(letter_grade(50), "C")

if __name__ == "__main__":
    unittest.main()

TestLetterGrade inherits the test tools from unittest.TestCase. Each test is a method whose name starts with test. self identifies the current test object; keep it in each method's parameter list and before assertion method calls. You can copy this structure without designing classes of your own.

Tests run in alphabetical order of their method names by default, so test_boundary comes before test_low and test_top. Make every test supply its own needed input and work independently of previous tests.

Pick an assertion method

Prefer assertEqual(a, b) to assertTrue(a == b) when comparing values: the failure report shows the two values. The unittest methods also keep their checks when Python runs under -O.

To check an expected exception, enclose the call in assertRaises:

def test_score_too_high(self):
    with self.assertRaises(ValueError):
        letter_grade(120)

This test requires the function's rule to reject that score with ValueError. A return without an exception fails this check; a different non-assertion exception is an error.

Run and read the report

Run python test_grade.py to execute its guarded unittest.main(). Or run python -m unittest for discovery of test*.py files in the current folder. python -m unittest -v prints individual test names and their outcomes.

In the short report, . means pass, F means an assertion failed and E means another exception occurred. For a grading function with score > 90, the three tests above produce F... The failure report for test_boundary shows 'B' != 'A': the actual result is "B", while the expected result is "A". The summary reports three tests and one failure.

Before editing the function, check the test's expectation against the grading rules. A wrong expectation needs a test fix. If no tests run, inspect the method names, the direct-run guard and the launch command. Also avoid naming your file unittest.py, which hides the standard module.