Title: Differentiate decorator and decorator factory in docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Windson Yang, adelfino, chris.jerdonek, docs@python, dorosch, eric.araujo, ezio.melotti, fdrake, ncoghlan, rhettinger
Priority: normal Keywords: easy

Created on 2012-07-27 19:10 by eric.araujo, last changed 2020-02-27 01:07 by rhettinger. This issue is now closed.

Messages (13)
msg166600 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-27 19:10
Some of the confusion encountered when writing decorators arise from the difference between a decorator (@something) and a decorator factory (@something(args)).  It would help to adopt this clearer terminology in our docs: a decorator takes the decorated function as argument and does its business, a decorator factory takes some arguments and returns a decorator which wraps the decorated function.

(I think it was Nick who suggested this in a recent-ish mailing list thread.)
msg176138 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-22 23:20
The tutorial doesn't seem to mention decorators, do you think this should be covered there?
FWIW while explaining decorators I usually use 3 examples:
 1) a simple decorator that accepts a function, does something, and returns the same function;
 2) a decorator that defines and returns an inner function;
 3) a decorator factory, that defines two nested inner functions

Not sure if it's necessary to include the first example though.
msg176149 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-11-23 02:52
No, using decorators needs to be in the tutorial, but writing your own is a metaprogramming task that's beyond the tutorial's scope.

A HOWTO guide would be appropriate, though.
msg319882 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-18 13:32
If deemed appropriate, I can take the task of writing a HOWTO for decorators/decorators factories.
msg319884 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2018-06-18 13:46
I like Éric's terminology; giving a concrete name to the concept makes it a lot easier to grasp, and this doesn't require inventing any new component terms.

Andrés, if you'd like to tackle this, that's great!  I'd be happy to for you to bounce drafts through me if you like.
msg319885 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2018-06-18 14:16
Alright! :D Yes, your help will definitely come in handy, thanks!
msg344512 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-06-04 01:06
Hi, Andrés Delfino. Are you still working on it?
msg344539 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2019-06-04 10:18
Hi Windson Yang! Yes, I'm still working on it. I'll have it ready by the end of June.
msg344644 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2019-06-04 21:24
If you want some early feedback I believe you can already create a PR and mark it as work-in-progress/don't-merge.

If you need some material you can find the slides of a talk about decorators that I did at
Feel free to take from it whatever you need :)
msg344653 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2019-06-04 22:09
Great! I'll definitely give it a look.

I prefer not to make a PR until everything is in its place. You can check the status though:

Fred was very helpful with his insight :)
msg362568 - (view) Author: Andrei Daraschenka (dorosch) * Date: 2020-02-24 06:11
Hi, Andrés Delfino. Are you still working on it? I could help with this issues.
msg362758 - (view) Author: Andrés Delfino (adelfino) * (Python triager) Date: 2020-02-27 00:37
Hi, no I'm no longer working on this.
msg362760 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-02-27 01:07
Thanks Andrés.  

I'm going to close this one as it has been open for a long time and not attracted interest.  Also, in practice this ambiguity doesn't seem to be an issue and people almost universally refer to anything usable with the @-notation as a decorator.  Further, it has become common for tooling such as @lru_cache and @dataclass to be usable both with and without arguments, so the distinction no longer makes sense in some cases.
Date User Action Args
2020-02-27 01:07:04rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg362760

resolution: out of date
stage: needs patch -> resolved
2020-02-27 00:37:12adelfinosetmessages: + msg362758
2020-02-24 06:11:33doroschsetnosy: + dorosch
messages: + msg362568
2019-06-04 22:09:49adelfinosetmessages: + msg344653
2019-06-04 21:24:11ezio.melottisetmessages: + msg344644
versions: + Python 3.7, Python 3.8, Python 3.9, - Python 2.7, Python 3.2, Python 3.3, Python 3.4
2019-06-04 10:18:41adelfinosetmessages: + msg344539
2019-06-04 01:06:07Windson Yangsetnosy: + Windson Yang
messages: + msg344512
2018-06-18 14:16:06adelfinosetmessages: + msg319885
2018-06-18 13:46:07fdrakesetnosy: + fdrake
messages: + msg319884
2018-06-18 13:32:33adelfinosetnosy: + adelfino
messages: + msg319882
2012-11-23 02:52:13ncoghlansetmessages: + msg176149
2012-11-22 23:20:48ezio.melottisetmessages: + msg176138
2012-11-22 23:06:48ezio.melottisetnosy: + chris.jerdonek
2012-11-09 15:04:15ezio.melottisetversions: + Python 3.4
nosy: + ezio.melotti

keywords: + easy
type: enhancement
stage: needs patch
2012-07-27 19:10:07eric.araujocreate