Python’s classmethod and staticmethod decorators can behave unexpectedly when stacked. This guide explains why the order matters and provides practical, real-world solutions to fix decorator conflicts for good.

When Python Decorators Lie: A Senior Engineer’s Guide to `classmethod` Hell

I still remember the pager going off at 3:17 AM. A full-stack trace, originating from our core authentication service running on auth-worker-prod-07. A junior engineer had pushed what looked like a perfectly reasonable change: adding our standard @log_execution_time decorator to a classmethod that syncs user permissions. The code passed linting, it passed unit tests, but in production, under load, it was throwing a cryptic TypeError. The problem wasn’t his logic; it was the subtle, infuriating “gotcha” of decorator stacking order. We’ve all been there, staring at code that should work but doesn’t, and it’s almost always because of a detail the docs don’t scream from the rooftops. Let’s fix this so your pager stays quiet.

The “Why”: Decorators are Just Functions Wrapping Functions

The first thing to burn into your memory is that decorators are applied from the bottom up (or inside out). When you see this:

@decorator_A
@decorator_B
def my_function():
    pass

What the Python interpreter actually does is this: my_function = decorator_A(decorator_B(my_function)). The function closest to the def statement runs first.

The conflict you’re seeing happens when you mix a standard decorator with built-ins like @classmethod or @staticmethod. These built-ins don’t return a simple function; they return a special descriptor object. If your custom decorator runs first, it receives the function and returns a new function. Then, @classmethod receives that new function and correctly turns it into a class method descriptor. Everything works.

But if you swap them, @classmethod runs first. It takes your method and returns a classmethod descriptor object. Your custom decorator then receives this object, not a function. Most simple decorators aren’t built to handle that, and they crash and burn, usually with a TypeError because they expected a callable function they could execute.

Here’s the broken code that probably brought you here:

# Our simple logging decorator
def log_call(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

class DatabaseConnector:
    # THIS IS THE WRONG ORDER!
    @log_call
    @classmethod
    def connect(cls, db_name):
        print(f"Connecting to {db_name} as {cls.__name__}")

# This will raise a TypeError
# DatabaseConnector.connect("prod-db-01")
# TypeError: 'classmethod' object is not callable

The Fixes: From Quick & Dirty to Architecturally Sound

Depending on your situation, you have a few ways to tackle this. Here they are, from the immediate hotfix to the robust, long-term solution.

Solution 1: The Quick Fix (Just Swap Them)

This is the 2 AM hotfix. The fastest way to get your service back online is to simply re-order the decorators. Put the built-in decorator (@classmethod or @staticmethod) on top, so it gets applied last.

class DatabaseConnector:
    # THIS IS THE CORRECT ORDER
    @classmethod
    @log_call
    def connect(cls, db_name):
        # The 'log_call' decorator runs first, wrapping the raw function.
        # Then, 'classmethod' runs second, turning the *wrapped function*
        # into a proper class method.
        print(f"Connecting to {db_name} as {cls.__name__}")

# This now works perfectly
DatabaseConnector.connect("prod-db-01")

This works, it’s correct, and for 90% of cases, it’s all you need. The only downside is that it relies on every developer on your team knowing this rule forever.

Solution 2: The Permanent Fix (The Composed Decorator)

If this logic is part of a shared library or a critical framework, relying on “remembering the order” is a recipe for future outages. A much more robust solution is to create a decorator that correctly handles the composition for you. You create one decorator that applies both the custom logic and the classmethod transformation.

import functools

# Create a decorator that IS a classmethod logger
def logged_classmethod(func):
    # First, wrap the function with our logging logic
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} on class {args[0].__name__}")
        return func(*args, **kwargs)
    
    # Then, turn the resulting wrapper into a classmethod
    return classmethod(wrapper)

class ReportGenerator:
    @logged_classmethod
    def generate_daily_report(cls):
        # Now there's only one decorator. No ambiguity.
        print(f"Generating report using {cls.__name__}")

ReportGenerator.generate_daily_report()

This is my preferred method for framework-level code. It’s explicit, reusable, and impossible for a junior dev to accidentally get the order wrong.

Solution 3: The ‘Nuclear’ Option (Making a Smarter Decorator)

Sometimes you can’t change the decorator order, or you want your decorator to be “smart” enough to handle being applied to anything—a regular function, a classmethod, whatever. This is more complex, but it makes your decorator incredibly robust. The goal is to inspect what you’re wrapping.

def smarter_log_call(func_or_descriptor):
    if isinstance(func_or_descriptor, (classmethod, staticmethod)):
        # The thing we are decorating is ALREADY a descriptor.
        # We need to reach inside it to get the actual function.
        original_function = func_or_descriptor.__func__
        
        @functools.wraps(original_function)
        def wrapper(*args, **kwargs):
            print(f"Calling decorated method: {original_function.__name__}")
            return original_function(*args, **kwargs)
        
        # Re-apply the original descriptor type to our new wrapper
        if isinstance(func_or_descriptor, classmethod):
            return classmethod(wrapper)
        elif isinstance(func_or_descriptor, staticmethod):
            return staticmethod(wrapper)
    else:
        # It's just a regular function, proceed as normal
        @functools.wraps(func_or_descriptor)
        def wrapper(*args, **kwargs):
            print(f"Calling decorated function: {func_or_descriptor.__name__}")
            return func_or_descriptor(*args, **kwargs)
        return wrapper

class FileProcessor:
    @smarter_log_call
    @classmethod
    def process_directory(cls, path):
        print(f"Processing directory {path} with {cls.__name__}")

FileProcessor.process_directory("/mnt/data/logs")

A Word of Warning: While the ‘Nuclear’ option is powerful, it adds complexity. You’re now writing code to handle Python’s internal descriptor protocol. Use this when you’re building a public-facing library or an internal tool where you absolutely cannot dictate decorator order. For a typical application service, Solution 1 or 2 is cleaner and easier to maintain.

At the end of the day, understanding that decorators are just nested function calls is the key. Once you see @A @B def f as A(B(f)), the “magic” disappears, and you can debug these issues with confidence. Keep building, and stay curious.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions