decopatch Library

1.4.10 · active · verified Sun Apr 12

decopatch is a Python library designed to simplify the creation of decorators. It addresses the common challenge in Python where writing decorators requires explicit handling of both with-parenthesis and without-parenthesis usages. The library is currently at version 1.4.10 and receives regular minor updates, maintaining an active development status.

Warnings

breaking Enabling the experimental 'stack introspection' feature (`enable_stack_introspection=True`) now raises an explicit `NotImplementedError` on Python 3.8 and newer versions. Users relying on this beta feature on recent Python versions will encounter errors.
Fix: Avoid using `enable_stack_introspection=True` on Python 3.8+ or consult documentation for alternatives if introspection is critical.
gotcha While `decopatch` significantly simplifies decorator creation, prior to version 1.4.6, there were reported bugs concerning incorrect injection of arguments, particularly when variable-positional arguments (`*args`) were present in the decorated function's signature. Although fixed, this highlights a potential 'gotcha' area for complex function signatures if not fully leveraging `decopatch`'s mechanisms or if custom wrapper logic is introduced without careful consideration.
Fix: Ensure `decopatch` is updated to at least version 1.4.6 to benefit from fixes related to variable-positional argument handling. Rely primarily on `decopatch`'s provided constructs for decorator creation to avoid manual signature manipulation errors.
gotcha The primary problem `decopatch` solves is enabling decorators to work with or without parentheses seamlessly. Manually attempting to detect how a decorator was called (e.g., by checking `callable(args[0])`) is a common and error-prone workaround in Python. Using `decopatch`'s `function_decorator`, `class_decorator`, or `decorator` correctly abstracts this complexity, preventing a significant footgun for decorator authors.
Fix: Always use `decopatch`'s decorator factories (`@function_decorator`, `@class_decorator`, `@decorator`) as intended to handle the parenthesis detection automatically, rather than implementing manual checks within your decorator logic.

Install

pip install decopatch Install latest version

Imports

function_decorator
```
from decopatch import function_decorator
```
Primary decorator factory for functions.
class_decorator
```
from decopatch import class_decorator
```
Decorator factory for classes.
decorator
```
from decopatch import decorator
```
Generic decorator factory for decorators that can be applied to both functions and classes. `function_decorator` and `class_decorator` are presets for this.
WRAPPED, F_ARGS, F_KWARGS
```
from decopatch import WRAPPED, F_ARGS, F_KWARGS
```
Symbols used in 'double-flat mode' for more compact decorator definitions, representing the decorated item, positional arguments, and keyword arguments respectively.

Quickstart

This quickstart demonstrates the `function_decorator` to create a decorator that seamlessly works with and without parentheses, as well as with explicit arguments. The decorator `add_tag` adds a `tag` attribute to the decorated function.

from decopatch import function_decorator

@function_decorator
def add_tag(tag='hi!'):
    """
    Example decorator to add a 'tag' attribute to a function.
    :param tag: the 'tag' value to set on the decorated function.
    """
    def _apply_decorator(f):
        """
        This method is called when `@add_tag` is used on a function `f`.
        It should return a replacement for `f`.
        """
        setattr(f, 'tag', tag)
        return f
    return _apply_decorator

# Usage without parenthesis
@add_tag
def foo1():
    pass
assert foo1.tag == 'hi!'

# Usage with empty parenthesis
@add_tag()
def foo2():
    pass
assert foo2.tag == 'hi!'

# Usage with arguments
@add_tag('hello')
def foo3():
    pass
assert foo3.tag == 'hello'

print(f"foo1 tag: {foo1.tag}")
print(f"foo2 tag: {foo2.tag}")
print(f"foo3 tag: {foo3.tag}")

view raw JSON →