When to write a decorator(context manager) vs When to avoid

[YooSunYoung]

When to write a decorator

Decorator is not neat to write and it has bad readability if it's too complicated,
but it helps very much in some cases like below.
So I wrote down in which cases the decorator bypass the disadvantages.

In order to write a decorator easier, there is a wrapper tool module beamlime.tools.wrappers.
I will use wraps_better from the module in the example code below.
It updates the signature and __doc__ of wrapper function from wrapped function.
You can also just use functools.wraps if you don't want the signature to be updated.

Validation

If you wrap a block of code with try-except for specific error,
or you want to validate anything at the beginning or at the end of the function,
it might be easier to write a decorator to do that.

def function_that_need_validation(some_numeric_input: int) -> int:
  if 0 < some_numeric_input < 10:
     raise ValueError(f"{some_numeric_input} is out of range [0, 10]")
  try:
      out = # ... do sth dangerous
  except:
      raise CustomException('Wlqdp rkdiehlsmsep rnlcksgek!')
  if 0 < out < 10:
     raise ValueError(f"{out} is out of range [0, 10]")
  return out

Then you can write a decorator like,

def check_range(func: Callable):
    @wraps_better(func)
    def wrapper(some_numeric_input: int):
        if not 0 < some_numeric_input < 10:
            raise ValueError(f"{some_numeric_input} is out of range [0, 10]")
        out = func(some_numeric_input)
        if not 10 < out < 20:
            raise ValueError(f"{out} is out of range [10, 20]")
        return out

    return wrapper

It may look like you just extended the code, but then the actual function we wanted write will look like this:

@check_range
def function_that_need_validation(some_numeric_input: int) -> int:
    return # ... do sth dangerous

And if there are multiple functions that need the same validation, it'll reduce a lot of lines of code.

A group of calls wraps a block of code and they MUST be called in order

Any group of code that must be sctrictly called in order is a good candidate to be a decorator or a context manager.
For example, once you lock a thread, you must release the thread at some point.

def function_that_need_thread_lock():
    thread.lock()
   try:
        # ... do something affects thread ...
   except Exception:
       # ...
   finally:
       thread.release()

In this case above, since the thread lock and release is wrapping the try-exception,
so it is a good candidate to be a context manager.
It can be written like below.

from contextlib import ContextDecorator

class thread_lock_needed(ContextDecorator):
    def __enter__(self):
        thread.acquire()

    def __exit__(self, *_):
        thread.release()

Then you can use the context manager like below.

def function_that_need_thread_lock():
   with thread_lock_needed():
       ...  # do the dangerous thing here

# or as a decorator.

@thread_lock_needed
def function_that_need_thread_lock():
   ...  # do the dangerous thing here

Context manager is much easier to write and read compared to decorator.
If the same context manager was written in a decorator way, it will look like below.

def thread_lock_needed(func: Callable):
    def wrapper(*args, **kwargs):
        thread.lock()
        try:
            func(*args, **kwargs)
        except:
          ...
        finally:
           thread.release()
    return wrapper

But when you need to see the arguments to the function call, or use the output of the function call you want to wrap, context manager might not be enough.

When to avoid decorator

We don't need decorators in general but we should avoid to write one especially if,

• The decorator will not be used more than 2 places.
• It will cause more than 2 stacks of decorators on functions.
• It needs too many variations, then it should be a normal function call so that you can easily pass arguments.