Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Preview
Start a free Courses trial
to watch this video
Sometimes you can just write a function or method or class and be done with it. But sometimes you find that you need to wrap your functions or methods or classes in some sort of new behavior. And since you're a good programmer, you don't want to change every function in the same way over and over again. That's not DRY or a good use of your time! Well, when that happens, you just might need a decorator.
For more about logging: Write Better Python and the logging documentation.
A great blog post about using functools.wraps.
There is no functional difference, as far as Python itself or the interpreter is concerned, between applying a decorator directly or with the @ symbol.
Examples
Nested function:
def outer():
number = 5
def inner():
print(number)
inner()
outer() # prints 5
First-class functions
def apply(func, x, y):
return func(x, y)
def add(a, b):
return a + b
print(apply(add, 5, 5)) # prints 10
Closures
def close():
x = 5
def inner():
print(x)
return inner
closure = close() # closure is actually a pointer to inner()
closure() # prints 5
Decorator
def logme(func):
import logging # because we don't want to require users to import it
logging.basicConfig(level=logging.DEBUG)
def inner():
logging.debug("Called {}".format(func.__name__)
return func()
return inner
@logme
def say_hello():
print("Hello there!")
say_hello() # logs the call and then prints "Hello there!"
Related Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign upRelated Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign up
[MUSIC]
0:00
Sometimes you just want to write
a function, or a method, or a class and
0:04
be done with it.
0:07
But sometimes you need to wrap your
functions, or methods, or classes
0:09
in some new, sort of, behavior, and since
you're a good programmer, you don't want
0:12
to change every function in the same
way over and over again that's not dry.
0:16
Well when that happens
you need a decorator.
0:21
Instead of picking out a new color palette
for your apartment, Python Decorators let
0:24
you wrap your existing functions, classes,
etcetera with another Python cullible.
0:27
While this subject is often pretty
confusing both to understand and
0:31
to explain, once you get a grasp on
decorators they can be an amazingly useful
0:35
part of your Python workflow.
0:39
Decorators are one of those things
that are really really useful, but
0:42
sometimes it's hard to give a concrete
example or a reason for creating one.
0:46
For example, if you have a property that
takes a long time to calculate, you might
0:52
want a caching or memoization decorator
to store the value of that property.
0:55
There are other ways to solve that
problem, but a decorator is clean,
1:00
small, and they're easy to add or remove.
1:04
The reason I say that it's hard
to give a concrete example or
1:06
a reason for, is because of that.
1:09
Python's somewhat flexible, so
I can't always be like, oh yeah,
1:11
this is best solved by a decorator.
1:15
It's kind of case by case basis.
1:17
So, let's work our way
toward writing them and
1:19
kind of understanding how they work and
why we'd wanna use them.
1:22
They're amazing useful, though, I promise.
1:24
So the first thing that we have to
understand, on our way to creating
1:27
decorators, is that we can nest functions
inside of other functions in Python.
1:30
I've got a file started here called
dec.py that's gonna hold all the code for
1:36
this workshop.
1:39
So, let's create a function
that's called outer.
1:40
And you know what, that's two spaces,
that should be four spaces.
1:46
There we go.
1:52
And inside here, I'm gonna say that I have
a variable called number that equals five.
1:53
And then inside here I'm gonna have
a new function named inner, and
1:58
inner is going to print number.
2:03
And then out here, back at the same level,
I'm going to call inner.
2:07
So all deck top pie has in it
is a function called outer.
2:12
Inside outer, we define a variable.
2:16
And we define a function called inner, and
inner prints number from outer's scope.
2:19
And then outer calls inner so
that the print happens.
2:24
All right, let's give that a try.
2:31
So we're gonna come down here.
2:33
We're gonna go into Python.
2:35
And you'll say from deck import outer,
we'll make this a little bigger,
2:37
and then we're gonna call outer,
and it prints five.
2:42
Now, outer doesn't ever print, but
outer calls inner and inner prints five.
2:46
Okay, so
functions can live in other functions and
2:51
they have access to the scope of
the function that they live in.
2:53
All right, we're gonna get out
of there because we're going to
2:59
have to import it again.
3:00
Let's go back up here.
3:02
Another part that's important about
all of this process is that functions
3:03
are known as first class citizens or
first class objects.
3:08
What this means is that
functions are objects.
3:13
We can treat them as such.
3:17
We can put attributes on them or whatever.
3:18
But that also means that
they can be passed around
3:21
from one function to another or you can
pass a function to a class or vice versa.
3:24
So what does that mean for us?
3:29
Well let's do this,
let's add a new function called apply.
3:33
And apply's going to take a func, and
3:37
it's going to take an x and
it's going to take a y.
3:39
And all it's going to do is return
func with x and y being called.
3:43
Okay.
3:50
So doesn't really do much,
3:52
it just returns the output of func
when you supply func, x, and y.
3:54
Okay, let's add a couple
other functions here.
3:59
Let's do add.
4:01
And add is going to take an x and
a y, and it's going to return x + y.
4:04
And let's do a sub,
which is going to take an x and
4:09
a y, and it's going to return x- y.
4:14
Okay, so
those three functions are pretty simple.
4:19
Nothing really weird going on there.
4:22
So let's print apply where
we supply at add, and
4:25
then 5 and 5, and let's print apply
where we give it sub and 2 and 8.
4:31
Okay, so now let's just run our dec.py.
4:41
We get back 10 and we get back -6.
4:48
Those are the math problems
that we gave it so
4:50
what we know is that apply applied
our arguments to our functions.
4:54
So, that's kinda cool.
4:59
We can pass a function into a function,
and
5:00
then that function can call
the function that was passed into it.
5:04
All,right, if you're still with me,
let's do one more step here.
5:06
And this is one of the more
important concepts, and
5:11
it's one that a lot of people
don't deal with in Python.
5:15
They deal with that a lot in JavaScript.
5:19
But it's in Python and it's really cool.
5:22
It's called a closure.
5:24
A closure, effectively,
is a function that has a predefined scope.
5:25
When we define an inner or enclosed
function, which we did right here,
5:29
then we're also defining the scope and
the environment for that function.
5:35
So this is the scope.
5:39
That's what exists for inner.
5:40
Inner only has access to number.
5:41
Now if we had declared
variables out here above outer,
5:43
inner would have access to them as well.
5:46
But inner always has
access to this number.
5:48
So let's make a closure.
5:51
This is where they're
a little bit different.
5:55
What we're doing here is here we're
turning or we're calling inner.
5:57
Here we're returning whatever
happens when we call func.
6:00
So instead of doing either one of those,
let's return what would be func.
6:05
Okay, so I'm gonna take off these two
print statements, and here we go.
6:11
So let's write def close for our closure,
6:17
and we say that x is 5, and
then we're gonna define inner.
6:20
And we're gonna print(x).
6:27
And then we're going to return inner.
6:29
Now, we didn't return what
happens when we call inner.
6:35
We just returned inner,
the function inner.
6:39
So let's try this out.
6:42
So let's add a new line down here.
6:45
And we're gonna say closure equals close.
6:48
So we've got closure equals close,
and now let's call closure.
6:53
Can we do that, can we call closure?
6:57
We can and we get 5.
7:02
So what happens?
7:03
Well, so what happened is that when
we said closure equals close, and
7:06
we called close, close works its way
through, and it returns at the end, right?
7:10
It returns inner.
7:15
So it returns a pointer to
this inner function, and
7:17
this inner function has
a scope that's defined.
7:21
And what enter does it interprints X.
7:24
Well it knows, okay, hey, x is five.
7:26
So when you call me, I'm gonna print 5.
7:28
So closure is equal to the calling
of close, which returns inner.
7:31
And when we call closure,
because closure is effectively just inner.
7:37
When we call closure it prints x and
x is 5.
7:41
So that's pretty neat.
7:44
It's a lot to kind of process and
think through but it's pretty neat.
7:46
Okay.
7:50
But let's go a step further on all this
because you need to see what makes
7:51
the scoping really neat.
7:54
So, again,
we're going to get rid of those two lines.
7:57
We're gonna make a new one here.
8:01
We're gonna say add_to_five and
it's gonna take a num.
8:02
And the in def inner we're
going to say print(num+ 5).
8:06
And then, again,
we're going to return inner.
8:13
Not the calling of inner, just inner.
8:16
Okay.
8:19
So 15 equals add to five and
8:19
we're gonna pass at ten,
and that's called 15.
8:23
All right, so again,
we're going to do that, and we've got 15.
8:27
Now that's kind of cool.
8:33
We never passed num into
the enter function, so
8:35
it's there because it's in the scope.
8:39
Right.
8:41
So you might be starting to see
how this can work out where
8:42
if we call a function or
we take a function and
8:45
we have a function inside that does
something to that function then
8:48
whatever will return we've got this
new thing that's floating around.
8:51
Right.
8:56
We could define a state
inside of add to five,
8:57
that would influence the inner function,
we could do all this stuff.
8:59
Effectively, this gives
us private variables.
9:01
Private variables are handy for
9:04
a lot of different reasons
that we're not gonna go into.
9:05
Okay, so, ultimately, though,
we're here about decorators and
9:08
how does this all apply to decorators?
9:11
Okay, stick with me here for a minute.
9:14
Decorators are really just functions
that accept functions as arguments.
9:17
And they have an inner function
that performs some action
9:22
before returning the accepted function.
9:25
And, of course, the outer function,
9:28
the decorator,
really returns that inner function.
9:29
So it's a function that
returns a function, which,
9:33
in turn, returns a function that was
accepted by the outermost function.
9:35
That's a lot to say.
9:40
We should build one.
9:42
And of course I would hope it goes
without saying the inner function really
9:43
doesn't have to return
the function that was passed in.
9:46
You can just do whatever you want.
9:48
It's code.
And it's your code.
9:50
Do what you want in your code.
9:52
Okay.
Let's build one.
9:54
What we're gonna build
is a decorator that,
9:55
when we get to the end of all this Will
let us do a log message with Python's
9:58
logging module every time the function
that's decorated is called.
10:03
And it's going to log
the function that was called and
10:08
what arguments that
function was called with.
10:11
We've got a ways to go,
so let's just keep going.
10:14
We'd use this to find
functions that are called in
10:18
just an abnormal amount of times,
10:21
like oh my, you've called this function
15 times can you only call it five?
10:23
Or, we could use it to track down like
when a problematic variables passed in or
10:28
value is passed in.
10:32
Now, we could all do this with a regular
function, and we would just add
10:34
that call into every function that we want
to log, but that means that our functions
10:37
now have this like debugging and
secretarial work inside of them.
10:42
We have to remember to take it out.
10:48
It's easier to find and delete a bunch of
lines that all start with the decorative
10:50
symbol, the at symbol, than it is define
all the calls to logging.debug or
10:54
whatever custom function that we wrote.
10:59
And it's a separation of concerns.
11:02
Like I mentioned, you'd have to add the
secretarial logic into all your functions,
11:03
and now your functions
are doing two things.
11:07
They're logging themselves and they're
doing whatever work you want them to do.
11:08
While that's not a big deal,
it's not clean.
11:14
And it's not really pythonic.
11:18
Your functions should do one thing.
11:19
Also, another good point,
if we wanna change how this works,
11:21
we'll just go change our decorator.
11:24
We don't have to change all
of the functions and yeah,
11:26
if they're calling a function and
then we just changed that one function.
11:29
But still it's cleaner.
11:31
Okay.
11:32
Let's get started.
11:33
That's enough preaching about it for
right now.
11:34
So we're gonna make a new
function called logme.
11:36
And logme is going to take a func.
11:39
Sometimes you'll see this abbreviated,
11:42
often you'll see this abbreviated
as just f, but I like func.
11:44
So inside here we want to import logging.
11:47
And we're gonna do
logging.basicConfig(level=logging.DEBUG).
11:50
Because remember,
we want to catch all of our log messages.
11:58
If you don't know about logging,
you should go watch
12:01
the Write Better Python course,
which has a whole thing about logging.
12:04
Okay, so, we've imported logging,
logging.basicConfig.
12:09
The reason we imported logging
inside of this function
12:12
is because we want logging
to be available, but
12:15
we don't want people to have to import
logging just to use our decorator.
12:17
So we're gonna take care of that for
them, so def inner() and
12:20
we're gonna do logging.debug and
we're gonna say "Called
12:26
Something and
we're gonna format with that func.name.
12:31
Close our parens there, and
then we're going to return func and
12:39
then we're going to return inner.
12:44
So, how do we use this?
12:47
That's a very good question.
12:51
What we're going to do, is we're
going to go over here to our shell,
12:52
and we're going to play with this.
12:57
Okay, so from deck import logme, and
we're going to write a function,
12:59
and we're just going to say print_2.
13:05
Doesn't take any arguments.
13:10
And it's just going to print two.
13:11
Okay.
So if we just call print two,
13:18
prints out two.
13:21
All right, cool.
13:21
Easy.
13:22
Now how do we decorate this?
13:23
Because this isn't decorated.
13:24
Well let's do that the explicit way for
right now.
13:25
So we'll say print_2
equals logme of print_2.
13:28
And now if we call print 2
13:32
we get this debug route called print 2 and
then we get our 2 as well.
13:37
Because eventually we
call the actual function.
13:42
We actually call it and
return what comes out of it.
13:45
But we have this logging
message that happens first.
13:48
Cool.
We got our first logging message.
13:51
So we can also use the at symbol
when we want to use a decorator.
13:52
This is a bit of syntactic sugar that
makes Python look a little nicer.
13:57
Also I think it's kind of
nice because the @ kind
14:02
of looks like something
being wrapped around.
14:06
Yeah.
Kind of works.
14:08
Okay.
14:09
So let's redefine our print to.
14:10
This time we're going to
decorate it the normal way.
14:12
So we do @logme.
14:16
And then we do def print.
14:17
Let's do def print_4 this time.
14:20
We're fancy.
14:22
And it's going to print four.
14:24
All right.
14:27
So now if I call print_4, we got our
logging message, and we got our 4.
14:29
Still works the exact same way, symbol's
a little nicer than having to redefine
14:34
the function and re-assign its name, and
then remembering that you've done that.
14:39
It's not always the easiest thing to
remember, so that's a little nicer.
14:44
Okay, so let's get out of here.
14:47
And do a clear on that cuz I wanna
do some more work on logme, okay.
14:51
So far, we've only handled a function
that didn't take arguments.
14:56
If you tried this, our previous steps,
on a function that took an argument,
14:59
like maybe it was just print a number and
you were to pass in a number,
15:02
print out that number,
you would've gotten an error.
15:07
You would've gotten warnings about
it doesn't take any arguments.
15:09
That's true.
15:13
So let's not do that.
15:14
Let's make it to where we can get
arguments into our functions.
15:17
Okay, so how do we handle decorating
a function that takes arguments?
15:21
We have to change our decorator
to accept the arguments.
15:25
This construct is a little bit weird.
15:28
But once you learn it,
15:30
which you should be able to do now,
then you'll have it and you'll be fine.
15:33
So we're still gonna take
func out here for logme.
15:38
But then, in inner we're
going to take two arguments.
15:42
And we're gonna take args and kwargs.
15:45
Just like we normally do.
15:48
Okay.
15:50
So we take args and kwargs.
15:50
Now I wanna change this.
15:51
We've got called blah blah blah.
15:53
Let's do args and kwargs and then let's
bring our format to the next line.
15:55
And it's going to print out args and
kwargs.
16:04
And then in the end,
we need to return func.
16:07
And we need to supply func with args and
quargs.
16:09
Now here we do them without stars.
16:14
And we do them here without stars.
16:17
But we do them here with stars.
16:19
The reason is we want to actually print
out the tupple and the dictionary here.
16:21
And here we want to use the tupple and
dictionary as arguments.
16:26
That's it!
16:29
What's kind of strange is that our
decorator still only take the function,
16:30
and the inner function takes the args and
coargs.
16:33
That's why you've got this separation,
right?
16:36
Okay, so let's test this one out.
16:39
So again I'm gonna pull this way up,
do Python from dec import logme.
16:43
All right, logme.
16:50
sub(x, y}.
16:54
Let's add in switch=False.
16:57
All right.
17:01
And we're gonna say return x- y
17:03
if not switch else y- x.
17:10
So simple function just has a thing for
17:14
if we want to swap the order
of the subtraction.
17:16
Okay, so let's do sub(5, 2) and
17:21
we get five two of the args no quargs,
and the answer is three.
17:25
Let's do sub (5, 2,
switch=True), and we get args 5,
17:29
2 quargs switch is true, and
we get negative -3 as the answer.
17:35
That works like I expected, yeah?
17:41
Okay, cool.
17:43
Again, going to exit this and clear.
17:44
And that's fine because we're going
to reimport decorator anyway.
17:47
All right.
17:50
There's a bit of housekeeping
that we should do,
17:52
though, as good Python programmers.
17:54
Actually, you know what,
let's go back in here.
17:57
Python from dec import Logme.
18:01
Logme def sub (x y).
18:06
Return x-y.
18:13
Okay, so if you're used to kind of
playing around debugging Python,
18:14
you've no doubt discovered
that you can do this.
18:19
And we even did it in our decorator.
18:22
Sub.name.
18:23
Now this should tell us sub,
because sub is the name of our function.
18:24
But it tells us inner,
18:28
because if we look at our decorator,
inner is what comes back out.
18:29
So when we decorated it,
we actually got inner.
18:34
We didn't get sub.
18:37
That's about the most awesome thing ever,
right?
18:39
The name for sub isn't inner,
it should be sub.
18:42
What if sub had a doc string, right?
18:44
If we were to do this again,
def sub (x, y),
18:46
and we were to say, Returns
the difference between two numbers.
18:52
And then we'll return x- y.
19:03
Okay, so now if I do help(sub), oh,
19:05
I don't get doc strings I get inner.
19:09
And if I do sub.doc,
I don't get any doc string at all
19:15
because inner up here
doesn't have a doc string.
19:20
And we've replaced sub with inner.
19:26
Okay, so that's kind of annoying.
19:28
That's kind of, that's not good Python.
19:31
You shouldn't do that.
19:34
So how do we fix this?
19:36
Well there's actually two
ways we can fix this.
19:38
The first way we can fix this
is we can change our stuff here.
19:41
So let's do that.
19:44
Let's come down here and
we're gonna change inner.doc
19:45
to be equal to func.__doc__, and
we're going to change inner.__name__
19:51
to be equal to func.__name__.
19:58
So that if we were to do
our stuff all over again,
20:03
the sub and everything, we'd get the name
and the doc and everything like that.
20:08
Cool, that's good, that's great.
20:11
There's an easier way, though,
thanks to Python's func tools module.
20:13
So let's go ahead and
import that up here at the top, and
20:17
we're gonna say from
func tools import raps.
20:21
There's actually a lot of really
nice stuff inside func tools, so
20:26
I suggest checking out the package.
20:29
Okay, so we've imported wraps.
20:32
Now, functools.wraps is itself,
a decorator.
20:33
So, it's kind of cool though, it handles
doing all of this assigning stuff for you.
20:38
There's doc, there's name, and there's two
or three others that we didn't talk about
20:42
that we haven't ever looked at,
that this thing also handles.
20:46
We'd have to override all of those and
20:50
we'd have to do it every
time we made a decorator.
20:51
And if we're making a lot of decorators,
that can be really annoying.
20:52
So let's not do that.
20:56
Instead, let's take those lines out.
20:57
And we're just gonna go up here.
20:59
We're gonna say raps(func}.
21:01
So this decorator, which we're not
gonna cover how to do this, but
21:05
this decorator takes an argument.
21:08
You can do that.
21:10
Decorators can take arguments that
are then applied to the functions.
21:11
Wraps will handle assigning
all the content on inner
21:15
to all the content on
funk when funk comes in.
21:19
Okay?
21:22
We don't have to change anything else.
21:23
Everything else is still perfectly fine.
21:25
So let's just add, so
I don't have to write this again,
21:27
Logme Sub(x,
21:32
y) returns the difference
between two numbers.
21:39
Return x- y.
21:45
Okay, cool.
21:51
So now, let's go down here.
21:52
Python from dec import sub.
21:56
Sub.name, sub, help(sub).
22:00
Hey, returns the difference
between two numbers.
22:08
Cool.
22:13
So, and if we do sub( 5 and 2),
we still get our debug call.
22:15
Sometimes, as I mentioned before,
22:21
it's a little hard to see why
you'd create a decorator.
22:22
I'm gonna link to a cookbook of
decorators in the teacher's notes for
22:25
some great examples of places
where decorators come in handy.
22:28
Generally though, watch for
22:31
places where you repeat a lot
of ancillary functionality.
22:32
Places where your bookkeeping
are great places for decorators.
22:35
You may go your whole career without
ever creating a new decorator.
22:39
That's okay.
22:42
But now, you'll be able to look at
built-in decorators like property and
22:43
class method, or decorators from Flask and
Jango like app.route or
22:47
login required, and you'll be able to
understand what's going on inside of them.
22:51
Decorators are a really common
part of many Python libraries.
22:55
We've already used several
here at Treehouse.
22:59
While you may not create many of them
yourself, it's good to know how they work,
23:01
how they're constructed, and scenarios
were a decorator is a perfect solution.
23:05
You need to sign up for Treehouse in order to download course files.
Sign upYou need to sign up for Treehouse in order to set up Workspace
Sign up