classification
Title: Dis module - documentation of MAKE_FUNCTION
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: arno, docs@python, python-dev, sandro.tosi, terry.reedy
Priority: normal Keywords:

Created on 2011-09-21 22:02 by arno, last changed 2013-10-12 16:40 by python-dev. This issue is now closed.

Messages (9)
msg144393 - (view) Author: Arnaud Delobelle (arno) Date: 2011-09-21 22:02
The description of the opcode MAKE_FUNCTION in the dis module document is out of date.  It still describes the 2.X version of the opcode:

"""
MAKE_FUNCTION(argc)
Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc default parameters, which are found below TOS.
"""

According to http://hg.python.org/cpython/file/default/Python/ceval.c#l2684:


 2684             int posdefaults = oparg & 0xff;
 2685             int kwdefaults = (oparg>>8) & 0xff;
 2686             int num_annotations = (oparg >> 16) & 0x7fff;

So the documentation should read something like

"""
MAKE_FUNCTION(argc)
Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc & 0xFF positional default parameters, (argc >> 8) & 0xFF keyword only default parameters, and (argc >> 16) & 0x7FFF parameter annotations which are push below TOS in this order. For each keyword only default, the name of the parameter is pushed just below its default value. On top of all the annotations, a tuple is pushed listing the parameter names for these annotations.
"""
msg144394 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-09-21 22:16
Minor edit: in 'which are push below TOS', /push/pushed/.
I understand 'in this order' to mean that positional defaults are pushed first so that they end up on the bottom, whereas annotations are pushed last and end up just under the code object. Correct? (This order makes sense given the structure of function headers.)
msg144395 - (view) Author: Arnaud Delobelle (arno) Date: 2011-09-21 22:21
Yes, you are correct.  Reading this again, I don't think I should have used the word "pushed" as it sounds like the effect of the opcode is to push stuff onto the stack, whereas I was only trying to describe what is on the stack just before the opcode is executed.
msg144402 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-09-22 07:02
Right. This opcode is the end of a sequence of opcodes that sets up the stack in the way expected. Perhaps something like

Pushes a new function object on the stack. From bottom to top, the consumed stack must have have argc & 0xFF positional default parameter objects, (argc >> 8) & 0xFF keyword only name, default parameter object pairs (with name and object in separate positions), (argc >> 16) & 0x7FFF parameter annotations, a tuple listing the parameter names for the annotations, and finally a code object as TOS.
msg144403 - (view) Author: Arnaud Delobelle (arno) Date: 2011-09-22 07:33
This reads a lot better.  Perhaps change 

    (with name and object in separate positions)

to something like

    (with name just below object on the stack)
msg144423 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-09-22 21:51
Agreed
msg150876 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-01-08 16:08
Hi Arnaud,
would you like to provide a patch to update the MAKE_FUNCTION opcode description? That would speed up a bit the fix-up.

Also, I don't have that clear what "For each keyword only default, ..." mean: are those the default values for keyword arguments? something else?

Thanks in advance,
Sandro
msg150902 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-01-08 20:39
"For each keyword only default" is not in my text, but if you are referring to "keyword only name, default parameter object pairs ", yes. Here is a revised suggested wording:

MAKE_FUNCTION(argc)
Pushes a new function object on the stack. From bottom to top, the consumed stack must have have (argc & 0xFF) default argument objects in positional order, ((argc >> 8) & 0xFF) (name, default argument) pairs, with name just below the object on the stack, for keyword-only parameters, ((argc >> 16) & 0x7FFF) parameter annotation objects, a tuple listing the parameter names for the annotations, and finally a code object as TOS.
msg199593 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-12 16:40
New changeset b9ab48c491d5 by Georg Brandl in branch '3.3':
Closes #13026: fix documentation of MAKE_FUNCTION for 3.x.
http://hg.python.org/cpython/rev/b9ab48c491d5
History
Date User Action Args
2013-10-12 16:40:36python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg199593

resolution: fixed
stage: needs patch -> resolved
2012-01-08 20:39:16terry.reedysetmessages: + msg150902
2012-01-08 16:08:41sandro.tosisetversions: + Python 3.2
nosy: + sandro.tosi

messages: + msg150876

stage: needs patch
2011-09-22 21:51:43terry.reedysetmessages: + msg144423
2011-09-22 07:33:51arnosetmessages: + msg144403
2011-09-22 07:02:15terry.reedysetmessages: + msg144402
2011-09-21 22:21:08arnosetmessages: + msg144395
2011-09-21 22:16:07terry.reedysetmessages: + msg144394
2011-09-21 22:02:38arnocreate