wrapt

A basic Python decorator implemented via a function closure or a class instance often breaks introspection and the Python object model. Common issues include:

• Loss of Metadata: The wrapped function's __name__ and __doc__ attributes are replaced by the wrapper's attributes.
• Broken Introspection: Tools like inspect.getargspec() or inspect.getsource() will return information about the wrapper instead of the original function, or fail entirely.
• Descriptor Protocol Failure: Simple decorators can break @classmethod and @staticmethod because they do not correctly handle descriptors that need to be bound to a class or instance before being called.
• Attribute Errors: Using functools.wraps or functools.update_wrapper on certain objects (like classmethod objects in older Python versions) can raise AttributeError if attributes like __module__ are missing.

The pure-Python and C implementations of ObjectProxy handle the __qualname__ attribute differently:

• Pure-Python implementation: Takes a snapshot of the wrapped object's __qualname__ at construction time. If the wrapped object's __qualname__ is mutated directly later, the proxy still returns the original value.
• C extension implementation: Performs a live-read of the wrapped object's __qualname__ on every access.

Consistency: If you set __qualname__ through the proxy (e.g., proxy.__qualname__ = "new"), both implementations will agree because the change is applied to the wrapped object and the local snapshot (in Python) simultaneously.

import wrapt

def foo(): pass

proxy = wrapt.ObjectProxy(foo)
foo.__qualname__ = "Changed"

# Pure-Python: proxy.__qualname__ returns the original value (snapshot)
# C extension: proxy.__qualname__ returns "Changed"

When using wrapt decorators on class methods (instance methods, class methods, or static methods), there is additional overhead compared to decorating simple functions. This is because wrapt implements decorators as descriptors to correctly honor the Python execution model (ensuring proper binding of methods to instances).

Key Performance Insights:

• Pure Python Implementation: A pure Python implementation of the wrapt decorator factory incurs significantly higher overhead (e.g., ~6.67 $\mu$s per call) because it must handle descriptor logic via __get__ to manage method binding.
• C Extension Implementation: Using the wrapt C extension significantly reduces this overhead (e.g., ~0.836 $\mu$s per call), making it much closer to the performance of a simple function closure decorator.
• Why the overhead exists: To be 'correct' and avoid breaking code during monkey patching, wrapt must perform extra steps during the __get__ call to ensure the method is properly bound to the class or instance.

If you are performing high-frequency calls (e.g., thousands of calls per web request), the difference between a pure Python implementation and the C extension implementation can be the difference between milliseconds and microseconds of added latency.

In Python, decorators can fail when applied to objects that implement the descriptor protocol, such as @classmethod or @staticmethod.

The Problem

A standard decorator (often implemented as a function closure) typically wraps a function and calls it directly. However, descriptors like @classmethod do not have a __call__ method themselves; instead, they implement __get__ to return a bound method object that is callable.

If a decorator is applied on top of a descriptor:

@decorator
@classmethod
def my_method(cls): ...

The decorator attempts to call the @classmethod object directly, resulting in a TypeError: 'classmethod' object is not callable because it bypassed the descriptor's __get__ method.

The Solution

To correctly support descriptors, a decorator must itself be a descriptor. It must implement the __get__ method to ensure that when the decorated object is accessed as a class attribute, the descriptor protocol is propagated correctly.

When an instance method is called directly via the class (e.g., Class.method(instance, *args)), the decorator factory must ensure the instance is correctly identified rather than being treated as the first element of args.

To achieve this, the bound_function_wrapper should check if self.instance is None. If it is, it should pop the first element from args to use as the instance and then use functools.partial to bind that instance to the wrapped function before passing it to the user's wrapper.

class bound_function_wrapper(object_proxy):
    def __call__(self, *args, **kwargs):
        if self.instance is None:
            # Handle Class.method(instance, ...)
            instance, args = args[0], args[1:]
            wrapped = functools.partial(self.wrapped, instance)
            return self.wrapper(wrapped, instance, args, kwargs)
        return self.wrapper(self.wrapped, self.instance, args, kwargs)