Evaluation order of decorator expressions and function / class defs is wrongly implied.
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 52/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Start with the language reference sections 6.3.4, 8.7, and 8.8 named in the issue, then compare the decorator examples with the provided dis.dis output. Update the wording and equivalent examples to state the evaluation order accurately, and verify that the revised text covers both function and class decorators.
Written by the indexing model from the issue text.
Description
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.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 558
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from python/cpython
-
docs pending
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
stdlib type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
stdlib type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
build type-bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
stdlib topic-email type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
qgis/QGIS-Documentation#11275 ·
-
bug priority:normal ready-for-dev
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
OpenHands/extensions#626 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
CSCfi/sd-search-api#39 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
StevenBlack/hosts#3255 ·