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!

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

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.

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 ;-)

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