classification
Title: Documentation of MAKE_FUNCTION/MAKE_CLOSURE_EXTENDED_ARG is misleading
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.2, Python 3.3, Python 3.4, Python 3.5
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, freakboy3742, serhiy.storchaka
Priority: normal Keywords:

Created on 2015-12-11 04:13 by freakboy3742, last changed 2018-03-22 09:19 by serhiy.storchaka. This issue is now closed.

Messages (3)
msg256189 - (view) Author: Russell Keith-Magee (freakboy3742) * Date: 2015-12-11 04:13
Refs Issue16554, Issue13026, Issue14349, and probably others.

The documentation for the interpretation of the argc argument to MAKE_FUNCTION in Doc/library/dis.rst is incorrect. 

As of 13 August 2015, the docs say:

"""
Pushes a new function object on the stack.  From bottom to top, the consumed
stack must consist of:

   * ``argc & 0xFF`` default argument objects in positional order
   * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the 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 (only if there are
     ony annotation objects)
   * the code associated with the function (at TOS1)
   * the :term:`qualified name` of the function (at TOS)
"""

However, this doesn't capture the fact that:

 * if there are annotations, the number of default arguments returned by `argc & 0xFF` must be reduced by `(argc >> 16) & 0x7FFF`

 * The value `(argc >> 16) & 0x7FFF` for the number of annotations *includes* the "extra" entry for the tuple describing which arguments the annotations apply to. This means that `(argc >> 16) & 0x7FFF` will be either 0, or 2+; it can't be 1 (because if you have one annotation, you must also have a tuple describing which arguments is annotated).
msg256632 - (view) Author: Russell Keith-Magee (freakboy3742) * Date: 2015-12-18 01:42
It turns out I wasn't completely correct. As per my second point, the interpretation of annotations needs be clarified, but my first point about default_args including the annotation count is incorrect. 

My error was made because of the documentation for EXTENDED_ARG. The current text implies that you need to combine the argument value of the EXTENDED_ARG opcode with the argument value for the previous opcode. However if you're using dis.Bytecode() to extract bytecodes, that composition is done for you - you can effectively ignore the EXTENDED_ARG opcode.
msg314238 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-03-22 09:19
MAKE_FUNCTION was changed in 3.6, and its documentation was changed accordingly. 3.5 is now in security-only fixes stage.
History
Date User Action Args
2018-03-22 09:19:51serhiy.storchakasetstatus: open -> closed

nosy: + serhiy.storchaka
messages: + msg314238

resolution: out of date
stage: resolved
2015-12-18 01:42:27freakboy3742setmessages: + msg256632
title: Documentation of MAKE_FUNCTION is still incorrect -> Documentation of MAKE_FUNCTION/MAKE_CLOSURE_EXTENDED_ARG is misleading
2015-12-11 04:14:44freakboy3742setversions: - Python 2.7
2015-12-11 04:13:55freakboy3742create