decoratorExamples.py

from functools import wraps # this decorator preserves function metadata

####################### BASIC DECORATOR AND OVERVIEW ##########################

# Let's say we have this function:
def sayMyName_original(firstName, lastName):
	return f"{firstName} {lastName}"

# If we want to supplement its functionality, we can make a wrapper function.
# But if we have numerous functions and want to add similar functionality to
# many of them, that's when decorators can come in handy:
#   Decorators let us easily mass-produce wrappers!
#
# A decorator is a function that takes a function as an argument and returns a
# function that wraps the passed function.
#
# This means we're making:
#   a function
#	   which makes a wrapper function
#		   which runs a function.
#   

# The below decorator creates a wrapper that adds "Ser " before the value
# returned by the wrapped function.
def knight(myFunction):
	print("Creating wrapped function...")
	@wraps(myFunction)
	def wrapper(*args, **kwargs):
		print("Wrapper is about to run function...")
		result = myFunction(*args, **kwargs)
		print("Wrapper is finished running function!")
		return f"Ser {result}"
	return wrapper

# The print functions within the wrapper are there to demonstrate how your
# wrapper can make modifications to behavior before and/or after the
# internal function is called.  You can do things like modify arguments,
# modify return values, or track meta behavior like how long it took for
# a function to execute.

# Above we made a decorator, a function that returns a wrapped function.
# Now let's decorate our initial function.
# We just pass our initial function into the decorating function, which then
# returns a wrapped version of our initial function.
sayMyName = knight(sayMyName_original)

# Now let's see the results:
myName = sayMyName("Jon", "Arbuckle")
print(f"My name is {myName}.")
print()

# However, there's a more common way to apply decorators, one that uses a
# special syntax and makes the process more convenient.
# We can apply the decorator right when we're declaring our initial function:
@knight
def sayYourName(firstName, lastName):
	return f"{firstName} {lastName}"

#	That did the same thing as the previous approach, except:
# 		- it looks a bit prettier
# 		- it doesn't create an extra throwaway function name

# Now let's see the results:
yourName = sayYourName("Jon", "Arbuckle")
print(f"Your name is {yourName}.")

# As expected, the output is just the same as the previous method we used.

print('\n')
########################## DECORATOR WITH ARGUMENTS ###########################
#
# To do this, we're going to need to make a function that RETURNS a decorator.
# This means we're making:
#   a function
#	   which makes a decorator function
#		   which makes a wrapper function
#				which runs a function.
# We've added one more function layer!

def decoratorMaker(htmlTag):
	def decoratingFunction(myFunction):
		@wraps(myFunction)
		def wrapper(*args, **kwargs):
			result = myFunction(*args, **kwargs)
			return f'<{htmlTag}>{result}</{htmlTag}>'
		return wrapper
	return decoratingFunction

applyTag = decoratorMaker # alias is unnecessary, just helps conceptualize

@applyTag("b")
@applyTag("i")
def bodyText(text):
	return text

print( bodyText("Heyo!") )

# We can see that the decorator was used to add 2 HTML tags around the text.

print('\n')
############################# SOME NOTES ######################################
#
#	1. The order that multiple decorators are applied can matter.
#	
#   2. Each decorator adds an additional function call to calling a function;
# 	   consider that for both your stack and your speed.
#


####################### SOME PRACTICAL EXAMPLES ###############################

# only applies the decorators if we're testing
TEST_MODE = True

# a decorator that outputs time spent executing its function
def testSpeed(myFunction):
	if not TEST_MODE:
		return myFunction

	import time
	@wraps(myFunction)
	def wrapper(*args, **kwargs):
		timeBeforeRun = time.process_time_ns()
		result = myFunction(*args, **kwargs)
		timeElapsed = time.process_time_ns() - timeBeforeRun
		print(f"{myFunction.__name__} took {timeElapsed} nanoseconds.")
		return result
	return wrapper


# a decorator that tracks how many times a function has been called
def countCalls(myFunction):
	if not TEST_MODE:
		return myFunction

	@wraps(myFunction)
	def wrapper(*args, **kwargs):
		wrapper.count = wrapper.count + 1
		result = myFunction(*args, **kwargs)
		print(f"{myFunction.__name__} called {wrapper.count} time(s) total.")
		return result
	wrapper.count = 0
	return wrapper


@testSpeed
@countCalls
def countToTenMillion():
	for i in range(0, 10000000):
		pass
	print("Finished counting!")

countToTenMillion()
print()
countToTenMillion()
print()
countToTenMillion()

# For more thorough explanations:
# https://stackoverflow.com/questions/739654/how-do-i-make-function-decorators-and-chain-them-together