Add section about function decorators.

trekhleb · trekhleb · commit c3b505737cfe · 2018-08-30T22:02:19.000+03:00
diff --git a/README.md b/README.md
@@ -92,6 +92,7 @@ written correctly.
     - [Lambda Expressions](src/functions/test_lambda_expressions.py) (`lambda` statement)
     - [Documentation Strings](src/functions/test_function_documentation_string.py)
     - [Function Annotations](src/functions/test_function_annotations.py)
+    - [Function Decorators](src/functions/test_function_decorators.py)
 6. **Classes**
     - [Class Definition](src/classes/test_class_definition.py) (`class` statement)
     - [Class Objects](src/classes/test_class_objects.py)
diff --git a/src/functions/test_function_decorators.py b/src/functions/test_function_decorators.py
@@ -0,0 +1,91 @@
+"""Function Decorators.
+
+@see: https://www.thecodeship.com/patterns/guide-to-python-function-decorators/
+
+Function decorators are simply wrappers to existing functions. In the context of design patterns,
+decorators dynamically alter the functionality of a function, method or class without having to
+directly use subclasses. This is ideal when you need to extend the functionality of functions that
+you don't want to modify. We can implement the decorator pattern anywhere, but Python facilitates
+the implementation by providing much more expressive features and syntax for that.
+"""
+
+
+def test_function_decorators():
+    """Function Decorators."""
+
+    # Function decorators are simply wrappers to existing functions. Putting the ideas mentioned
+    # above together, we can build a decorator. In this example let's consider a function that
+    # wraps the string output of another function by p tags.
+
+    # This is the function that we цфте to decorate.
+    def greeting(name):
+        return "Hello, {0}!".format(name)
+
+    # This function decorates another functions output with <p> tag.
+    def decorate_with_p(func):
+        def function_wrapper(name):
+            return "<p>{0}</p>".format(func(name))
+        return function_wrapper
+
+    # Now, let's call our decorator and pass the function we want decorate to it.
+    my_get_text = decorate_with_p(greeting)
+
+    # Here we go, we've just decorated the function output without changing the function itself.
+    assert my_get_text('John') == '<p>Hello, John!</p>'  # With decorator.
+    assert greeting('John') == 'Hello, John!'  # Without decorator.
+
+    # Now, Python makes creating and using decorators a bit cleaner and nicer for the programmer
+    # through some syntactic sugar  There is a neat shortcut for that, which is to mention the
+    # name of the decorating function before the function to be decorated. The name of the
+    # decorator should be prepended with an @ symbol.
+
+    @decorate_with_p
+    def greeting_with_p(name):
+        return "Hello, {0}!".format(name)
+
+    assert greeting_with_p('John') == '<p>Hello, John!</p>'
+
+    # Now let's consider we wanted to decorate our greeting function by one more functions to wrap a
+    # div the string output.
+
+    # This will be our second decorator.
+    def decorate_with_div(func):
+        def function_wrapper(text):
+            return "<div>{0}</div>".format(func(text))
+        return function_wrapper
+
+    # With the basic approach, decorating get_text would be along the lines of
+    # greeting_with_div_p = decorate_with_div(decorate_with_p(greeting_with_p))
+
+    # With Python's decorator syntax, same thing can be achieved with much more expressive power.
+    @decorate_with_div
+    @decorate_with_p
+    def greeting_with_div_p(name):
+        return "Hello, {0}!".format(name)
+
+    assert greeting_with_div_p('John') == '<div><p>Hello, John!</p></div>'
+
+    # One important thing to notice here is that the order of setting our decorators matters.
+    # If the order was different in the example above, the output would have been different.
+
+    # Passing arguments to decorators.
+
+    # Looking back at the example before, you can notice how redundant the decorators in the
+    # example are. 2 decorators(decorate_with_div, decorate_with_p) each with the same
+    # functionality but wrapping the string with different tags. We can definitely do much better
+    # than that. Why not have a more general implementation for one that takes the tag to wrap
+    # with as a string? Yes please!
+
+    def tags(tag_name):
+        def tags_decorator(func):
+            def func_wrapper(name):
+                return "<{0}>{1}</{0}>".format(tag_name, func(name))
+            return func_wrapper
+        return tags_decorator
+
+    @tags('div')
+    @tags('p')
+    def greeting_with_tags(name):
+        return "Hello, {0}!".format(name)
+
+    assert greeting_with_tags('John') == '<div><p>Hello, John!</p></div>'
