8.2 Debugging Tools and Techniques for Python

NicePython

— 6 min read

Debugging is an essential skill in software development that allows you to find and fix errors or bugs in your code. Effective debugging helps you identify where your code is going wrong and why it is not producing the expected output. Python provides several built-in tools and techniques that can help streamline the debugging process, making it easier to trace the flow of execution, inspect variables, and understand the behavior of your code.

In this section, we’ll cover various debugging tools and techniques, from basic print statements to more advanced debugging with Python's built-in pdb module and Integrated Development Environments (IDEs).

8.2.1 Basic Debugging with print() Statements

One of the simplest and most common debugging techniques is using print() statements. By printing the values of variables at different points in your code, you can trace the program’s execution and verify that the code behaves as expected.

Example:

def calculate_sum(numbers):
    total = 0
    for number in numbers:
        print(f"Adding {number} to total {total}")  # Debugging print statement
        total += number
    print(f"Final total: {total}")  # Debugging print statement
    return total

calculate_sum([1, 2, 3, 4])

In this example:

  • print() statements are added inside the loop and at the end of the function to show the progress of the calculation.
  • You can inspect the intermediate values of total to verify the correctness of the program’s logic.

8.2.2 Using assert for Debugging

The assert statement is used to test if a condition is True. If the condition is False, it raises an AssertionError. You can use assert to check for expected values or conditions in your code and halt execution if something goes wrong.

Syntax:

assert condition, "Error message if condition is False"

Example:

def divide(a, b):
    assert b != 0, "Error: Division by zero"
    return a / b

print(divide(10, 2))  # Works fine
print(divide(10, 0))  # Raises AssertionError with the message

In this example:

  • The assert statement ensures that the denominator b is not zero before performing the division.
  • If b is zero, an AssertionError is raised with the message "Error: Division by zero", which helps identify the issue early.

8.2.3 Using the Python Debugger (pdb)

Python’s built-in debugger, pdb, is a powerful tool for debugging your code. It allows you to pause execution, inspect variables, set breakpoints, and step through your code line by line.

Basic Commands in pdb:

  • b: Set a breakpoint at a specific line or function.
  • c: Continue execution until the next breakpoint.
  • s: Step into the next line or function call.
  • n: Step over the next line without stepping into a function.
  • p: Print the value of a variable or expression.
  • q: Quit the debugger.

Example: Using pdb for Debugging:

import pdb

def calculate_sum(numbers):
    pdb.set_trace()  # Set a breakpoint here
    total = 0
    for number in numbers:
        total += number
    return total

# Debugging session
calculate_sum([1, 2, 3, 4])

In this example:

  • The pdb.set_trace() function starts the debugger at the point where it is called.
  • You can then use pdb commands to step through the code, inspect variables, and control the flow of execution.

Running the Debugger:
When the program runs, it will pause at the pdb.set_trace() line, and you can interact with the code using commands like n (next line), p total (print the value of total), and c (continue).

8.2.4 Breakpoints in IDEs (e.g., PyCharm, VS Code)

Modern Integrated Development Environments (IDEs) like PyCharm and Visual Studio Code (VS Code) offer advanced debugging features, including breakpoints, step-through execution, and variable inspection. These features make it easier to debug large and complex programs without manually adding print() statements.

How to Use Breakpoints in an IDE:

  1. Set a Breakpoint: Click in the margin next to the line number where you want the program to pause.
  2. Run in Debug Mode: Start your program in debug mode (usually an option in the IDE toolbar).
  3. Inspect Variables: Once the program hits the breakpoint, you can inspect variables, step through the code, and modify the state of your program.

Advantages of Using an IDE:

  • Graphical Interface: You can set and manage breakpoints visually, making it easier to control the debugging process.
  • Real-time Variable Inspection: View and modify variables on the fly without having to modify your code.
  • Step-by-step Execution: Step into, over, or out of functions, allowing precise control over the execution of your program.

8.2.5 Using Logging for Debugging

While print() statements are useful for basic debugging, logging is a more robust and flexible way to track the flow of your program and capture information about its execution. The logging module in Python allows you to record debug messages, warnings, errors, and other information to the console or to a log file.

Basic Logging Setup:

import logging

# Configure logging
logging.basicConfig(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s")

# Example usage
def calculate_sum(numbers):
    logging.debug(f"Starting sum calculation for: {numbers}")
    total = sum(numbers)
    logging.debug(f"Total calculated: {total}")
    return total

calculate_sum([1, 2, 3, 4])

In this example:

  • logging.debug() is used to log detailed debugging information.
  • The logging configuration sets the logging level to DEBUG, meaning that all debug-level messages and above (like errors or warnings) will be shown.
  • You can change the logging level to INFO, WARNING, ERROR, or CRITICAL to control what kinds of messages are logged.

Why Use Logging Instead of print()?

  • Control Over Output: You can adjust the verbosity of the output by changing the logging level.
  • Persistent Logs: Logs can be written to files for later analysis, making it easier to track the program’s behavior over time.
  • Structured Information: Logging provides detailed information, including timestamps, log levels, and custom messages, helping you identify and debug problems more effectively.

8.2.6 Using traceback to Print Error Details

The traceback module provides a way to print detailed error information when exceptions occur. This can help you understand where and why an error occurred by displaying the stack trace.

Example: Using traceback to Debug Exceptions:

import traceback

def divide(a, b):
    try:
        return a / b
    except ZeroDivisionError:
        print("An error occurred:")
        traceback.print_exc()  # Prints the full traceback for debugging

divide(10, 0)

In this example:

  • The traceback.print_exc() function prints the stack trace of the exception, showing exactly where the error occurred and making it easier to debug.
  • This is useful when you want to handle exceptions but still need detailed error information for debugging.

8.2.7 Using a Debugger in Jupyter Notebooks

If you are working in a Jupyter Notebook, you can use the %debug magic command to invoke the Python debugger after an exception is raised. This allows you to explore the state of the program at the point where the error occurred.

Example: Debugging in Jupyter Notebook:

def divide(a, b):
    return a / b

divide(10, 0)  # This will raise a ZeroDivisionError

# After the error occurs, run:
%debug

In this example:

  • After the ZeroDivisionError is raised, running %debug starts the interactive debugger in the notebook, allowing you to inspect variables and step through the code.
  • You can use p to print variable values, n to step to the next line, and other pdb commands.

8.2.8 Best Practices for Debugging

  1. Start Simple: Begin with basic debugging techniques like print() statements to narrow down the issue before moving on to more advanced tools.
  2. Use a Debugger: For larger or more complex projects, using a debugger like pdb or the debugging tools in an IDE can save time and give you more control.
  3. Log Important Information: Use logging to track critical events in your program’s execution, especially in production environments where you can’t use interactive debugging

.
4. Break Down the Problem: If the issue is complex, break the problem into smaller parts and test each component individually.
5. Test with Different Inputs: Test your code with various inputs, including edge cases, to ensure it handles all scenarios correctly.
6. Avoid Excessive print() Statements: While print() statements are useful for small projects, excessive use can clutter your code. Switch to logging when debugging larger projects.

8.2.9 Summary

  • print() statements: Simple but effective for basic debugging. Use them to trace the flow of execution and inspect variables.
  • assert statements: Useful for checking conditions during debugging and halting execution if a condition is not met.
  • pdb debugger: Python’s built-in debugger allows you to pause execution, inspect variables, and step through code line by line.
  • IDE Breakpoints: Use breakpoints in IDEs like PyCharm or VS Code to inspect your program interactively and manage execution flow.
  • Logging: The logging module provides a more structured and scalable way to track your program’s execution and record debug information.
  • traceback: Provides detailed error information when exceptions occur, helping you identify the root cause of errors.
  • Jupyter Notebooks: Use the %debug magic command to interactively debug errors directly in your notebook.

By mastering these debugging tools and techniques, you’ll be better equipped to identify and fix errors in your code, leading to more robust and reliable software development.

Read more