var d=Object.defineProperty,u=Object.defineProperties;var m=Object.getOwnPropertyDescriptors;var o=Object.getOwnPropertySymbols;var i=Object.prototype.hasOwnProperty,s=Object.prototype.propertyIsEnumerable;var l=(a,t,n)=>t in a?d(a,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):a[t]=n,e=(a,t)=>{for(var n in t||(t={}))i.call(t,n)&&l(a,n,t[n]);if(o)for(var n of o(t))s.call(t,n)&&l(a,n,t[n]);return a},p=(a,t)=>u(a,m(t));var c=(a,t)=>{var n={};for(var r in a)i.call(a,r)&&t.indexOf(r)<0&&(n[r]=a[r]);if(a!=null&&o)for(var r of o(a))t.indexOf(r)<0&&s.call(a,r)&&(n[r]=a[r]);return n};const layoutProps={},MDXLayout="wrapper";function MDXContent(n){var r=n,{components:a}=r,t=c(r,["components"]);return mdx(MDXLayout,p(e(e({},layoutProps),t),{components:a,mdxType:"MDXLayout"}),mdx("p",null,"When I started programming with Python, if I am not mistaken, the version was 3.3. Therefore, when I started programming, decorators had been available to the Python community for a long time."),mdx("p",null,"Function decorators came to Python with version 2.2 and Class decorators came to Python with version 2.6."),mdx("p",null,"Personally, I see Python's Decorator feature as a very powerful feature of the language."),mdx("p",null,"Actually, my aim is to make a series of articles about the most difficult to understand topics in Python. I plan to cover these topics, which are a little more than ten, one by one."),mdx("p",null,"In this article, I will try to touch on every part of the Decorators topic as much as I can."),mdx("h2",null,"1. Historical Context"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Early Days (Pre-Python 2.2):")," Before decorators, modifying functions or classes often involved manual wrapping or monkey-patching, which was cumbersome and less readable."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Metaclasses (Python 2.2):")," Metaclasses provided a way to control class creation, offering some of the functionality that decorators would later provide, but they were complex for simple modifications."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"PEP 318 (Python 2.4):")," Decorators were formally introduced in Python 2.4 through ",mdx("a",e({parentName:"li"},{href:"https://peps.python.org/pep-0318/"}),"PEP 318"),". The proposal was inspired by annotations in Java and aimed to provide a cleaner, more declarative way to modify functions and methods."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Class Decorators (Python 2.6):")," Python 2.6 extended decorator support to classes, further enhancing their versatility."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Widespread Adoption:")," Decorators quickly became a popular feature, used extensively in frameworks like Flask and Django for routing, authentication, and more.")),mdx("h2",null,"2. What are Decorators?"),mdx("p",null,"In essence, ",mdx("a",e({parentName:"p"},{href:"https://en.wikipedia.org/wiki/Decorator_pattern"}),"a decorator is a design pattern")," in Python that allows you to modify the behavior of a function or a class without changing its core structure. Decorators are a form of metaprogramming, where you're essentially writing code that manipulates other code."),mdx("p",null,"You know ",mdx("a",e({parentName:"p"},{href:"https://realpython.com/python-scope-legb-rule/"}),"Python resolve names using the scope given in order below"),":"),mdx("ol",null,mdx("li",{parentName:"ol"},"Local"),mdx("li",{parentName:"ol"},"Enclosing"),mdx("li",{parentName:"ol"},"Global"),mdx("li",{parentName:"ol"},"Built-in")),mdx("p",null,"Decorators are sit Enclosing scope, which is closely related to the ",mdx("a",e({parentName:"p"},{href:"https://en.wikipedia.org/wiki/Closure_(computer_programming)"}),"Closure concept"),"."),mdx("p",null,mdx("strong",{parentName:"p"},"Key Idea:")," A decorator takes a function as input, adds some functionality to it, and returns a modified function."),mdx("p",null,mdx("strong",{parentName:"p"},"Analogy:")," Think of a decorator as a gift wrapper. You have a gift (the original function), and you wrap it with decorative paper (the decorator) to make it look nicer or add extra features (like a bow or a card). The gift inside remains the same, but its presentation or associated actions are enhanced."),mdx("h2",null,"A) Decorator Variations: Function-based vs. Class-based"),mdx("p",null,`Most decorators in Python are implemented using functions, but you can also create decorators using classes. Function-based decorators are more common and simpler, while class-based decorators offer additional flexibility.`),mdx("h3",null,"Function-based Basic Decorator Syntax"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def my_decorator(func): def wrapper(*args, **kwargs): # Do something before calling the decorated function print("Before function call") result = func(*args, **kwargs) # Do something after calling the decorated function print("After function call") return result return wrapper @my_decorator def say_hello(name): print(f"Hello, {name}!") say_hello("World") `)),mdx("p",null,mdx("strong",{parentName:"p"},"Explanation:")),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("inlineCode",{parentName:"li"},"my_decorator")," is the decorator function. It takes the function func to be decorated as input."),mdx("li",{parentName:"ul"},mdx("inlineCode",{parentName:"li"},"wrapper")," is an inner function that wraps the original function's call. It can execute code before and after the original function."),mdx("li",{parentName:"ul"},mdx("inlineCode",{parentName:"li"},"@my_decorator")," is the decorator syntax. It's equivalent to ",mdx("inlineCode",{parentName:"li"},"say_hello = my_decorator(say_hello)"),".")),mdx("h3",null,"Class-based Basic Decorator Syntax"),mdx("p",null,"These use classes instead of functions to define decorators."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`class MyDecorator: def __init__(self, func): self.func = func def __call__(self, *args, **kwargs): # Do something before calling the decorated function print("Before function call") result = self.func(*args, **kwargs) # Do something after calling the decorated function print("After function call") return result @MyDecorator def say_hello(name): print(f"Hello, {name}!") say_hello("World") `)),mdx("p",null,mdx("strong",{parentName:"p"},"Explanation:")),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("inlineCode",{parentName:"li"},"MyDecorator")," is a class that acts as a decorator."),mdx("li",{parentName:"ul"},"The ",mdx("inlineCode",{parentName:"li"},"__init__")," method stores the function to be decorated."),mdx("li",{parentName:"ul"},"The ",mdx("inlineCode",{parentName:"li"},"__call__")," method makes the class instance callable, allowing it to be used like a function.")),mdx("hr",null),mdx("h2",null,"B) ",mdx("strong",{parentName:"h2"},"Implementing a Simple Decorator")),mdx("p",null,`The fundamental concept of decorators is that they are functions that take another function as an argument and extend its behavior without explicitly modifying it. Here's the simplest form:`),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def my_decorator(func): def wrapper(): print("Something is happening before the function is called.") func() print("Something is happening after the function is called.") return wrapper # Using the decorator with @ syntax @my_decorator def say_hello(): print("Hello!") # When we call say_hello() say_hello() # This is equivalent to: # say_hello = my_decorator(say_hello) `)),mdx("h2",null,"C) Implementing a Decorator with Arguments"),mdx("p",null,"Let's create a decorator that logs the execution time of a function:"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def decorator_with_args(func): def wrapper(*args, **kwargs): # Accept any number of arguments print(f"Arguments received: {args}, {kwargs}") return func(*args, **kwargs) # Pass arguments to the original function return wrapper @decorator_with_args def greet(name, greeting="Hello"): print(f"{greeting}, {name}!") greet("Alice", greeting="Hi") # Prints arguments then "Hi, Alice!" `)),mdx("h2",null,"D) Implementing a Parameterized Decorator"),mdx("p",null,"These are decorators that can accept their own parameters:"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def repeat(times): def decorator(func): def wrapper(*args, **kwargs): for _ in range(times): result = func(*args, **kwargs) return result return wrapper return decorator @repeat(times=3) def greet(name): print(f"Hello {name}") return "Done" greet("Bob") # Prints "Hello Bob" three times `)),mdx("h2",null,"E) Implementing a Class Decorator"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def singleton(cls): instances = {} def get_instance(*args, **kwargs): if cls not in instances: instances[cls] = cls(*args, **kwargs) return instances[cls] return get_instance @singleton class DatabaseConnection: def __init__(self): print("Initializing database connection") # Creating multiple instances actually returns the same instance db1 = DatabaseConnection() # Prints initialization db2 = DatabaseConnection() # No initialization printed print(db1 is db2) # True `)),mdx("h2",null,"F) Implementing Method Decorators"),mdx("p",null,"These are specifically designed for class methods:"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def debug_method(func): def wrapper(self, *args, **kwargs): print(f"Calling method {func.__name__} of {self.__class__.__name__}") return func(self, *args, **kwargs) return wrapper class MyClass: @debug_method def my_method(self, x, y): return x + y obj = MyClass() print(obj.my_method(5, 3)) `)),mdx("h2",null,"G) Implementing Decorator Chaining"),mdx("p",null,"Multiple decorators can be applied to a single function:"),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def bold(func): def wrapper(): return "" + func() + "" return wrapper def italic(func): def wrapper(): return "" + func() + "" return wrapper @bold @italic def greet(): return "Hello!" print(greet()) # Outputs: Hello! `)),mdx("p",null,mdx("strong",{parentName:"p"},"Explanation:")),mdx("ul",null,mdx("li",{parentName:"ul"},"Decorators are applied from bottom to top."),mdx("li",{parentName:"ul"},"It is more like in what we do in math: ",mdx("inlineCode",{parentName:"li"},"f(g(x))"),"."),mdx("li",{parentName:"ul"},mdx("inlineCode",{parentName:"li"},"italic")," is applied first, then ",mdx("inlineCode",{parentName:"li"},"bold"),".")),mdx("h2",null,"H) What happens if we don't use @functools.wraps ?"),mdx("p",null,"The ",mdx("inlineCode",{parentName:"p"},"functools.wraps")," decorator, ",mdx("a",e({parentName:"p"},{href:"https://docs.python.org/3/library/functools.html#functools.wraps"}),"See docs"),", is a helper function that preserves the metadata of the original function (like its name, docstring, and signature) when you wrap it with a decorator. If you don't use it, you'll lose this important information."),mdx("p",null,mdx("strong",{parentName:"p"},"Example:")),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def my_decorator(func): def wrapper(*args, **kwargs): """Wrapper docstring""" return func(*args, **kwargs) return wrapper @my_decorator def my_function(): """My function docstring""" pass print(my_function.__name__) print(my_function.__doc__) `)),mdx("p",null,mdx("strong",{parentName:"p"},"Output:")),mdx("pre",null,mdx("code",e({parentName:"pre"},{}),`wrapper Wrapper docstring `)),mdx("p",null,mdx("strong",{parentName:"p"},"Problem:")),mdx("ul",null,mdx("li",{parentName:"ul"},"The original function's name (",mdx("inlineCode",{parentName:"li"},"my_function"),') and docstring ("My function docstring") are lost.'),mdx("li",{parentName:"ul"},"This can make debugging and introspection difficult.")),mdx("p",null,mdx("strong",{parentName:"p"},"Solution: Use ",mdx("inlineCode",{parentName:"strong"},"functools.wraps"),"):")),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`import functools def my_decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): """Wrapper docstring""" return func(*args, **kwargs) return wrapper @my_decorator def my_function(): """My function docstring""" pass print(my_function.__name__) print(my_function.__doc__) `)),mdx("p",null,mdx("strong",{parentName:"p"},"Output:")),mdx("pre",null,mdx("code",e({parentName:"pre"},{}),`my_function My function docstring `)),mdx("h3",null,mdx("strong",{parentName:"h3"},"Benefits of ",mdx("inlineCode",{parentName:"strong"},"functools.wraps"),":")),mdx("ul",null,mdx("li",{parentName:"ul"},"Preserves function metadata."),mdx("li",{parentName:"ul"},"Improves code readability and maintainability."),mdx("li",{parentName:"ul"},"Makes debugging easier."),mdx("li",{parentName:"ul"},"Helps with introspection tools and documentation generators.")),mdx("h2",null,"I) Decorators with State"),mdx("p",null,"Decorators can also maintain state between function calls. This is particularly useful for scenarios like caching or counting function calls."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-python"}),`def count_calls(func): def wrapper(*args, **kwargs): wrapper.calls += 1 print(f"Call {wrapper.calls} of {func.__name__}") return func(*args, **kwargs) wrapper.calls = 0 return wrapper @count_calls def say_hello(): print("Hello!") say_hello() # Call 1 of say_hello say_hello() # Call 2 of say_hello `)),mdx("p",null,mdx("strong",{parentName:"p"},"Output:")),mdx("pre",null,mdx("code",e({parentName:"pre"},{}),`Call 1 of say_hello Hello! Call 2 of say_hello Hello! `)),mdx("p",null,"Explanation:"),mdx("p",null,`The wrapper function maintains a counter (calls) that increments each time the decorated function is called. This is a simple example of how decorators can be used to maintain state.`),mdx("h2",null,"J) Best Practices for Python Decorators"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Use ",mdx("inlineCode",{parentName:"strong"},"functools.wraps"),":")," Always use ",mdx("inlineCode",{parentName:"li"},"@functools.wraps")," in your decorators to preserve the original function's metadata."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Keep Decorators Simple:")," Decorators should ideally do one specific thing and do it well. This makes them more reusable and easier to understand."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Document Your Decorators:")," Explain what your decorator does, what arguments it takes, and what it returns."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Test Your Decorators:")," Write unit tests to ensure your decorators work as expected in various scenarios."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Consider the Order of Chaining:")," Be mindful of the order when chaining multiple decorators, as it affects the execution flow.")),mdx("h2",null,"K) Bad Implementations (Anti-Patterns)"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Overly Complex Decorators:")," Avoid creating decorators that are too complex or try to do too many things. This makes them hard to understand, maintain, and debug."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Ignoring ",mdx("inlineCode",{parentName:"strong"},"functools.wraps"),":")," Forgetting to use ",mdx("inlineCode",{parentName:"li"},"@functools.wraps")," leads to loss of function metadata, which can cause issues with introspection and debugging."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Side Effects:")," Decorators should ideally not have unintended side effects outside of modifying the decorated function."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Hardcoding Values:")," Avoid hardcoding values within decorators. Instead, use decorator factories to make them configurable."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Not Handling Arguments Properly:")," Ensure your ",mdx("inlineCode",{parentName:"li"},"wrapper")," function can handle any number of positional and keyword arguments using ",mdx("inlineCode",{parentName:"li"},"*args")," and ",mdx("inlineCode",{parentName:"li"},"**kwargs")," if the decorator is meant to be used with a variety of functions.")),mdx("h2",null,"L) 10. Real-World Use Cases"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Logging:")," Recording function calls, arguments, and return values for debugging or auditing."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Timing:")," Measuring the execution time of functions for performance analysis."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Caching:")," Storing the results of expensive function calls to avoid redundant computations (memoization)."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Authentication and Authorization:")," Verifying user credentials or permissions before executing a function."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Input Validation:")," Checking if the arguments passed to a function meet certain criteria."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Rate Limiting:")," Controlling the number of times a function can be called within a specific time period."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Retry Logic:")," Automatically retrying a function call if it fails due to a temporary error."),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Framework-Specific Tasks:")," Frameworks like Flask and Django use decorators for routing (mapping URLs to functions), registering plugins, and more.")),mdx("h2",null,"M) Curated Lists of Python Decorators"),mdx("p",null,"You can find a curated lists of Python decorators below:"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"https://github.com/lord63/awesome-python-decorator"}),"Awesome Python Decorators")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"https://wiki.python.org/moin/PythonDecoratorLibrary"}),"Python Decorator Library"))),mdx("h2",null,"N) 11. Conclusion"),mdx("p",null,`Decorators are a powerful and elegant feature in Python that allows you to enhance functions and classes in a clean and declarative way. By understanding the principles, best practices, and potential pitfalls, you can effectively leverage decorators to write more modular, maintainable, and expressive code. They are a valuable tool in any Python programmer's arsenal, especially when working with frameworks or building reusable components.`))}MDXContent.isMDXComponent=!0;