I've seen this a lot in legacy codebases: a developer realizes a specific function is outdated or dangerous, but they aren't ready to delete it because it would break a hundred other things. Their first instinct is usually to just drop a print() statement at the top of the function to tell whoever is using it to stop. It seems harmless, right? But in a professional production environment, print() is practically invisible or, worse, it pollutes the standard output of a tool that might be piping data to another process.

The noise of print and the violence of exceptions

def get_user_data(user_id):
    print(f"WARNING: get_user_data is deprecated. Use fetch_user_profile instead!")
    # ... existing logic ...
    return {"id": user_id, "name": "John Doe"}

The problem here is that print() has no semantic meaning. To the Python interpreter, you're just outputting text. The person calling your library has no way to programmatically silence that warning, nor can they redirect it to a dedicated logging system without capturing all other stdout. Now, some people swing too far in the opposite direction and raise an exception. They'll throw a DeprecationError or a custom OldApiError. I call this the "nuclear option." If you raise an exception, you've just crashed your user's application because you wanted to tell them to update their code. That's a great way to get a very angry email from a project manager.

Using warnings for a middle ground

This is where the warnings module comes in. It gives you a way to signal that something is wrong—or will be wrong soon—without halting execution. It’s a non-fatal alert that follows a standardized protocol. Instead of print(), we use warnings.warn().

import warnings

def get_user_data(user_id):
    warnings.warn(
        "get_user_data is deprecated and will be removed in v2.0; use fetch_user_profile instead",
        DeprecationWarning,
        stacklevel=2
    )
    # ... existing logic ...
    return {"id": user_id, "name": "John Doe"}

Notice that stacklevel=2 argument. I can't stress this enough: use it. By default, the warning will point to the line where warnings.warn() is called (inside your function). But the developer doesn't care that your function is warning them; they care about where in their own code they called the deprecated function. Setting the stacklevel to 2 pushes the warning report back one level in the call stack, pointing directly to the culprit's line of code.

Filtering the signal from the noise

The real power of the warnings module isn't how you send the warning, but how the consumer handles it. Because these warnings are categorized (like DeprecationWarning, UserWarning, or RuntimeWarning), the user can decide how to react to them globally. For instance, during a local development phase, a dev might want to see everything. But in a CI/CD pipeline, they might want to treat all deprecation warnings as actual errors to ensure no old code slips into production.

You can control this behavior using warnings.simplefilter(). If you're tired of seeing a specific warning, you can set it to "ignore". If you're hunting down every single instance of a deprecated call, you can set it to "error", which effectively turns that warn() call into a raised exception. This flexibility is why I always insist on this module over print(); it hands the control over to the person who is actually running the code, rather than forcing the library author's preferences on them.

📋 Practical Task

Refactoring the Legacy Calculation Engine

You have been handed a module that performs financial calculations. One of the functions, calculate_tax_legacy(), is outdated and uses an incorrect formula for the current fiscal year. You are tasked with implementing a warning system so that other developers know to switch to calculate_tax_2024(), but you cannot break the existing application.

Requirements:

• Import the warnings module.
• Modify the calculate_tax_legacy() function to issue a DeprecationWarning.
• Ensure the warning message explicitly mentions that calculate_tax_2024() should be used instead.
• Use the correct stacklevel so the warning points to the code that called the function, not the inside of the function itself.
• Write a small test script that calls calculate_tax_legacy() and then use warnings.simplefilter('error', DeprecationWarning) to prove that the warning can be escalated to an exception.

# Starter Code
def calculate_tax_legacy(amount):
    # TODO: Add warning here
    return amount * 0.15

def calculate_tax_2024(amount):
    return amount * 0.22

# Test your implementation below:
calculate_tax_legacy(100)