Python Decorators in 12 Steps (2012) (simeonfranklin.com)

When I worked at my last company, we had to expose an easy-to-use API for an optimistic-concurrency database that required cooperating clients to retry operations in a variety of situations. Rather than asking every client to implement correct retry behavior, we tried to expose a simple retry loop in an idiomatic way in each client language.

Python was far and away my favorite, since we could take advantage of decorators to make everything relatively seamless.

Consider a function something like this:

  def do_something_transactionally(db, *args, **kwargs):
      tr = db.create_transaction()
      # do some things with the transaction object
      tr.commit().get()

This code was broken in a number of ways -- there's no retry, or handling of errors from commit, etc.

So we exposed a decorator in Python to handle all of these issues for the common case:

  @transactional
  def do_something_transactionally(db, *args, **kwargs):
      # do some things with the transaction object

This was more or less equivalent to:

  def do_something_transactionally(db, *args, **kwargs):
      tr = db.create_transaction()
      while True:
          try:
              # do some things with the transaction object
              tr.commit().wait()
              break
          except Error as e:
              tr.on_error(e).get()

It was actually even niftier than that, though, because the decorator allowed you to pass in either a transaction object or a database object. If the caller provided a transaction rather than a database, then the decorator did not create a new transaction or commit it; this allowed composition of more complicated transactional calls of decorated functions.

So I will definitely grant you that if you encountered this code, you would need to understand what @transactional meant, but I would definitely argue that this was cleaner and easier to deal with than asking every function to explicitly implement the retry logic.

     with transactional as transaction:
          # do something

  @transactional
  def thing_one(tr, *args):
      # stuff

  @transactional
  def thing_two(tr, *args):
      # other stuff

  @transactional
  def both_things(tr, *args):
      thing_one(tr, args)
      thing_two(tr, args)

@something is a function call and if it is properly named, it should give you a hint as to what it does without scrolling through the source code.

So you're saying:

  def baz():
     bar1()
     foo()
     bar2()

is hugely better than:

  @bar
  def baz():
     foo()

I think it massively depends on naming and the general context. I can see myself choosing either depending on the precise situation.

As with all things in Python (and coding in general) taste and discretion are key: use decorators when they improve legibility and stop using them when they don't.

There's also Graham Dumpleton's "How you implemented your Python decorator is wrong" blog post - http://blog.dscpl.com.au/2014/01/how-you-implemented-your-py... and the related "Decorators and monkey patching" list http://blog.dscpl.com.au/p/decorators-and-monkey-patching.ht...

> Decorators are very easy to understand

I use them every day but I think this view only seems true when one is looking back in hindsight. Even fundamental ideas like assignment and the scoping of variables can be difficult for newbies. To really grok decorators (i.e. not just to use them as prescribed by the Django/Flask/whatever docs but to take the next step and create your own), one needs to be comfortable with the idea of first class functions - not a first day topic, at any rate.

I don't care for that explanation, because they don't have to call the original function. (E.g. an @skip('not yet implemented') test decorator.) Or they could call it multiple times. The post-decoration function doesn't even need to be a function[1]. And that doesn't touch on decorated classes, either.

I find them easiest to understand using the source-rewriting explanation:

    @foo
    def bar(...):
       ...

is the same as

    def bar(...):
       ...

    bar = foo(bar)

Classes can be decorated in the same way. This also explains why decorators taking arguments work how they do: because

    @foo(...)

turns into

    bar = foo(...)(bar)

and thus foo needs to return a decorator, not be a decorator. (Where a decorator can be thought of as "any function that accepts a single argument", or as "any function which happens to be useful as a decorator", or whatever.)

But explaining them like this doesn't make it obvious what they're for. (I can worry about that later, but others find it easier to understand things given a motivating example.) And some people haven't got their heads around first-class functions yet. So while this would be my preferred explanation if I was talking to a version of me who didn't know decorators yet, it's not the best for everyone.

[1] This hasn't previously occurred to me, and I've never seen it explored, but I just verified that it works:

    def const(fun):
        return fun()

    @const
    def bar():
        return 3

    print 3 * bar # 9

I'm not sure if this would be useful for anything.

consider the example

    @decorator_without_args
    def function():
        pass

this is equivalent to

    function = decorator_without_args(function)

now consider the other case, where the decorator takes in some args:

    @dec_with_args("hello", "world")
    def func():
        pass

this is equivalent to

    function = decorator_with_args("hello", "world")(function)

Or in other words, the expression after @ needs to evaluate to a Callable which is then called on the function you are decorating, so with @a_decorator, you call a_decorator on your function. When you use @with_args(1, 2, 3), you are calling the function "with_args" and then the result of that function is your decorator. So an example of this working is like so:

    debug_list = []
    other_list = []
    def dynamic_debug_decorator(output_list=debug_list):
        # dynamic debug decorator should return a decorator function
        # realistically, ddd is a decorator factory, not a decorator
        def debug_decorator(function):
            # so this is our real decorator
            def decorated_function(*args, **kwargs):
                # and this is the new function we return
                output_list.append(function)  # because silly example
                return function(*args, **kwargs)
            return decorated_function
        return debug_decorator

so now using that decorator:

    @dynamic_debug_decorator  
    def function():
        pass

this fails, because dynamic debug decorator takes a list, but is now receiving a function. Instead we need to call it like so:

    @dynamic_debug_decorator
    def function():
        pass

this works, using the default values.

    @dynamic_debug_decorator()
    def function():
        pass

Just FYI, The expression is "rite of passage."