Repository navigation
Differentiate decorator and decorator factory in docs #59679
Description
| BPO | 15474 |
|---|---|
| Nosy | @freddrake, @rhettinger, @ncoghlan, @ezio-melotti, @merwok, @cjerdonek, @andresdelfino, @Windsooon, @dorosch |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2020-02-27.01:07:04.238>
created_at = <Date 2012-07-27.19:10:07.128>
labels = ['easy', '3.7', '3.8', '3.9', 'type-feature', 'docs']
title = 'Differentiate decorator and decorator factory in docs'
updated_at = <Date 2020-02-27.01:07:04.232>
user = 'https://github.com/merwok'bugs.python.org fields:
activity = <Date 2020-02-27.01:07:04.232>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-02-27.01:07:04.238>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2012-07-27.19:10:07.128>
creator = 'eric.araujo'
dependencies = []
files = []
hgrepos = []
issue_num = 15474
keywords = ['easy']
message_count = 13.0
messages = ['166600', '176138', '176149', '319882', '319884', '319885', '344512', '344539', '344644', '344653', '362568', '362758', '362760']
nosy_count = 10.0
nosy_names = ['fdrake', 'rhettinger', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'chris.jerdonek', 'docs@python', 'adelfino', 'Windson Yang', 'dorosch']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15474'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']
Activity
merwok commentedon Jul 27, 2012
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.)
ezio-melotti commentedon Nov 22, 2012
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:
Not sure if it's necessary to include the first example though.
ncoghlan commentedon Nov 23, 2012
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.
andresdelfino commentedon Jun 18, 2018
If deemed appropriate, I can take the task of writing a HOWTO for decorators/decorators factories.
freddrake commentedon Jun 18, 2018
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.
andresdelfino commentedon Jun 18, 2018
Alright! :D Yes, your help will definitely come in handy, thanks!
Windsooon commentedon Jun 4, 2019
Hi, Andrés Delfino. Are you still working on it?
andresdelfino commentedon Jun 4, 2019
Hi Windson Yang! Yes, I'm still working on it. I'll have it ready by the end of June.
ezio-melotti commentedon Jun 4, 2019
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
https://www.pycon.it/media/conference/slides/understanding-decorators.pdf
Feel free to take from it whatever you need :)
andresdelfino commentedon Jun 4, 2019
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:
https://github.com/andresdelfino/cpython/tree/decorators-howto
Fred was very helpful with his insight :)
dorosch commentedon Feb 24, 2020
Hi, Andrés Delfino. Are you still working on it? I could help with this issues.
andresdelfino commentedon Feb 27, 2020
Hi, no I'm no longer working on this.
rhettinger commentedon Feb 27, 2020
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.