Evaluation order of decorator expressions and function / class defs is wrongly implied.

Comienza con las secciones 6.3.4, 8.7 y 8.8 de la referencia del lenguaje mencionadas en el issue y, a continuación, compara los ejemplos de decoradores con la salida de dis.dis proporcionada. Actualiza la redacción y los ejemplos equivalentes para indicar correctamente el orden de evaluación, y verifica que el texto revisado cubra tanto los decoradores de funciones como los de clases.

Documentation

The documentation on calls (6.3.4) says

The primary must evaluate to a callable object (user-defined functions, built-in functions, methods of built-in objects, class objects, methods of class instances, and all objects having a call() method are callable). All argument expressions are evaluated before the call is attempted.

What is missing is that the callable primary is evaluated before the arguments are. This is important because evaluating the primary could alter things that are used in the arguments.

For example:
'''
dis.dis('x(1)(y(2)(f+g))')
0 LOAD_NAME 0 (x)
2 LOAD_CONST 0 (1)
4 CALL_FUNCTION 1
6 LOAD_NAME 1 (y)
8 LOAD_CONST 1 (2)
10 CALL_FUNCTION 1
12 LOAD_NAME 2 (f)
14 LOAD_NAME 3 (g)
16 BINARY_ADD
18 CALL_FUNCTION 1
20 CALL_FUNCTION 1
22 RETURN_VALUE
'''
You can see that x(1) is evaluated first, then y(2), then f+g, then the two function calls.
EDIT: Not an issue. (4.16) makes this clear. Thanks to comment from @pochmann below. However, (4.3.4) could still be amended to make this more clear.

In the case of function decorators, section (8.7) says

For example, the following code
@ f1(arg)
@ f2
def func(): pass
is roughly equivalent to
def func(): pass
func = f1(arg)(f2(func))
except that the original function is not temporarily bound to the name func.

In the case of class decorators, section (8.8) has a similar example.

These imply that the function / class def is evaluated first, then the decorator expressions.
The truth, however, is that the decorators are evaluated before the function / class def.

Example:
>>> dis.dis('''
... @ x(1)
... @ y(2)
... class C: pass''')
2 0 LOAD_NAME 0 (x)
2 LOAD_CONST 0 (1)
4 CALL_FUNCTION 1

3 6 LOAD_NAME 1 (y)
8 LOAD_CONST 1 (2)
10 CALL_FUNCTION 1

4 12 LOAD_BUILD_CLASS
14 LOAD_CONST 2 (<code object C ...)
16 LOAD_CONST 3 ('C')
18 MAKE_FUNCTION 0
20 LOAD_CONST 3 ('C')
22 CALL_FUNCTION 2
24 CALL_FUNCTION 1
26 CALL_FUNCTION 1
28 STORE_NAME 2 (C)
30 LOAD_CONST 4 (None)
32 RETURN_VALUE
So it is equivalent to

_1 = x(1)
_2 = y(2)
class _3: pass
C = _1(_2(_3))

except for the bindings to _1, _2, and _3.

Suggestions

Change (6.3.4) to read:

First, the primary is evaluated, then all argument expressions are evaluated, before the call is attempted.

Change (8.7) to read:

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. They are evaluated, in top to bottom order, before the function is defined. 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 nested fashion. For example, the following code

@ f1(arg)
@ f2
def func(): pass

is roughly equivalent to

_dec1 = f1(arg)
_dec2 = f2
def _func(): pass
func = _dec1(_dec2(_func))

except that the names _dec1, _dec2 and _func are not bound.

Make a similar change to the example in section (8.8) for class decorators.

@ f1(arg)
@ f2
class Foo: pass

is roughly equivalent to

_dec1 = f1(arg)
_dec2 = f2
class _Foo: pass
Foo = _dec1(_dec2(_Foo))

except that the names _dec1, _dec2 and _Foo are not bound.