Python’s documentation isn’t entirely clear on what a decorator is or how it works, so here are the details.<\/p>\n\n\n\n\n\n\n\n
A decorator<\/strong> is a way to apply a wrapper<\/strong> around function. It’s given the name “decorator” because of the way you attach it to the function being wrapped: like a decoration.<\/p>\n\n\n\n The decorator itself does not actually wrap the function. A better name for it might be a wrapper factory<\/strong>.<\/p>\n\n\n\n Python unfortunately refers to both “wrapper factories” and “wrapper-factory factories” as “decorators”, which is quite confusing.<\/p>\n\n\n\n Closures are important to the workings of the decorator. If you already know what a closure is, skip to the next heading. If not, here is a brief explanation.<\/p>\n\n\n\n A closure allows you to create a function and have it reference variables from its enclosing scope later, when it is executed. Consider the code below:<\/p>\n\n\n\n The The function It’s equivalent to a class that does this:<\/p>\n\n\n\n Suppose you wish to wrap The code above achieves the goal, but it has one flaw: Because it calls To achieve this we will create a factory function<\/strong> that returns the wrapper. The function to be wrapped is passed in as a parameter and the wrapper function closes around it, storing a reference to it.<\/p>\n\n\n\n This will now print “Hello world.” before any wrapped function.<\/p>\n\n\n\n The Suppose now that you wish to customize the wrapper function for each function that you wrap. This is achieved by creating a factory function that returns a wrapper factory. This allows you to pass variables in to the wrapper-factory-factory and have the wrapper-factory or the wrapper close around them.<\/p>\n\n\n\n For example, suppose you wish to customize the message printed by the wrapper:<\/p>\n\n\n\n This is starting to get a little complicated, so lets go through it step by step:<\/p>\n\n\n\n If you are working with existing code, how do you know if you are working with a decorator or a decorator factory?<\/p>\n\n\n\n A decorator will not have brackets (parentheses) following it. A decorator factory will.<\/p>\n\n\n\n If you are creating your own decorator then:<\/p>\n\n\n\n There are two ways to pass parameters through your wrapper to the wrapped function. If the functions you are wrapping will always have the same parameters then you can just copy them. Otherwise, you can use Python’s variable-parameters syntax. The return value of the wrapped function can be returned directly from the wrapper.<\/p>\n\n\n\n One final pattern that you may encounter is to use a decorator to do some work when the function is defined. The decorator then returns the function directly, instead of returning a wrapper around it.<\/p>\n\n\n\n For example, suppose you wish to add your function to a list of commands that users can invoke:<\/p>\n\n\n\n The code above will add “help” to the Note that this happens when the Python’s documentation isn’t entirely clear on what a decorator is or how it works, so here are the details.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[33],"tags":[],"class_list":["post-224","post","type-post","status-publish","format-standard","hentry","category-python"],"_links":{"self":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/224","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/comments?post=224"}],"version-history":[{"count":10,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/224\/revisions"}],"predecessor-version":[{"id":235,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/224\/revisions\/235"}],"wp:attachment":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/media?parent=224"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/categories?post=224"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/tags?post=224"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}An Aside: Closures<\/h2>\n\n\n\n
def create_function(message):\n\n def say():\n print(message)\n\n return say\n\nsay_hello = create_function("hello")\n\n# Print "hello".\nsay_hello()<\/code><\/pre>\n\n\n\nsay()<\/code> function is keeping a reference to the message<\/code> variable, even after the create_function<\/code> function has returned.<\/p>\n\n\n\nsay()<\/code> is a closure<\/em> that closes around<\/em> the message<\/code> variable.<\/p>\n\n\n\nclass Say:\n __init__(message):\n self.message = message\n\n __call__()\n print(self.message)\n\nsay_hello = Say("hello")\n\n# Print "hello".\nsay_hello()<\/code><\/pre>\n\n\n\nStarting Point: A Simple Wrapper<\/h2>\n\n\n\n
my_func()<\/code> such that it prints a message whenever it is called. This can be achieved by creating a wrapper function that calls my_func()<\/code>, and then reassigning the variable my_func<\/code> so it actually points to the wrapper function:<\/p>\n\n\n\n# The function to be wrapped.\ndef my_func():\n print('Doing some work...')\n\n# The wrapper.\ndef wrapper():\n print('Hello world.')\n my_func()\n\n# Make it so that calling my_func() actually calls wrapper().\nmy_func = wrapper\n\n# This will print "Hello world. Doing some work...".\nmy_func()<\/code><\/pre>\n\n\n\nImprovement: A Wrapper Factory<\/h2>\n\n\n\n
my_func()<\/code> directly, the wrapper can only ever wrap my_func()<\/code>. It would be nice if we could wrap any<\/em> function in our wrapper.<\/p>\n\n\n\ndef wrapper_factory(func):\n\n def wrapper():\n print('Hello world.')\n return func()\n\n return wrapper\n\nmy_func = wrapper_factory(my_func)\nmy_other_func = wrapper_factory(my_other_func)<\/code><\/pre>\n\n\n\nSyntactic Sugar: @decorator<\/h2>\n\n\n\n
@decorator<\/code> syntax in Python is a simple syntax for the above: It runs the wrapper factory and replaces the function with the wrapped function.<\/p>\n\n\n\ndef wrapper_factory(func):\n\n def wrapper():\n print('Hello world.')\n return func()\n\n return wrapper\n\n@wrapper_factory\ndef my_func():\n print('Doing some work...') <\/code><\/pre>\n\n\n\nCustomizing the Decorator: A Wrapper-Factory-Factory<\/h2>\n\n\n\n
def wrapper_factory_factory(message):\n\n def wrapper_factory(func):\n\n def wrapper():\n print(message)\n return func()\n\n return wrapper\n\n return wrapper_factory\n\n@wrapper_factory_factory('HELLO')\ndef my_func():\n print('Doing some work...')\n\n# This will print "HELLO Doing some work..."\nmy_func()<\/code><\/pre>\n\n\n\n\n
wrapper_factory_factory('HELLO')<\/code> is called.
This closes around the message<\/code> variable and returns a wrapper_factory<\/code> function.<\/li>\n\n\n\nwrapper_factory(my_func)<\/code> is called.
This closes around the func<\/code> variable and returns a wrapper<\/code> function.<\/li>\n\n\n\nmy_func<\/code> is replaced by the wrapper<\/code> function returned from step 2.<\/li>\n\n\n\nmy_func()<\/code>, which actually calls wrapper()<\/code>.wrapper()<\/code> prints the message “HELLO”, then calls the original my_func()<\/code> function.<\/li>\n<\/ol>\n\n\n\nDecorator or Decorator Factory?<\/h2>\n\n\n\n
# No brackets: It is a decorator and returns a wrapper.\n@decorator1\n\n# Brackets: It is a decorator factory and returns a decorator.\n@decorator2()<\/code><\/pre>\n\n\n\n\n
Parameters and Return Values<\/h2>\n\n\n\n
def decorator(func):\n\n def wrapper(*args, **kwargs):\n return func(*args, **kwargs)\n\n@decorator\ndef my_func(... any parameters ...):\n # ...<\/code><\/pre>\n\n\n\nDecorators That Aren’t Wrappers<\/h2>\n\n\n\n
commands = []\n\ndef command_decorator(func):\n commands.append(func.__name__)\n\n return func\n\n@command_decorator\ndef help():\n # Do some worker...<\/code><\/pre>\n\n\n\ncommands<\/code> list. It uses Python’s built-in __name__<\/code> property to get the function’s name.<\/p>\n\n\n\nhelp()<\/code> function is defined, not when it is called.<\/p>\n","protected":false},"excerpt":{"rendered":"