🛑 Lesson 5: Error Handling in Depth

🤔 Why Error Handling Matters

In the real world, things go wrong constantly: files are missing, network connections drop, users enter garbage data, APIs return unexpected responses. Error handling is how your program responds gracefully instead of crashing.

You've already seen basic try/except blocks. In this lesson, we'll go much deeper — learning to write error-handling code that's precise, informative, and maintainable.

🌳 Python's Built-in Exception Hierarchy

Python's exceptions form a class hierarchy rooted at BaseException. Understanding this tree is essential for writing precise except clauses — because catching a parent class also catches all its children.

Common Built-in Exceptions

Checking the Hierarchy

# You can inspect the hierarchy with __mro__ (Method Resolution Order)
print(FileNotFoundError.__mro__)
# (<class 'FileNotFoundError'>, <class 'OSError'>, <class 'Exception'>,
#  <class 'BaseException'>, <class 'object'>)

# This means: catching OSError also catches FileNotFoundError!
print(issubclass(FileNotFoundError, OSError))   # True
print(issubclass(FileNotFoundError, Exception)) # True

🔄 The Full try/except/else/finally Pattern

Most developers know try/except, but the full four-part pattern gives you precise control over what runs when:

try:
    # Code that might fail
    result = risky_operation()

except SomeError as e:
    # Runs ONLY if SomeError (or its subclass) was raised
    print(f"Caught: {e}")

else:
    # Runs ONLY if NO exception occurred in try
    print(f"Success: {result}")

finally:
    # ALWAYS runs — exception or not, even if you return/break
    print("Cleanup done.")

Practical Example

def load_config(filepath):
    """Load a config file with full error handling."""
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            data = f.read()

    except FileNotFoundError:
        print(f"❌ Config file not found: {filepath}")
        return None

    except PermissionError:
        print(f"🔒 No permission to read: {filepath}")
        return None

    else:
        # Only runs if open + read succeeded
        print(f"✅ Loaded {len(data)} characters from {filepath}")
        return data

    finally:
        # Always runs — good for logging, metrics, cleanup
        print(f"📋 Attempted to load: {filepath}")


# Test it
config = load_config("settings.ini")
config = load_config("nonexistent.ini")

✅ Loaded 142 characters from settings.ini
📋 Attempted to load: settings.ini
❌ Config file not found: nonexistent.ini
📋 Attempted to load: nonexistent.ini

# ❌ Bad: processing code inside try — a bug in process_data()
#    could be caught by except ValueError
try:
    raw = input("Enter a number: ")
    number = int(raw)
    result = process_data(number)  # Bug here? Caught below!
except ValueError:
    print("Not a number!")

# ✅ Good: only the risky part is in try
try:
    raw = input("Enter a number: ")
    number = int(raw)
except ValueError:
    print("Not a number!")
else:
    result = process_data(number)  # Bug here? Propagates normally

🎯 Catching Multiple Exceptions

You have several options for handling different exceptions differently:

Separate except Clauses

try:
    value = int(user_input)
    result = data[value]
except ValueError:
    print("Please enter a valid integer.")
except IndexError:
    print(f"Index out of range. Valid: 0–{len(data) - 1}")
except Exception as e:
    print(f"Unexpected error: {type(e).__name__}: {e}")

Catching Multiple Types in One Clause

If you want the same handler for several exceptions, use a tuple:

try:
    result = parse_and_calculate(user_input)
except (ValueError, TypeError, ArithmeticError) as e:
    print(f"Input error: {e}")
    result = None

Accessing Exception Details

The as e syntax binds the exception instance so you can inspect it:

try:
    with open("data.json", "r") as f:
        data = json.load(f)
except json.JSONDecodeError as e:
    print(f"JSON parse error in {e.doc[:20]}...")
    print(f"  Line {e.lineno}, Column {e.colno}")
    print(f"  Message: {e.msg}")
except FileNotFoundError as e:
    print(f"Missing file: {e.filename}")
    print(f"  Error number: {e.errno}")

🚀 Raising & Chaining Exceptions

Raising Exceptions

Use raise to signal that something has gone wrong. This is how your functions communicate errors to their callers:

def set_age(age):
    if not isinstance(age, int):
        raise TypeError(f"Age must be an integer, got {type(age).__name__}")
    if age < 0 or age > 150:
        raise ValueError(f"Age must be 0–150, got {age}")
    return age

# These work
set_age(25)   # 25
set_age(0)    # 0

# These raise
set_age("old")   # TypeError: Age must be an integer, got str
set_age(-5)      # ValueError: Age must be 0–150, got -5

Re-raising Exceptions

Sometimes you want to catch an exception, do something (like log it), and then let it continue propagating. Use bare raise:

def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"⚠️ Logging: {path} not found")
        raise  # Re-raises the SAME exception with original traceback

Exception Chaining with from

When you catch one exception and raise a different one, you can preserve the original cause with raise ... from ...:

class ConfigError(Exception):
    """Error loading application configuration."""
    pass

def load_config(path):
    try:
        with open(path) as f:
            return json.load(f)
    except FileNotFoundError as e:
        raise ConfigError(f"Config file missing: {path}") from e
    except json.JSONDecodeError as e:
        raise ConfigError(f"Invalid JSON in {path}") from e


try:
    config = load_config("bad_config.json")
except ConfigError as e:
    print(f"Config error: {e}")
    print(f"Caused by: {e.__cause__}")

Config error: Config file missing: bad_config.json
Caused by: [Errno 2] No such file or directory: 'bad_config.json'

🏗️ Custom Exception Classes

Custom exceptions make your error handling semantic — callers can catch InsufficientFundsError instead of guessing which ValueError means what.

Basic Custom Exception

class InsufficientFundsError(Exception):
    """Raised when a withdrawal exceeds the account balance."""
    pass

class BankAccount:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self.balance = balance

    def withdraw(self, amount):
        if amount > self.balance:
            raise InsufficientFundsError(
                f"Cannot withdraw ${amount:.2f} — "
                f"balance is ${self.balance:.2f}"
            )
        self.balance -= amount
        return self.balance


account = BankAccount("Alice", 100)

try:
    account.withdraw(150)
except InsufficientFundsError as e:
    print(f"❌ {e}")

❌ Cannot withdraw $150.00 — balance is $100.00

Custom Exceptions with Extra Data

Add attributes to carry structured information about the error:

class ValidationError(Exception):
    """Raised when input validation fails."""

    def __init__(self, field, value, message):
        self.field = field
        self.value = value
        self.message = message
        super().__init__(f"{field}: {message} (got {value!r})")


def validate_email(email):
    if not isinstance(email, str):
        raise ValidationError("email", email, "must be a string")
    if "@" not in email:
        raise ValidationError("email", email, "must contain @")
    if not email.endswith((".com", ".org", ".net", ".edu")):
        raise ValidationError("email", email, "unsupported domain")
    return email


try:
    validate_email("bob_at_gmail")
except ValidationError as e:
    print(f"❌ Validation failed!")
    print(f"   Field: {e.field}")
    print(f"   Value: {e.value!r}")
    print(f"   Reason: {e.message}")

❌ Validation failed!
   Field: email
   Value: 'bob_at_gmail'
   Reason: must contain @

🌳 Exception Hierarchies in Practice

For larger projects, organize your custom exceptions into a hierarchy. This lets callers choose their level of granularity — catch a broad category or a specific error.

class AppError(Exception):
    """Base exception for our application."""
    pass

class DatabaseError(AppError):
    """Base for all database-related errors."""
    pass

class ConnectionError(DatabaseError):
    """Failed to connect to the database."""
    pass

class QueryError(DatabaseError):
    """A database query failed."""
    pass

class AuthError(AppError):
    """Base for authentication/authorization errors."""
    pass

class InvalidCredentialsError(AuthError):
    """Wrong username or password."""
    pass

class PermissionDeniedError(AuthError):
    """User lacks required permissions."""
    pass

Now callers can choose their specificity:

# Catch everything from our app
try:
    do_something()
except AppError as e:
    print(f"App error: {e}")

# Catch only database issues
try:
    query_database()
except DatabaseError as e:
    print(f"DB problem: {e}")

# Catch a specific auth issue
try:
    login(username, password)
except InvalidCredentialsError:
    print("Wrong username or password.")
except AuthError:
    print("Authentication problem — please try again.")

📋 The logging Module

Using print() for debugging and error reporting is a beginner habit that doesn't scale. Python's built-in logging module gives you leveled output, configurable destinations, and structured formatting — all with very little setup.

Why logging Over print()?

Quick Start

import logging

# Configure the root logger
logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)-8s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)

logger = logging.getLogger(__name__)

logger.debug("Starting data processing...")
logger.info("Loaded 1,024 records from database.")
logger.warning("Disk usage at 87% — consider cleanup.")
logger.error("Failed to connect to payment API.")
logger.critical("Database is unreachable — shutting down.")

2026-04-12 10:30:01 [DEBUG   ] __main__: Starting data processing...
2026-04-12 10:30:01 [INFO    ] __main__: Loaded 1,024 records from database.
2026-04-12 10:30:01 [WARNING ] __main__: Disk usage at 87% — consider cleanup.
2026-04-12 10:30:01 [ERROR   ] __main__: Failed to connect to payment API.
2026-04-12 10:30:01 [CRITICAL] __main__: Database is unreachable — shutting down.

Logging to a File

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler("app.log", encoding="utf-8"),
        logging.StreamHandler()  # Also print to console
    ]
)

logger = logging.getLogger(__name__)
logger.info("Application started.")
logger.error("Something went wrong!")

Logging Exceptions with Tracebacks

The killer feature of logging is exc_info=True, which automatically includes the full traceback:

import logging

logger = logging.getLogger(__name__)

def divide(a, b):
    try:
        return a / b
    except ZeroDivisionError:
        logger.error("Division by zero!", exc_info=True)
        return None

result = divide(10, 0)

2026-04-12 10:30:01 [ERROR   ] __main__: Division by zero!
Traceback (most recent call last):
  File "example.py", line 7, in divide
    return a / b
ZeroDivisionError: division by zero

You can also use logger.exception() as a shortcut — it's the same as logger.error(..., exc_info=True):

try:
    risky_operation()
except SomeError:
    logger.exception("Operation failed")  # Includes traceback automatically

Named Loggers

In larger projects, use named loggers to trace which module generated each message:

# In database.py
logger = logging.getLogger("myapp.database")
logger.info("Connected to PostgreSQL")

# In auth.py
logger = logging.getLogger("myapp.auth")
logger.warning("Failed login attempt for user: admin")

# In main.py — configure once
logging.basicConfig(level=logging.DEBUG)
# Now all "myapp.*" loggers output through the root logger

🏋️ Hands-on Exercises

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)-8s] %(message)s",
    datefmt="%H:%M:%S"
)
logger = logging.getLogger(__name__)


def parse_number(value):
    """Parse a string into int or float."""
    # TODO: Try int first, then float, raise ValueError if both fail
    pass


def safe_divide(a, b):
    """Divide a by b with full error handling."""
    # TODO: Use try/except/else/finally
    #   - try: perform division
    #   - except: handle ZeroDivisionError and TypeError
    #   - else: log the successful result
    #   - finally: log that division was attempted
    pass


# Test cases
test_values = ["42", "3.14", "0xFF", "hello", "", "  7  "]
for val in test_values:
    try:
        result = parse_number(val)
        logger.info(f"parse_number({val!r}) = {result}")
    except ValueError as e:
        logger.error(f"parse_number({val!r}) failed: {e}")

print()
safe_divide(10, 3)
safe_divide(10, 0)
safe_divide("10", 3)

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)-8s] %(message)s",
    datefmt="%H:%M:%S"
)
logger = logging.getLogger(__name__)


def parse_number(value):
    """Parse a string into int or float."""
    cleaned = value.strip()
    if not cleaned:
        raise ValueError(f"Cannot parse empty string as a number")

    try:
        return int(cleaned)
    except ValueError:
        pass  # Not an int, try float

    try:
        return float(cleaned)
    except ValueError:
        raise ValueError(
            f"Cannot parse {value!r} as int or float"
        )


def safe_divide(a, b):
    """Divide a by b with full error handling."""
    try:
        result = a / b
    except ZeroDivisionError:
        logger.error(f"Cannot divide {a} by zero")
        return None
    except TypeError as e:
        logger.error(f"Type error in division: {e}")
        return None
    else:
        logger.info(f"{a} / {b} = {result:.4f}")
        return result
    finally:
        logger.debug(f"Division attempted: {a!r} / {b!r}")


# Test cases
test_values = ["42", "3.14", "0xFF", "hello", "", "  7  "]
for val in test_values:
    try:
        result = parse_number(val)
        logger.info(f"parse_number({val!r}) = {result}")
    except ValueError as e:
        logger.error(f"parse_number({val!r}) failed: {e}")

print()
safe_divide(10, 3)
safe_divide(10, 0)
safe_divide("10", 3)

import logging
from pathlib import Path

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)-8s] %(message)s",
    datefmt="%H:%M:%S"
)
logger = logging.getLogger("config_loader")

# --- Custom Exception Hierarchy ---

class ConfigError(Exception):
    """Base exception for configuration errors."""
    pass

class ConfigNotFoundError(ConfigError):
    """Config file does not exist."""
    pass

class ConfigParseError(ConfigError):
    """Config file has invalid syntax."""
    pass

class ConfigValidationError(ConfigError):
    """Config values fail validation."""
    pass


# --- Config Loader ---

REQUIRED_KEYS = {"host", "port", "debug"}

def load_config(path):
    """Load and validate a key=value config file."""
    path = Path(path)
    logger.info(f"Loading config from: {path}")

    # Step 1: Read the file
    try:
        text = path.read_text(encoding="utf-8")
    except FileNotFoundError as e:
        raise ConfigNotFoundError(f"Config not found: {path}") from e
    except PermissionError as e:
        raise ConfigError(f"Cannot read {path}: permission denied") from e

    # Step 2: Parse key=value pairs
    config = {}
    for line_num, line in enumerate(text.splitlines(), start=1):
        line = line.strip()
        if not line or line.startswith("#"):
            continue  # Skip blanks and comments
        if "=" not in line:
            raise ConfigParseError(
                f"Line {line_num}: expected key=value, got {line!r}"
            )
        key, value = line.split("=", 1)
        config[key.strip()] = value.strip()

    logger.debug(f"Parsed {len(config)} config entries")

    # Step 3: Validate required keys
    missing = REQUIRED_KEYS - config.keys()
    if missing:
        raise ConfigValidationError(
            f"Missing required keys: {', '.join(sorted(missing))}"
        )

    # Step 4: Validate port
    try:
        port = int(config["port"])
    except ValueError as e:
        raise ConfigValidationError(
            f"'port' must be an integer, got {config['port']!r}"
        ) from e

    if not (1 <= port <= 65535):
        raise ConfigValidationError(
            f"'port' must be 1–65535, got {port}"
        )
    config["port"] = port

    # Step 5: Parse debug as boolean
    config["debug"] = config["debug"].lower() in ("true", "1", "yes")

    logger.info(f"Config loaded: host={config['host']}, "
                f"port={config['port']}, debug={config['debug']}")
    return config


# --- Test ---

# Create a sample config file
sample_config = """# App Configuration
host = localhost
port = 8080
debug = true
database = postgres://localhost/mydb
"""

Path("app.cfg").write_text(sample_config, encoding="utf-8")

try:
    config = load_config("app.cfg")
    print(f"Config: {config}")
except ConfigNotFoundError as e:
    logger.error(f"File missing: {e}")
except ConfigParseError as e:
    logger.error(f"Parse error: {e}")
except ConfigValidationError as e:
    logger.error(f"Validation error: {e}")
except ConfigError as e:
    logger.error(f"Config error: {e}")

📏 Best Practices

✅ Do's

• Catch specific exceptions — not bare except: or except Exception: unless you're at the top-level entry point
• Use else to separate the "risky" code from the "success" code
• Use finally for cleanup that must happen regardless (closing connections, releasing locks)
• Chain exceptions with from when wrapping low-level errors in domain-specific ones
• Use logging instead of print() — it's trivial to set up and infinitely more useful
• Use logger.exception() inside except blocks to automatically include tracebacks
• Include context in error messages — "File not found" is bad; "Config file not found: /etc/app/settings.ini" is good

❌ Don'ts

• Don't use bare except: — it catches KeyboardInterrupt and SystemExit, making your program impossible to stop
• Don't silently swallow exceptions — except: pass hides bugs. At minimum, log the error
• Don't catch exceptions too broadly — except Exception at every call site masks bugs
• Don't use exceptions for flow control — checking if key in dict is better than catching KeyError in normal flow
• Don't inherit from BaseException — always inherit from Exception for custom errors

💡 Pro Tips

• Use logging.getLogger(__name__) in every module — it automatically creates a logger hierarchy matching your package structure
• Configure logging once in your main() or entry point — don't call basicConfig() in library code
• For production apps, use logging.handlers.RotatingFileHandler to prevent log files from growing forever
• The warnings module is for deprecation notices and non-fatal issues — don't confuse it with logging

📝 Summary

📚 Additional Resources

• Python Docs — Errors and Exceptions
• Python Docs — Built-in Exceptions
• Python Docs — logging Module
• Python Logging HOWTO

🚀 What's Next?

In the next lesson, we'll explore Regular Expressions — Python's re module for powerful pattern matching, text search, and data extraction.