09. Low-level Design

• 1: pygame setup
• 2: Avoid magic literals
• 3: Single Responsibility Principle
• 4: DRY and the Rule of Three
• 5: Handle Errors at the Lowest Sensible Level
• 6: Raise Specific Errors and Define Your Own If Needed

1 - pygame setup

Example event-driven program using pygame

We’ll have some fun by creating a very simple game using the pygame library. Our example program comes from a very excellent YouTube tutorial called “The Ultimate introduction to Pygame” by Clear Code. I highly recommend his channel as his tutorials are clear and to the point.

We will implement the code as in his tutorial, but we will re-design the code by applying the rules above. His code works just fine, but our re-design will help improve the understandability, maintainability, efficiency, and robustness of the software.

Setup

1. Open a Terminal and use cd to get into your seng-201 directory.
2. Run the command git clone https://github.com/UNCW-SENG/pygame-design. This will create a subdirectory named pygame-design.
3. Open PyCharm. Go through the menus: File -> Open. Find and open the pygame-design/ folder, then hit the Open button. You should see the following structure:

   

   It is essential that the root folder is pygame-design/
4. Click in the bottom right of your PyCharm window where it either says Add interpreter... or Python 3.x (something).
5. Then select Add Interpreter -> Add Local Interpreter. You should see something similar to the following:

   

6. Make sure Generate New is selected. The pre-populated location should be fine. Then hit OK.
7. Open the Integrated Terminal in PyCharm. Type the command pip install pygame to download the pygame library.
8. Open runner.py and run it. A black screen should pop-up and you should see Hello from the pygame community in the integrated Terminal.

   

You should now be good to go.

Class recording

Code at the end

You must have cloned the project from the setup section. Here is the code at the end of class:

• runner.py

Next up

Up next is our first principle: avoid magic literals.

2 - Avoid magic literals

Class recording

What is a “magic literal”?

A magic literal is a raw value (number, string, None, etc.) that appears in code without a name explaining its meaning or origin. They harm readability, hide intent, and make changes risky—because the same value might be duplicated in many places.

Rule of thumb: If a value has domain meaning (tax rate, role name, error code, feature flag, file path, regex, etc.), name it once and reuse that name everywhere.

Benefits

• Clear intent (self-documenting)
• Single source of truth (change in one place)
• Fewer bugs during refactors
• Easier testing & configuration

Example 1 - numeric literal

Problematic code

def final_price(subtotal):
    # Why 0.085? City tax? Promo? Future me has no idea.
    return subtotal * (1 + 0.085)

Problem: Where does the value 0.085 come from? Why is it there? Not knowing this harms maintainability.

Fixed with a constant that conveys intent

Constants are variables that don’t vary. They are set once and not changed. In Python, the convention is to name Python constants as ALL_UPPERCASE_AND_UNDERSCORES.

CITY_SALES_TAX_RATE = 0.085  # 8.5% city sales tax

def final_price(subtotal: float) -> float:
    return subtotal * (1 + CITY_SALES_TAX_RATE)

Why this is better: The constant gives the number meaning, centralizes the value, and invites documentation and tests around that concept. Keep constants close to where they’re used (module-level), or in a dedicated constants.py if shared broadly.

Example 2 - String literals

Problematic code

def get_discount(category):
    if category == "student":
        return 0.10
    elif category == "veteran":
        return 0.15
    elif category == "employee":
        return 0.20
    else:
        return 0.0

Again, the meaning of each string is hidden. Typos (“vetran”) will silently break the logic. And, finally, if category labels change, you must update multiple places.

Fixed using named constants

CATEGORY_STUDENT = "student"
CATEGORY_VETERAN = "veteran"
CATEGORY_EMPLOYEE = "employee"

DISCOUNT_STUDENT = 0.10
DISCOUNT_VETERAN = 0.15
DISCOUNT_EMPLOYEE = 0.20
DISCOUNT_DEFAULT = 0.0

def get_discount(category):
    if category == CATEGORY_STUDENT:
        return DISCOUNT_STUDENT
    elif category == CATEGORY_VETERAN:
        return DISCOUNT_VETERAN
    elif category == CATEGORY_EMPLOYEE:
        return DISCOUNT_EMPLOYEE
    else:
        return DISCOUNT_DEFAULT

The constants clearly express intent and centralize both string values and their corresponding numeric meanings. If a new category or discount rate is added, it only needs to be defined once.

For larger systems, consider moving these constants to a separate constants.py module to avoid duplication across files.

When a literal is not magic

• Sentinel/obvious values: 0, 1, -1, True, False, "" used in generic math or indexing (e.g., arr[-1]) are usually fine.
• Short-lived throwaway code/tests: Inline values in extremely small, clear scopes can be acceptable.
• Data structure examples: Literals inside illustrative examples or test fixtures are usually okay unless they are likely to change.

Knowledge Check

• Question: Why are magic literals risky in larger code bases?
  Answer

  Because you need to update the literal values everywhere they appear in code if the value needs to change.
• Question: Which of the following is least likely to be a magic literal?
  1. "admin"
  2. 0.075
  3. arr[-1]
  4. "https://api.example.com/v1"
  Answer

  3 — Sentinel and language-specific values like 0, 1, True, False, and -1 are not considered magic literals. In Python, arr[-1] is a shortcut to get the last element of a list.
• Question: Spot and fix the magic literal(s):

  def greet_user(role):
      if role == "admin":
          print("Welcome back, administrator!")
      elif role == "guest":
          print("Hello, guest user.")
      else:
          print("Access restricted.")
  

  Answer

  The "admin" and "guest" strings are magic literals. The messages themselves are probably not magic literals since they are likely used only once. However, if your app had internationalization where it supports multiple languages, you would replace those messages with variables.
• Question: True or False: It’s acceptable to use a literal directly in code when its meaning is obvious and universally understood, such as 0 in range(0, 10) or True in a simple condition.
  Answer

  This is True, similar to the answer of Question 2.

Next up

Up next is the SRP principle.

3 - Single Responsibility Principle

Class recording

The Single Responsibility Principle

The Single Responsibility Principle is that functions should have a single responsibility—i.e., they should be cohesive. Group together into a function statements and logic that have a single, simple goal.

The Single Responsibility Principle is often stated as “each function has one clear reason to change.”

Benefits

• Each function has a clear purpose and answers one “what does this do?” question.
• Narrow behaviors are easier to unit test.
• A change to that single purpose only affects one function rather than requiring changes across unrelated code.
• Small, focused functions are easier to compose to solve bigger problems.

Red flags (violations):

• The function name needs “and” to describe it.
• It touches multiple domains (I/O, parsing, business rules, UI) at once.
• It has many parameters or returns mixed/compound results that signal different concerns.
• It has multiple try/except blocks for different activities.
• It both decides and acts (e.g., computes a result and prints/saves/sends it).

Example 1 - Decision logic mixed with formatting

Problematic code

def describe_temperature(celsius: float) -> str:
    if celsius < 0:
        color = "blue"
        label = "Freezing"
    elif celsius < 20:
        color = "green"
        label = "Cool"
    else:
        color = "red"
        label = "Hot"

    # Mixing presentation logic here
    return f"{label} ({celsius}°C) shown in {color.upper()}"

Problem: This function both categorizes a temperature and formats a human-readable message. If we change color conventions or output format, unrelated logic breaks.

Fixed to separate out unrelated purposes

def classify_temperature(celsius: float) -> str:
    if celsius < 0:
        return "Freezing"
    elif celsius < 20:
        return "Cool"
    return "Hot"

def color_for_temperature(label: str) -> str:
    return {"Freezing": "blue", "Cool": "green", "Hot": "red"}[label]

def format_temperature_message(label: str, celsius: float, color: str) -> str:
    return f"{label} ({celsius}°C) shown in {color.upper()}"

def describe_temperature(celsius: float) -> str:
    label = classify_temperature(celsius)
    color = color_for_temperature(label)
    return format_temperature_message(label, celsius, color)

Why this is better: Each helper has a single reason to change — classification rules, color mapping, or formatting.

Example 2 - Data validation mixed with transformation

Problematic code

def normalize_user_input(data: dict) -> dict:
    if "name" not in data or "email" not in data:
        raise ValueError("Missing fields")

    data["name"] = data["name"].strip().title()
    data["email"] = data["email"].lower()

    return data

Validation and transformation responsibilities are blended. Changing validation rules would risk altering transformation behavior.

Fixed by splitting the function

def validate_user_input(data: dict) -> None:
    if "name" not in data or "email" not in data:
        raise ValueError("Missing fields")

def normalize_user_fields(data: dict) -> dict:
    return {
        "name": data["name"].strip().title(),
        "email": data["email"].lower(),
    }

def process_user_input(data: dict) -> dict:
    validate_user_input(data)
    return normalize_user_fields(data)

Each function has one clear reason to change — validation rules vs. formatting rules.

How to refactor toward SRP

1. Name first. Write a function name that states a single outcome; split if you need “and.”
2. Separate concerns. Isolate I/O, parsing, validation, business rules, formatting, and presentation.
3. Extract functions. Pull distinct blocks into helpers with clear inputs/outputs.
4. Push side effects outward. Keep core logic pure; print/save at the edges.

Knowledge Check

• Which function best follows SRP?
  1. process_and_save_and_print_order()
  2. compute_total(items, tax_rate)
  3. read_validate_compute()
  4. do_everything()
  Answer

  2 — the names of the others all imply that they have multiple responsibilities.
• A common SRP smell is:
  1. One return statement
  2. Short parameter list
  3. A function that both validates input and writes files
  4. A pure function with docstring
  Answer

  3 — Validating input (from a user, from a file) and writing data to a file are distinct responsibilities within a program.
• A good SRP-based refactor typically involves:
  1. Extracting cohesive operations into new functions.
  2. Reducing the number of function calls.
  3. Merging similar code into a single larger function.
  4. Avoiding helper functions.
  Answer

  1 — refactoring an SRP problem almost always will result in more functions in the program.
• The SRP is violated when a function changes for more than one reason. “Reason” here refers to:
  1. Multiple developers editing the same code.
  2. Multiple sources of change tied to distinct responsibilities.
  3. The number of commits per week.
  4. The number of test cases.
  Answer

  2 — thinking of "responsibility" as "one task the program performs", if something about that task changes (e.g., getting input, validating input is correct, writing output) it should ideally only affect one function in the code that is separate from the other tasks.

Next up

Up next is the DRY principle and the Rule of Three.

4 - DRY and the Rule of Three

Class recording

Rule #3: DRY — Don’t Repeat Yourself (and the Rule of Three)

Don’t Repeat Yourself! Commonly called the DRY rule, it simply means don’t write the same code in multiple places.

Why not? Because when you must fix or update the logic, you have to do it everywhere it’s copied—this multiplies effort and risk of bugs.

The Rule of Three is helpful to identify when DRY is being violated. If the same (or nearly the same) code shows up in three or more places, extract it into a function (or module). Two copies feels suspicious, but three is definitely an indicator to refactor.

If the copies differ slightly, find the part that varies and control that via a parameter.

Benefits

• One place to fix or improve.
• Fewer missed patches and inconsistent behaviors.
• Less surface area to understand/review.
• Better-named functions document intent.

Example 1 — Obvious repetition → function

Problematic code

# apply discounts in three places
total_a = subtotal_a - (subtotal_a * 0.10)  # 10% off
taxed_a = total_a * 1.07

total_b = subtotal_b - (subtotal_b * 0.10)  # 10% off
taxed_b = total_b * 1.07

total_c = subtotal_c - (subtotal_c * 0.10)  # 10% off
taxed_c = total_c * 1.07

The only thing that changes here is the variable acted upon. This is a clear call for a function. There are also magic literals here.

Better code (extract once)

# Note the use of default parameters below. These should 
DEFAULT_DISCOUNT = 0.10
DEFAULT_TAX_RATE = 0.07

def apply_discount_and_tax(subtotal, discount=DEFAULT_DISCOUNT, tax_rate=DEFAULT_TAX_RATE):
    discounted = subtotal * (1 - discount)
    return discounted * (1 + tax_rate)

taxed_a = apply_discount_and_tax(subtotal_a)
taxed_b = apply_discount_and_tax(subtotal_b)
taxed_c = apply_discount_and_tax(subtotal_c)

Now we have one function and the repeated code is gone. Even better, that function is now flexible by taking the discount amount and tax rate as parameters. We also cleaned up magic literals!

Example 2 - Hidden duplication (structure, not lines)

Problematic code

def send_welcome_email(user):
    msg = f"Welcome {user.name}!"
    smtp = SMTP("smtp.example.com")
    smtp.send(user.email, msg)
    smtp.close()

def send_password_reset_email(user, token):
    msg = f"Reset link: https://x/reset/{token}"
    smtp = SMTP("smtp.example.com")
    smtp.send(user.email, msg)
    smtp.close()

Duplication isn’t always copy-paste; sometimes two blocks share a shape. Do you see the similarities and differences? We should refactor the common elements into a reusable helper function, and then create additional functions to provide the specifics to that helper (this will help with SRP too)!

Better code (extract shared steps)

SMTP_SERVER = "smtp.example.com"

def send_email(user, msg):
    smtp = SMTP(SMTP_SERVER)
    try:
        smtp.send(user.email, msg)
    finally:
        smtp.close()

def send_welcome_email(user):
    send_email(user, f"Welcome {user.name}!")

def send_password_reset_email(user, token):
    send_email(user, f"Reset link: https://x/reset/{token}")

We extracted the common logic of sending the SMTP mail but parameterized the message. Now the send_welcome_email and send_password_reset_email use the helper.

Common Pitfalls

• Parameter bloat. Too many knobs can make the function unclear. If it grows unwieldy, split into cohesive variants or use a small strategy object.
• Premature abstraction. Don’t over-abstract on the first duplication. Two copies are a smell, the third justifies the refactor.
• Duplicating data transformations. Push conversions (e.g., parsing, formatting) to the boundaries. Write functions that work with one canonical representation internally, and make other functions for dealing with particular formats (like in Example 2).

Knowledge Check

• What’s the best trigger to refactor for DRY?
  1. The very first time code is written.
  2. When you see two copies anywhere.
  3. When substantially the same code appears three or more times.
  4. Only when performance suffers.
     Answer

     C — Use the **Rule of Three** as a practical trigger (two is a smell, three is a must).
• You find three similar blocks differing only in a constant (e.g., a rate). What’s the cleanest DRY fix?
  1. Copy the block and change the constant.
  2. Extract a function and make the constant a parameter.
  3. Add three separate functions.
  4. Inline everything into one giant function.
     Answer

     B — Extract and parameterize the variation.
• Two blocks share setup/teardown but build different messages. Best approach?
  1. Leave as is; they’re “not identical.”
  2. Extract just the setup/teardown into a helper and pass the message (or a small builder) as the parameter.
  3. Merge both into one if/else ladder in-place.
  4. Use copy-paste with a TODO.
     Answer

     B — Extract the shared structure; parameterize the varying message.
• Your new helper now takes 7 parameters and is hard to read. What next?
  1. Add more parameters.
  2. Revert to duplication.
  3. Split the helper along cohesive responsibilities.
  4. Ignore it.
     Answer

     C — Avoid parameter bloat by grouping or splitting to maintain cohesion.

Next up

Up next is handling exceptions at the lowest sensible level.

5 - Handle Errors at the Lowest Sensible Level

Example and class note

The class recording below uses the project bank-accounts.zip for an example. The beginning of the recording applies Design Rules 1-3 to the project, including multiple code updates. The discussion of design rules 4-5 begins around 45:30.

Handle Errors at the Lowest Sensible Level

The rule Handle errors at the lowest sensible level, and re-raise/re-throw them otherwise means that you should catch and handle exceptions where you can meaningfully address them, and let them propagate upward when you cannot.

What is sensible? Do not gobble up errors just to hide problems. Catch and fix them if you can, otherwise, raise the error and let the calling function deal with it.

What does it mean to meaningfully address or fix an error? A function can meaningfully address an error when it has the context and capability to either resolve the issue or convert it into a recoverable state. For example, a function that reads user input can handle a ValueError by prompting for valid input again, or a network function can retry a failed connection. However, if a function encounters an error it cannot resolve (like a missing configuration file that the function doesn’t have permission to create, or a badly-formatted input file in a function that only processes data), it should re-raise the exception so a higher-level function with more context can handle it appropriately. The key is: if you can fix it or work around it meaningfully at your level, do so; otherwise, let it propagate.

Benefits

• Functions become more robust and clearly defined: “I handle these situations, but not these.”
• Error-handling logic is simplified because you only handle what you can fix.
• Errors are not hidden; they propagate to where they can be properly addressed.
• The user interface layer is responsible for displaying error messages, keeping business logic separate from presentation.

Red flags (violations):

• Functions that catch all exceptions and silently return None or default values, hiding real problems.
• Catching exceptions at too high a level when they could be handled more specifically at a lower level.
• Swallowing exceptions with empty except: blocks or except: pass.
• Functions that catch exceptions only to re-raise them without adding context or handling.
• Mixing error handling with business logic instead of handling errors where they occur.
• Displaying error messages or logging from deep within business logic functions.

Example 1 - Swallowing errors to hide problems

Problematic code

def read_config_file(filename: str) -> dict:
    try:
        config = {}
        with open(filename, 'r') as f:
            for line in f:
                if '=' in line:
                    key, value = line.strip().split('=', 1)
                    config[key] = value
        return config
    except:
        return {}  # Silently fails, caller doesn't know what went wrong

def process_user_data(config: dict) -> list:
    users = []
    for user_id in config.get("user_ids", []):
        try:
            user = fetch_user_from_database(user_id)
            users.append(user)
        except:
            pass  # Silently skips users, no indication of failure
    return users

Problem: These functions swallow errors, hiding real problems. The caller has no way to know if the config file was missing, corrupted, or if the database call failed. Errors are hidden rather than being handled or propagated.

Fixed to handle or re-raise appropriately

def read_config_file(filename: str) -> dict:
    try:
        config = {}
        with open(filename, 'r') as f:
            for line_num, line in enumerate(f, 1):
                line = line.strip()
                if not line or line.startswith('#'):
                    continue
                if '=' not in line:
                    raise ValueError(f"Invalid format in {filename} at line {line_num}: missing '='")
                key, value = line.split('=', 1)
                config[key.strip()] = value.strip()
        return config
    except FileNotFoundError:
        # Can't handle this at this level - file missing is a real problem
        raise
    except ValueError as e:
        # Could provide more context, but still re-raise
        raise ValueError(f"Invalid config format in {filename}: {e}") from e

def process_user_data(config: dict) -> list:
    users = []
    failed_ids = []
    for user_id in config.get("user_ids", []):
        try:
            user = fetch_user_from_database(user_id)
            users.append(user)
        except ConnectionError:
            # Network error - can't fix here, but we can track it
            failed_ids.append(user_id)
        except ValueError as e:
            # Invalid user ID format - can't fix here
            raise ValueError(f"Invalid user_id {user_id}: {e}") from e
    
    if failed_ids:
        # Re-raise with context about what failed
        raise ConnectionError(f"Failed to fetch users: {failed_ids}")
    return users

Why this is better: Errors are either handled meaningfully (with context added) or re-raised so callers can decide how to respond. No errors are silently swallowed.

Example 2 - Handling errors at too high a level

Problematic code

def process_order(order_data: dict) -> bool:
    try:
        # All errors handled at top level
        validate_order(order_data)
        calculate_total(order_data)
        charge_card(order_data)
        send_confirmation(order_data)
        return True
    except Exception as e:
        print(f"Error: {e}")  # UI concern in business logic!
        return False

Problem: All errors are caught at the top level, mixing UI concerns (printing) with business logic. The function can’t distinguish between different types of errors, and the caller gets no information about what went wrong. Different errors might need different handling.

Fixed by handling at appropriate levels

def validate_order(order_data: dict) -> None:
    if "items" not in order_data or len(order_data["items"]) == 0:
        raise ValueError("Order must contain at least one item")
    if "card_number" not in order_data:
        raise ValueError("Card number is required")
    # Validation errors are handled here, but they're fixable at input level

def calculate_total(order_data: dict) -> float:
    total = 0.0
    for item in order_data["items"]:
        if "price" not in item or "quantity" not in item:
            raise ValueError(f"Invalid item data: {item}")
        total += item["price"] * item["quantity"]
    return total
    # Calculation errors handled here - data problems are fixable

def charge_card(order_data: dict, amount: float) -> None:
    try:
        # Payment gateway call
        payment_api.charge(order_data["card_number"], amount)
    except payment_api.InsufficientFundsError as e:
        # Can't fix this here, but we communicate what happened
        raise ValueError("Insufficient funds to complete the transaction") from e
    except payment_api.InvalidCardError as e:
        # Can't fix this here either
        raise ValueError(f"Payment failed: {e}") from e
    # Network errors, etc. - let them propagate

def process_order(order_data: dict) -> None:
    # There are no try-except blocks in this function, so it re-raises errors by default. Let the caller handle them. 
    validate_order(order_data)
    total = calculate_total(order_data)
    charge_card(order_data, total)
    # Only send confirmation if everything succeeded
    send_confirmation(order_data)

Why this is better: Each function handles errors it can meaningfully address (validation, calculation) and re-raises errors it cannot fix (payment failures, network issues). The UI layer can then catch these and display appropriate messages to the user.

How to apply this rule

1. Handle what you can fix. If you can meaningfully recover from an error at a specific level, handle it there.
2. Re-raise what you can’t. If you can’t fix the problem, re-raise the exception (possibly with added context) so a caller can handle it.
3. Don’t swallow errors. Never use bare except: or except: pass unless you’re at the absolute top level (like a main event loop).
4. Add context when re-raising. Use exception chaining (raise ... from e) to preserve the original error while adding useful context.
5. Keep UI concerns separate. Displaying error messages or re-prompting the user to enter “good” input are the UI layer’s responsibilities, not the business logic layer’s.
6. Handle at the lowest level. If a low-level function can fix a specific error (e.g., retry a network call), handle it there rather than letting it bubble up unnecessarily.

Knowledge Check

• A function that reads user input encounters a ValueError when parsing a number. The function can prompt the user to re-enter valid input. What should this function do?
  1. Catch the exception and return None to indicate failure
  2. Catch the exception, prompt the user for valid input, and retry the operation
  3. Let the exception propagate to the caller without handling it
  4. Catch the exception and print an error message to the console
  Answer

  2 — since the function can meaningfully address the error by prompting for valid input, it should handle it at this level rather than propagating it upward.
• You’re writing a function that processes data from a configuration file. The function encounters a FileNotFoundError but doesn’t have permission to create files. What should it do?
  1. Catch the exception and return an empty dictionary as a default
  2. Catch the exception and print “File not found” to the console
  3. Re-raise the exception (possibly with added context) so a higher-level function can handle it
  4. Use except: pass to silently ignore the error
  Answer

  3 — since the function cannot meaningfully fix this error (it can't create the missing file), it should re-raise the exception so a caller with more context (like the UI layer) can handle it appropriately.
• When re-raising an exception with added context, what is the best practice?
  1. Use raise ValueError("New message") to replace the original exception completely
  2. Use raise ValueError("New message") from e to preserve the original exception chain
  3. Only re-raise the original exception without any modifications
  4. Catch and log the exception, then return None
  Answer

  2 — using `raise ... from e` preserves the original exception chain, which helps with debugging by showing both the original error and the added context.
• Which of the following is a red flag that violates the “lowest sensible level” principle?
  1. A validation function that raises ValueError when input is invalid
  2. A payment processing function that catches InsufficientFundsError and re-raises it as ValueError with a user-friendly message
  3. A data processing function that catches all exceptions and returns an empty list
  4. A function that lets network exceptions propagate to the caller when it can’t retry the connection
  Answer

  3 — catching all exceptions and returning a default value (like an empty list) hides errors and prevents callers from knowing what went wrong. This violates the principle by swallowing errors that should be handled or propagated.

Next up

Up next is our final rule: raise specific errors and define your own if needed.

6 - Raise Specific Errors and Define Your Own If Needed

Example and class note

The class recording below uses the project bank-accounts.zip for an example. The beginning of the recording applies Design Rules 1-3 to the project, including multiple code updates. The discussion of design rules 4-5 begins around 45:30.

Raise Specific Errors and Define Your Own If Needed

The rule Raise specific errors and define your own if needed means that you should use the most appropriate exception type for each error situation, choosing from built-in exceptions when they fit, and creating custom exception classes when they don’t.

Why specific errors? Specific exceptions precisely indicate what went wrong, making code more maintainable. When you catch a ValueError, you know the problem is with the value of the data. When you catch a FileNotFoundError, you know a file is missing. Generic exceptions like Exception or bare except: clauses hide the actual problem, making debugging and error handling much more difficult.

Built-in exceptions to use: Python provides many specific exception types. Choose the most appropriate one:

• ValueError - often the most appropriate when called with “bad” data (wrong value, invalid format)
• TypeError - for unsupported types of data (wrong type passed to function)
• FileNotFoundError - when a file or directory cannot be found
• PermissionError - when an operation is not permitted due to insufficient permissions
• KeyError - when a dictionary key is missing
• IndexError - when a sequence index is out of range
• AttributeError - when an attribute (variable or function) doesn’t exist on the object, e.g., calling x.append('Bob') but x is a dictionary. Dictionaries don’t understand how to append() in Python.
• And many more specific exceptions for different scenarios

When to create custom exceptions: When built-in exceptions don’t accurately represent your domain-specific errors, create your own exception classes. Custom exceptions make it clear that an error is specific to your application’s domain, not a general programming error. For example, if you’re building a payment system, a PaymentProcessingError or InsufficientFundsError is more meaningful than a generic ValueError.

Benefits

• Precise error identification: callers can catch specific exceptions and handle them appropriately
• Better maintainability: developers can quickly understand what went wrong
• Improved debugging: specific error types make it easier to locate and fix issues
• Clearer code intent: the exception type itself documents what can go wrong
• Enables selective error handling: callers can catch only the exceptions they know how to handle

Red flags (violations):

• Raising generic Exception instead of specific exception types
• Using ValueError for everything, even when TypeError or other exceptions are more appropriate
• Catching all exceptions with bare except: or except Exception: without distinguishing types

• Using string error messages instead of exceptions when an exception is more appropriate
• Creating custom exceptions that don’t add meaningful information beyond built-in exceptions

Example 1 - Using generic Exception instead of specific exceptions

Problematic code

def validate_age(age):
    if age < 0:
        raise Exception("Age cannot be negative")
    if not isinstance(age, int):
        raise Exception("Age must be an integer")
    return age

def process_user_data(user_id):
    try:
        user = fetch_user_from_database(user_id)
        return user
    except Exception:
        return None  # Caller doesn't know what went wrong

Problem: These functions use generic Exception instead of specific exceptions. Callers can’t distinguish between different error types, making it impossible to handle specific errors appropriately. For example, a caller can’t tell if read_config_file failed because the file was missing (FileNotFoundError) or because of a permission issue (PermissionError), so they can’t respond appropriately.

Fixed using specific exceptions

def validate_age(age):
    if not isinstance(age, int):
        raise TypeError(f"Age must be an integer, got {type(age).__name__}")
    if age < 0:
        raise ValueError(f"Age cannot be negative, got {age}")
    return age

def process_user_data(user_id):
    try:
        user = fetch_user_from_database(user_id)
        return user
    except ConnectionError as e:
        # Network issue - caller might want to retry
        raise ConnectionError("Could not connect to database.") from e
    except ValueError as e:
        # Invalid user ID format - different from network error
        raise ValueError(f"Invalid user_id format: {user_id}") from e

Why this is better: Specific exceptions allow callers to handle different error types appropriately. For example, a caller can catch FileNotFoundError to prompt for a different file, or catch PermissionError to display a permission-related message. The exception type itself communicates what went wrong.

Example 2 - Creating custom exceptions for domain-specific errors

Problematic code

def process_payment(card_number: str, amount: float) -> bool:
    if not card_number or len(card_number) < 13:
        raise ValueError("Invalid card number")
    
    if amount <= 0:
        raise ValueError("Amount must be positive")
    
    if amount > 10000:
        raise ValueError("Amount exceeds daily limit")
    
    # Check if card is expired
    if is_card_expired(card_number):
        raise ValueError("Card is expired")
    
    # Check if insufficient funds
    balance = get_account_balance(card_number)
    if balance < amount:
        raise ValueError("Insufficient funds")
    
    # Process payment
    return True

Problem: All errors raise ValueError, even though they represent fundamentally different problems. A caller can’t distinguish between “invalid card format”, “card expired”, “insufficient funds”, and “amount exceeds limit” - all are treated as generic value errors. This makes it difficult to handle different payment errors appropriately (e.g., retry for insufficient funds vs. reject for expired card). You could inspect the error message, but that would be using a magic literal.

Fixed by creating custom exceptions

# Define custom exceptions for payment domain
class PaymentError(Exception):
    """Base exception for payment-related errors"""
    pass

class InvalidCardError(PaymentError):
    """Raised when card number format is invalid"""
    pass

class CardExpiredError(PaymentError):
    """Raised when card has expired"""
    pass

class InsufficientFundsError(PaymentError):
    """Raised when account has insufficient funds"""
    pass

class AmountExceedsLimitError(PaymentError):
    """Raised when payment amount exceeds allowed limit"""
    pass

def process_payment(card_number: str, amount: float) -> bool:
    if not card_number or len(card_number) < 13:
        raise InvalidCardError(f"Invalid card number format: {card_number}")
    
    if amount <= 0:
        raise ValueError("Amount must be positive")  # Still ValueError - general validation
    
    if amount > 10000:
        raise AmountExceedsLimitError(f"Amount {amount} exceeds daily limit of 10000")
    
    # Check if card is expired
    if is_card_expired(card_number):
        raise CardExpiredError("Card has expired")
    
    # Check if insufficient funds
    balance = get_account_balance(card_number)
    if balance < amount:
        raise InsufficientFundsError(f"Insufficient funds: balance {balance}, required {amount}")
    
    # Process payment
    return True

# Caller can now handle specific errors appropriately
def handle_payment_request(card_number: str, amount: float):
    try:
        process_payment(card_number, amount)
        print("Payment successful!")
    except CardExpiredError:
        print("Your card has expired. Please use a different card.")
    except InsufficientFundsError:
        print("Insufficient funds. Please try a smaller amount.")
    except AmountExceedsLimitError:
        print("Payment amount exceeds daily limit. Please contact support.")
    except InvalidCardError:
        print("Invalid card number. Please check and try again.")
    except PaymentError:
        # Catch any other payment-related errors
        print("Payment processing failed. Please try again later.")

Why this is better: Custom exceptions clearly communicate domain-specific errors. Callers can catch specific exceptions (InsufficientFundsError, CardExpiredError) and handle them appropriately, or catch the base PaymentError to handle any payment-related error. The exception hierarchy also allows for selective handling: catch PaymentError for all payment issues, or catch specific subclasses for granular control.

How to apply this rule

1. Choose the most appropriate built-in exception. When raising an error, use the most specific built-in exception that accurately describes the problem:

   • Use ValueError for invalid values or data formats
   • Use TypeError for wrong types
   • Use FileNotFoundError for missing files
   • Use PermissionError for permission issues
   • Use KeyError for missing dictionary keys
   • Use IndexError for out-of-range indices
   • And so on…

2. Create custom exceptions when built-in ones don’t fit. When your error is domain-specific and doesn’t match any built-in exception, create your own:

   class DataProcessError(Exception):
       pass
   

   Create a hierarchy if needed:

   class PaymentError(Exception):
       pass
   class InsufficientFundsError(PaymentError):
       pass
   

3. Don’t use generic Exception. Avoid raising Exception directly - it’s too generic and doesn’t help callers handle errors appropriately.

4. Don’t misuse ValueError for everything. While ValueError is common, don’t use it when TypeError, FileNotFoundError, or other exceptions are more appropriate.

5. Catch specific exceptions when possible. When catching exceptions, catch specific types rather than generic Exception:

   try:
       process_data()
   except FileNotFoundError:
       # Handle missing file
   except ValueError:
       # Handle invalid data
   

6. Use exception hierarchies for domain errors. Create a base exception class for your domain, then subclass it for specific cases. This allows callers to catch either specific errors or all domain errors:

   try:
       process_payment()
   except InsufficientFundsError:
       # Handle specific case
   except PaymentError:
       # Handle any payment error
   

Knowledge Check

• You’re writing a function that validates user input. The function receives a string when it expects an integer. What exception should you raise?
  1. Exception("Expected integer")
  2. ValueError("Expected integer")
  3. TypeError("Expected integer")
  4. AttributeError("Expected integer")
  Answer

  3 — TypeError` is the most appropriate exception for when the wrong type is passed to a function. ValueError would be for an integer with an invalid value (like a negative age), not for the wrong type entirely.
• Your function reads a configuration file, but the file doesn’t exist. What exception should you raise?
  1. ValueError("File not found")
  2. FileNotFoundError("config.txt")
  3. Exception("File missing")
  4. KeyError("config.txt")
  Answer

  2 — FileNotFoundError is the specific built-in exception for missing files. It's more precise than `ValueError` or generic `Exception`, and allows callers to handle file-not-found errors specifically.
• You’re building a payment processing system and need to indicate when a payment fails due to insufficient funds. The built-in exceptions don’t accurately represent this domain-specific error. What should you do?
  1. Raise ValueError("Insufficient funds") since it’s a value problem
  2. Create a custom exception class like class InsufficientFundsError(Exception)
  3. Raise Exception("Payment failed") to be generic
  4. Return False instead of raising an exception
  Answer

  2 — when built-in exceptions don't accurately represent your domain-specific errors, create custom exception classes. This makes the error type clear and allows callers to catch and handle InsufficientFundsError specifically, which is more meaningful than a generic ValueError.
• Which of the following is a red flag that violates the “raise specific errors” principle?
  1. Using TypeError when a function receives the wrong type
  2. Creating a custom DataProcessError exception for data processing failures
  3. Raising Exception for all errors instead of specific exception types
  4. Using FileNotFoundError when a file is missing
  Answer

  3 — raising generic Exception for all errors violates the principle because it doesn't help callers distinguish between different error types. Specific exceptions like ValueError, TypeError, FileNotFoundError, or custom exceptions allow for precise error handling.