Raising Exceptions

Intermediate ~30 min read

Sometimes you need to signal an error yourself - when validation fails, when preconditions aren't met, or when something unexpected happens. The raise statement lets you throw exceptions, create custom exception types for your application, and chain exceptions to preserve error context!

Basic Raise Statement

Use raise ExceptionType("message") to throw an exception. Choose the appropriate built-in exception type - ValueError for invalid values, TypeError for wrong types, KeyError for missing keys. Always include a descriptive message.

# Basic Raise Statement

print("=== Basic Raise ===\n")

# 1. Raise with message
print("1. Raise with message:")
try:
    age = -5
    if age < 0:
        raise ValueError("Age cannot be negative")
except ValueError as e:
    print(f"   Caught: {e}")
print()

# 2. Raise different exception types
print("2. Different exception types:")

def validate_input(value):
    if value is None:
        raise TypeError("Value cannot be None")
    if not isinstance(value, (int, float)):
        raise TypeError(f"Expected number, got {type(value).__name__}")
    if value < 0:
        raise ValueError("Value must be non-negative")
    if value > 100:
        raise ValueError("Value must be <= 100")
    return value

test_values = [None, "hello", -5, 150, 50]
for val in test_values:
    try:
        result = validate_input(val)
        print(f"   {val!r:10} -> Valid: {result}")
    except (TypeError, ValueError) as e:
        print(f"   {val!r:10} -> Error: {e}")
print()

# 3. Raise without message (not recommended)
print("3. Raise with minimal info:")
try:
    raise RuntimeError  # No message - less helpful
except RuntimeError as e:
    print(f"   Caught RuntimeError: '{e}'")
    print(f"   args: {e.args}")
print()

# 4. Raise with multiple arguments
print("4. Exception with multiple args:")
try:
    raise ValueError("Invalid value", 42, "expected positive")
except ValueError as e:
    print(f"   Message: {e}")
    print(f"   All args: {e.args}")
print()

# 5. Common patterns for validation
print("5. Validation patterns:")

def process_config(config):
    """Validate and process configuration."""
    if not isinstance(config, dict):
        raise TypeError(f"Config must be dict, got {type(config).__name__}")

required = ['host', 'port', 'timeout']
    missing = [key for key in required if key not in config]
    if missing:
        raise KeyError(f"Missing required config keys: {missing}")

if not isinstance(config['port'], int):
        raise TypeError("Port must be integer")
    if not 1 <= config['port'] <= 65535:
        raise ValueError(f"Port {config['port']} out of range (1-65535)")

return config

# Test configurations
configs = [
    "not a dict",
    {"host": "localhost"},
    {"host": "localhost", "port": "80", "timeout": 30},
    {"host": "localhost", "port": 99999, "timeout": 30},
    {"host": "localhost", "port": 8080, "timeout": 30},
]

for config in configs:
    try:
        result = process_config(config)
        print(f"   Valid config: {result}")
    except (TypeError, KeyError, ValueError) as e:
        print(f"   Invalid: {type(e).__name__}: {e}")

Output

Click Run to execute your code

When to Raise Which Exception:
ValueError - Right type, wrong value: raise ValueError("age must be positive")
TypeError - Wrong type: raise TypeError("expected string")
KeyError - Missing key: raise KeyError("config missing 'host'")
RuntimeError - General runtime issue: raise RuntimeError("state corrupted")
NotImplementedError - Subclass must override: raise NotImplementedError

Re-raising Exceptions

Sometimes you want to catch an exception, do something (like logging), and then let it propagate. Use bare raise (without arguments) to re-raise the current exception. This preserves the original traceback, which is crucial for debugging.

# Re-raising Exceptions

print("=== Re-raising Exceptions ===\n")

# 1. Basic re-raise with bare 'raise'
print("1. Re-raise after logging:")

def process_data(data):
    try:
        return int(data) * 2
    except ValueError:
        print(f"   [LOG] Failed to process: {data!r}")
        raise  # Re-raise the same exception

try:
    process_data("not a number")
except ValueError as e:
    print(f"   Caught: {e}")
print()

# 2. Re-raise preserves traceback
print("2. Traceback is preserved:")

def level1():
    raise ValueError("Original from level1")

def level2():
    try:
        level1()
    except ValueError:
        print("   [LOG] Error in level2, re-raising")
        raise  # Traceback shows level1 as origin

def level3():
    level2()

try:
    level3()
except ValueError as e:
    print(f"   Caught at top: {e}")
print()

# 3. Modify and re-raise (anti-pattern warning)
print("3. Adding context before re-raise:")

def process_file(filename):
    try:
        with open(filename) as f:
            return f.read()
    except FileNotFoundError:
        # Log and re-raise - don't lose the original
        print(f"   [LOG] File not found: {filename}")
        raise

try:
    process_file("missing.txt")
except FileNotFoundError as e:
    print(f"   Caught: {e.filename}")
print()

# 4. Common pattern: cleanup then re-raise
print("4. Cleanup before re-raise:")

class Connection:
    def __init__(self, name):
        self.name = name
        self.open = False

def connect(self):
        self.open = True
        print(f"   Connected to {self.name}")

def close(self):
        self.open = False
        print(f"   Closed {self.name}")

def risky_operation(conn):
    conn.connect()
    try:
        # Simulate failure
        raise RuntimeError("Operation failed!")
    except RuntimeError:
        print("   Cleaning up before re-raising...")
        conn.close()
        raise

conn = Connection("database")
try:
    risky_operation(conn)
except RuntimeError as e:
    print(f"   Caught: {e}")
    print(f"   Connection open: {conn.open}")  # False - cleaned up!
print()

# 5. Wrong: raising new exception loses context
print("5. Wrong: Creating new exception loses context:")

def bad_reraise():
    try:
        int("not a number")
    except ValueError as e:
        # BAD: Creates new exception, loses original traceback
        raise ValueError(f"Failed: {e}")  # New exception!

def good_reraise():
    try:
        int("not a number")
    except ValueError:
        # GOOD: Preserves original
        print("   [LOG] Conversion failed")
        raise  # Same exception, same traceback

print("   Bad way: raise ValueError(f'...')")
print("   Good way: just 'raise'")
print()

# 6. When to use new exception vs re-raise
print("6. Guidelines:")
print("""
Use bare 'raise' when:
- Logging but letting caller handle
- Cleanup before propagating
- Adding context without changing type

Use 'raise NewException()' when:
- Converting internal errors to API errors
- Hiding implementation details
- Exception chaining (next section!)
""")

Output

Click Run to execute your code

Re-raise Best Practices:
raise - Bare raise preserves original traceback
raise ValueError(...) - Creates NEW exception, loses original traceback

Use bare raise when you want to log and continue propagating. Use raise NewException() from original when converting exception types.

Custom Exception Classes

Create custom exceptions by inheriting from Exception. This lets you add attributes, create exception hierarchies, and provide domain-specific error handling. Always inherit from Exception, not BaseException.

# Custom Exception Classes

print("=== Custom Exceptions ===\n")

# 1. Basic custom exception
print("1. Simple custom exception:")

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

try:
    raise ValidationError("Email format is invalid")
except ValidationError as e:
    print(f"   Caught ValidationError: {e}")
print()

# 2. Custom exception with attributes
print("2. Exception with extra attributes:")

class ConfigError(Exception):
    """Raised when configuration is invalid."""
    def __init__(self, message, key=None, value=None):
        super().__init__(message)
        self.key = key
        self.value = value

try:
    raise ConfigError("Invalid port number", key="port", value=-1)
except ConfigError as e:
    print(f"   Message: {e}")
    print(f"   Key: {e.key}")
    print(f"   Value: {e.value}")
print()

# 3. Exception hierarchy for an application
print("3. Exception hierarchy:")

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

# Specific exceptions inherit from base
class AuthError(AppError):
    """Authentication/authorization errors."""
    pass

class DatabaseError(AppError):
    """Database-related errors."""
    pass

class NotFoundError(DatabaseError):
    """Resource not found in database."""
    def __init__(self, resource_type, resource_id):
        super().__init__(f"{resource_type} with id {resource_id} not found")
        self.resource_type = resource_type
        self.resource_id = resource_id

# Using the hierarchy
def get_user(user_id):
    if user_id < 0:
        raise AuthError("Invalid user ID")
    if user_id == 0:
        raise NotFoundError("User", user_id)
    return {"id": user_id, "name": "Alice"}

test_ids = [-1, 0, 42]
for uid in test_ids:
    try:
        user = get_user(uid)
        print(f"   ID {uid}: Got user {user}")
    except NotFoundError as e:
        print(f"   ID {uid}: {e.resource_type} not found")
    except AuthError as e:
        print(f"   ID {uid}: Auth error: {e}")
    except AppError as e:
        print(f"   ID {uid}: App error: {e}")
print()

# 4. Custom __str__ method
print("4. Custom string representation:")

class APIError(Exception):
    """API call failed."""
    def __init__(self, endpoint, status_code, message):
        self.endpoint = endpoint
        self.status_code = status_code
        self.message = message
        super().__init__(self._format_message())

def _format_message(self):
        return f"API {self.endpoint} failed ({self.status_code}): {self.message}"

try:
    raise APIError("/users", 404, "User not found")
except APIError as e:
    print(f"   {e}")
    print(f"   Status: {e.status_code}")
print()

# 5. Practical example: Form validation
print("5. Form validation exceptions:")

class FieldError(Exception):
    """Single field validation error."""
    def __init__(self, field, message):
        super().__init__(f"{field}: {message}")
        self.field = field
        self.message = message

class FormError(Exception):
    """Multiple field validation errors."""
    def __init__(self, errors):
        self.errors = errors  # List of FieldError
        messages = [str(e) for e in errors]
        super().__init__("Form validation failed: " + "; ".join(messages))

def validate_signup(data):
    errors = []

if not data.get('email') or '@' not in data.get('email', ''):
        errors.append(FieldError('email', 'Invalid email format'))

password = data.get('password', '')
    if len(password) < 8:
        errors.append(FieldError('password', 'Must be at least 8 characters'))

if not data.get('username'):
        errors.append(FieldError('username', 'Required'))

if errors:
        raise FormError(errors)

return True

# Test form validation
forms = [
    {'email': 'bad', 'password': '123', 'username': ''},
    {'email': 'good@email.com', 'password': 'secure123', 'username': 'alice'},
]

for form in forms:
    try:
        validate_signup(form)
        print(f"   Form valid: {form}")
    except FormError as e:
        print(f"   Form invalid:")
        for err in e.errors:
            print(f"     - {err.field}: {err.message}")

Output

Click Run to execute your code

Custom Exception Guidelines:
- Always inherit from Exception (not BaseException)
- Call super().__init__(message) in your __init__
- Add useful attributes (error codes, field names, etc.)
- Create a base exception for your app: class MyAppError(Exception)
- Specific exceptions inherit from base: class AuthError(MyAppError)

Exception Chaining

Exception chaining preserves the original error when wrapping it in a new exception. Use raise NewException() from original to explicitly chain. Use raise NewException() from None to suppress the chain (hide internal details).

# Exception Chaining

print("=== Exception Chaining ===\n")

# 1. Implicit chaining (during handling)
print("1. Implicit chaining (__context__):")

try:
    try:
        int("not a number")
    except ValueError:
        # This exception happens DURING handling
        d = {}
        value = d["missing"]  # KeyError during ValueError handling
except KeyError as e:
    print(f"   Caught KeyError: {e}")
    print(f"   Original exception: {e.__context__}")
print()

# 2. Explicit chaining with 'from'
print("2. Explicit chaining with 'from':")

class ConfigError(Exception):
    pass

def load_config(filename):
    try:
        with open(filename) as f:
            import json
            return json.load(f)
    except FileNotFoundError as e:
        # Chain the original cause
        raise ConfigError(f"Config file '{filename}' not found") from e
    except json.JSONDecodeError as e:
        raise ConfigError(f"Invalid JSON in '{filename}'") from e

try:
    load_config("nonexistent.json")
except ConfigError as e:
    print(f"   ConfigError: {e}")
    print(f"   Caused by: {e.__cause__}")
print()

# 3. Suppress chaining with 'from None'
print("3. Suppress chaining with 'from None':")

def get_user_safe(user_id):
    try:
        # Simulate internal lookup error
        raise KeyError(f"user_{user_id}")
    except KeyError:
        # Hide internal implementation detail
        raise ValueError(f"User {user_id} not found") from None

try:
    get_user_safe(42)
except ValueError as e:
    print(f"   ValueError: {e}")
    print(f"   __cause__: {e.__cause__}")  # None - suppressed
    print(f"   __context__: {e.__context__}")  # Still set internally
    print(f"   __suppress_context__: {e.__suppress_context__}")  # True
print()

# 4. Practical example: API wrapper
print("4. Practical: API error wrapping:")

import json

class APIError(Exception):
    """Public API error."""
    def __init__(self, message, status_code=500):
        super().__init__(message)
        self.status_code = status_code

def fetch_user_data(user_id):
    """Simulate fetching user data."""
    # Simulate different internal errors
    if user_id < 0:
        raise ValueError("Internal: negative ID")
    if user_id == 0:
        raise KeyError("Internal: user not in cache")
    if user_id == 999:
        raise ConnectionError("Internal: database timeout")
    return {"id": user_id, "name": "Alice"}

def get_user(user_id):
    """Public API - wraps internal errors."""
    try:
        return fetch_user_data(user_id)
    except ValueError as e:
        raise APIError("Invalid user ID", 400) from e
    except KeyError as e:
        raise APIError("User not found", 404) from e
    except ConnectionError as e:
        raise APIError("Service unavailable", 503) from e

test_ids = [-1, 0, 999, 42]
for uid in test_ids:
    try:
        user = get_user(uid)
        print(f"   User {uid}: {user}")
    except APIError as e:
        print(f"   User {uid}: [{e.status_code}] {e}")
        if e.__cause__:
            print(f"             (internal: {e.__cause__})")
print()

# 5. __context__ vs __cause__
print("5. __context__ vs __cause__:")
print("""
__context__ (implicit chaining):
  - Set automatically when exception raised during handling
  - Shows what was being handled when new error occurred

__cause__ (explicit chaining with 'from'):
  - Set explicitly with 'raise X from Y'
  - Clearly indicates Y caused X

from None:
  - Suppresses the chain in traceback
  - Use to hide implementation details
""")

# 6. Complete traceback example
print("6. How chaining appears in traceback:")
print("""
Without chaining:
  Traceback...
  ConfigError: Config file not found

With 'from e':
  Traceback...
  FileNotFoundError: [Errno 2] No such file

The above exception was the direct cause of:

Traceback...
  ConfigError: Config file not found

With implicit (during handling):
  Traceback...
  ValueError: conversion failed

During handling, another exception occurred:

Traceback...
  KeyError: 'missing'
""")

Output

Click Run to execute your code

Chaining Summary:
raise X from Y - Explicit: "Y caused X" (__cause__)
raise X (during handling) - Implicit: "X happened while handling Y" (__context__)
raise X from None - Suppress chain (hide internal errors)

Use explicit chaining when converting internal errors to public API errors.

Common Mistakes

1. Raising wrong exception type

# Wrong - RuntimeError for validation
def set_age(age):
    if age < 0:
        raise RuntimeError("Age cannot be negative")  # Wrong type

# Correct - ValueError for invalid values
def set_age(age):
    if age < 0:
        raise ValueError("Age cannot be negative")  # Right type

# Wrong - using Exception (too generic)
raise Exception("Something went wrong")

# Correct - specific exception
raise ConnectionError("Failed to connect to database")

2. Losing traceback when re-raising

# Wrong - creates new exception, loses traceback!
try:
    process_data()
except ValueError as e:
    log_error(e)
    raise ValueError(str(e))  # NEW exception, lost traceback!

# Correct - bare raise preserves traceback
try:
    process_data()
except ValueError:
    log_error("Processing failed")
    raise  # Same exception, same traceback

# Also correct - explicit chaining preserves cause
try:
    process_data()
except ValueError as e:
    raise ProcessingError("Failed to process") from e

3. Forgetting to chain exceptions

# Wrong - original error lost
def get_config():
    try:
        return json.load(open("config.json"))
    except (FileNotFoundError, json.JSONDecodeError):
        raise ConfigError("Bad config")  # What was the original error?

# Correct - chain with 'from'
def get_config():
    try:
        return json.load(open("config.json"))
    except (FileNotFoundError, json.JSONDecodeError) as e:
        raise ConfigError("Bad config") from e  # Original preserved!

4. Inheriting from BaseException

# Wrong - BaseException isn't caught by 'except Exception'
class MyError(BaseException):  # Wrong!
    pass

try:
    raise MyError("oops")
except Exception:
    print("Not caught!")  # MyError escapes!

# Correct - inherit from Exception
class MyError(Exception):  # Correct!
    pass

try:
    raise MyError("oops")
except Exception:
    print("Caught!")  # Works!

5. Not calling super().init in custom exception

# Wrong - forgets super().__init__
class APIError(Exception):
    def __init__(self, code, message):
        self.code = code
        self.message = message
        # Forgot super().__init__!

err = APIError(404, "Not found")
print(str(err))  # Empty string!

# Correct - call super().__init__
class APIError(Exception):
    def __init__(self, code, message):
        super().__init__(f"[{code}] {message}")
        self.code = code
        self.message = message

err = APIError(404, "Not found")
print(str(err))  # "[404] Not found"

Exercise: Validation Library

Task: Create a validation library with custom exceptions.

Requirements:

Create a base ValidationError exception
Create specific exceptions: RequiredFieldError, TypeValidationError, RangeError
Write a validate_user() function that validates user data
Chain exceptions properly to preserve context

# Exercise: Validation Library
# Task: Create a validation library with custom exceptions.

# Requirements:
# 1. Create a base ValidationError exception
# 2. Create specific exceptions: RequiredFieldError, TypeValidationError, RangeError
# 3. Write a validate_user() function that validates user data
# 4. Chain exceptions properly to preserve context

# 1. Define your custom exceptions here:
class ValidationError(Exception):
    """Base validation error."""
    pass

# Add more exception classes...

# 2. Write the validation function:
def validate_user(data):
    """
    Validate user data dictionary.
    Required fields: username (str), email (str), age (int)
    """
    # Your code here:
    pass

# Test your validation:
test_users = [
    {},
    {'username': 'ab', 'email': 'test@mail.com', 'age': 25},
    {'username': 'alice', 'email': 'noatsign', 'age': 25},
    {'username': 'charlie', 'email': 'charlie@mail.com', 'age': 30},
]

print("=== User Validation Tests ===\n")
for user in test_users:
    try:
        validate_user(user)
        print(f"Valid: {user}")
    except ValidationError as e:
        print(f"Invalid: {type(e).__name__}: {e}")

Output

Click Run to execute your code

Show Solution

# Custom exceptions
class ValidationError(Exception):
    """Base validation error."""
    pass

class RequiredFieldError(ValidationError):
    """Field is required but missing."""
    def __init__(self, field):
        super().__init__(f"Field '{field}' is required")
        self.field = field

class TypeValidationError(ValidationError):
    """Field has wrong type."""
    def __init__(self, field, expected, got):
        super().__init__(f"Field '{field}' expected {expected}, got {got}")
        self.field = field
        self.expected = expected
        self.got = got

class RangeError(ValidationError):
    """Value out of allowed range."""
    def __init__(self, field, value, min_val=None, max_val=None):
        if min_val is not None and max_val is not None:
            msg = f"Field '{field}' value {value} not in range [{min_val}, {max_val}]"
        elif min_val is not None:
            msg = f"Field '{field}' value {value} must be >= {min_val}"
        else:
            msg = f"Field '{field}' value {value} must be <= {max_val}"
        super().__init__(msg)
        self.field = field
        self.value = value


def validate_user(data):
    """Validate user data dictionary."""
    # Check required fields
    for field in ['username', 'email', 'age']:
        if field not in data or data[field] is None:
            raise RequiredFieldError(field)

    # Validate types
    if not isinstance(data['username'], str):
        raise TypeValidationError('username', 'str', type(data['username']).__name__)

    if not isinstance(data['email'], str):
        raise TypeValidationError('email', 'str', type(data['email']).__name__)

    if not isinstance(data['age'], int):
        raise TypeValidationError('age', 'int', type(data['age']).__name__)

    # Validate ranges
    if len(data['username']) < 3:
        raise RangeError('username length', len(data['username']), min_val=3)

    if data['age'] < 0 or data['age'] > 150:
        raise RangeError('age', data['age'], min_val=0, max_val=150)

    if '@' not in data['email']:
        raise ValidationError("Email must contain '@'")

    return True


# Test the validation
test_users = [
    {},
    {'username': 'ab', 'email': '[email protected]', 'age': 25},
    {'username': 'alice', 'email': 'noatsign', 'age': 25},
    {'username': 'bob', 'email': '[email protected]', 'age': -5},
    {'username': 'charlie', 'email': '[email protected]', 'age': 30},
]

print("=== User Validation Tests ===\n")
for user in test_users:
    try:
        validate_user(user)
        print(f"Valid: {user}")
    except ValidationError as e:
        print(f"Invalid: {type(e).__name__}: {e}")

Summary

raise: raise ValueError("message") throws an exception
Choose right type: ValueError for bad values, TypeError for wrong types
Bare raise: raise re-raises current exception with traceback
Custom exceptions: Inherit from Exception, call super().__init__()
Exception hierarchy: Create base exception, specific ones inherit from it
raise from: raise X from Y chains exceptions (Y caused X)
from None: raise X from None suppresses chain
Add attributes: Custom exceptions can have extra data (code, field, etc.)

What's Next?

Now you can both catch and raise exceptions. But sometimes you just want to check that something is true during development - not handle it as an error, but catch bugs early. Next, we'll learn about assert statements for debugging and development-time checks!

Previous Finally & Else

Next Assertions

Basic Raise Statement

Re-raising Exceptions

Custom Exception Classes

Exception Chaining

Common Mistakes

1. Raising wrong exception type

2. Losing traceback when re-raising

3. Forgetting to chain exceptions

4. Inheriting from BaseException

5. Not calling super().__init__ in custom exception

Exercise: Validation Library

Summary

What's Next?

Enjoying these tutorials?

5. Not calling super().init in custom exception