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

先從 issue 中提到的語言參考章節 6.3.4、8.7 和 8.8 開始，然後將裝飾器範例與提供的 dis.dis 輸出進行比較。更新措辭和等效範例，以準確說明求值順序，並確認修訂後的文字涵蓋函式裝飾器和類別裝飾器。

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.