Missing documentation for decorators

[tomerv]

BPO	36913
Nosy	@matrixise, @JulienPalard, @mblahay, @tomerv

^{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 = None
created_at = <Date 2019-05-14.07:35:28.614>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Missing documentation for decorators'
updated_at = <Date 2019-05-27.03:15:43.677>
user = 'https://github.com/tomerv'

bugs.python.org fields:

activity = <Date 2019-05-27.03:15:43.677>
actor = 'mblahay'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-05-14.07:35:28.614>
creator = 'tomerv'
dependencies = []
files = []
hgrepos = []
issue_num = 36913
keywords = []
message_count = 5.0
messages = ['342435', '342436', '342437', '342438', '343604']
nosy_count = 5.0
nosy_names = ['docs@python', 'matrixise', 'mdk', 'mblahay', 'tomerv']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue36913'
versions = ['Python 3.7', 'Python 3.8']

Linked PRs

• gh-81094: Refer to PEP 318 in compound_statements.rst #113588
• [3.12] gh-81094: Refer to PEP 318 in compound_statements.rst (GH-113588) #113643
• [3.11] gh-81094: Refer to PEP 318 in compound_statements.rst (GH-113588) #113644

[tomerv]

The documentation for decorators (for methods and classes) is pretty lacking.

Searching for "decorator" ( https://docs.python.org/3/search.html?q=decorator ) brings up a lot of libraries that use decorators, but no documentation explaining what they are and how they work. The documentation should have a dedicated page for explaining decorators, and this should be the 1st search result.

--

In the meantime, then search should give as a 1st result a link to the definition of decorator in the glossary: https://docs.python.org/3.7/glossary.html#glossary

Actually, it seems that there is no way to directly link to a paragraph in the glossary - so that should be added as well.

In general, it would be nice if a search for some term X would show as a 1st result the definition of X in the glossary (if it exists there).

Thanks!

[matrixise]

Hi,

Thank you for your feedback.

In fact, there is a limitation with the current search engine of Sphinx (because we use it for the documentation). For example, if you try to find the meaning of "for", for us it's a keyword but for the search engine, it will try to find all the sections containing "for" (formatter, platform, argparse.ArgumentParser.format_help, etc...).

For that, we could open an issue on the repository of Sphinx.

Now, about the decorators.

In the definition of a function, we explain the call of a decorator, See the grammar. https://docs.python.org/3/reference/compound_stmts.html#function-definitions

"""
A function definition may be wrapped by one or more decorator expressions. Decorator expressions are evaluated when the function is defined, in the scope that contains the function definition. The result must be a callable, which is invoked with the function object as the only argument. The returned value is bound to the function name instead of the function object. Multiple decorators are applied in a nested fashion. For example, the following code
"""

But because it's a specification of the language which has been described with 2 PEPs you can read it on the PEP Index page.

Function: https://www.python.org/dev/peps/pep-0318/
-> Introduced in 2.4 https://docs.python.org/3/whatsnew/2.4.html

Class: https://www.python.org/dev/peps/pep-3129/
-> Introduced in 3.0

Now, I suggest one thing, add a link to the PEPs in this section https://docs.python.org/3/reference/compound_stmts.html#function-definitions

[tomerv]

Thank you for the quick response.

Are PEPs considered de-facto documentation for language features? For example, string formatting was described in PEP-3101, but still has sections in the documentation dedicated to it. I believe that decorators should get a similar treatment :-)

I also think that describing decorators as part of the grammar definition is lacking. Why is there a whole chapter for Errors and Exceptions and it's not only discussed under the grammar definition for raise?

Decorators are a pretty unique (and cool!) feature of Python, and therefore new learners of the language need a better reference for learning about them.

I realize that this is a big request, as you would need some expert to write this documentation.

[matrixise]

Hi Tomer,

Thank you for the quick response.
Welcome

Are PEPs considered de-facto documentation for language features? For
example, string formatting was described in PEP-3101, but still has
sections in the documentation dedicated to it. I believe that
decorators should get a similar treatment :-)
Good catch for the string formatting.

For the decorator, it's different because a decorator is mainly a
function taking a function and returning a function.

Example you can write this decorator:

def my_decorator(func):
 return func

def my_awesome_function(*args, **kwargs):
 print(args)
 print(kwargs)

 return 42

my_awesome_function = my_decorator(my_awesome_function)

in this case, we don't need to document the decorator.

for the '@' syntax, it's described in the doc but it's syntactic sugar
for the decorator. I don't think we need to add a big description for
that, because everything is described in the PEP.

I would like to have the opinion of the other core-dev. @sizeof?

I also think that describing decorators as part of the grammar
definition is lacking. Why is there a whole chapter for Errors and
Exceptions and it's not only discussed under the grammar definition for
raise?

Decorators are a pretty unique (and cool!) feature of Python, and
therefore new learners of the language need a better reference for
learning about them.

I realize that this is a big request, as you would need some expert to
write this documentation.
You can open a PR ;-)

[mblahay]

The PEP is not the first place I go looking for information on Python topics, just my two cents.

[slateny]

It seems that the current search https://docs.python.org/3/search.html?q=decorator does point towards the glossary as the first search result.

The Class Definitions section does link PEP 3129 and also references PEP 318 so everything's technically in the doc, but as mentioned PEP 318 can also go under the box at the end of Function definitions for clarity.

[Rasputin2]

Hello, I am a first time contributor. If this is something that still needs assistance, I could start by just adding a description of decorators in the docs, see if you accept that, and then start drafting entries for each decorator one by one. This would be a good learning experience for me,. Not sure if this is still something you guys believed needed to be worked on or not.

[hugovk]

Hello! I think all that's left is:

PEP 318 can also go under the box at the end of Function definitions for clarity.

Would you like to open a PR?