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

Open
#96,329 2 comments 0 reactions 0 assignees View on GitHub

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

docs

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from python/cpython

All issues in python/cpython

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.