From 73295edb7c1323ea88bc650a7729527b0c7614c9 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 14:05:02 +0100 Subject: [PATCH 1/8] Document _UNPACK bytecodes added in 3.5 and BUILD_MAP changes --- Doc/library/dis.rst | 48 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 694d5642fb0e21..d4e9fef882909c 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -723,6 +723,47 @@ All of the following opcodes use their arguments. are put onto the stack right-to-left. +.. opcode:: BUILD_TUPLE_UNPACK (count) + + Pops ``count`` iterables from the stack, joins them in a single tuple, + and pushes the result. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_LIST_UNPACK (count) + + This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list + instead of tuple. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_SET_UNPACK (count) + + This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set + instead of tuple. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_MAP_UNPACK (count) + + Pops ``count`` mappings from the stack, joins them in a single dictionary, + and pushes the result. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_MAP_UNPACK_WITH_CALL (count) + + This is similar to :opcode:`BUILD_MAP_UNPACK`, + but is used for ``f(**x, **y, **z)`` call syntax. The stack item at position + ``count + 2`` should be the corresponding callable ``f``. + + .. versionadded:: 3.5 + + .. opcode:: STORE_ATTR (namei) Implements ``TOS.name = TOS1``, where *namei* is the index of name in @@ -772,8 +813,11 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP (count) - Pushes a new dictionary object onto the stack. The dictionary is pre-sized - to hold *count* entries. + Pushes a new dictionary object onto the stack. Pops ``2 * count`` items + so that the dictionary holds ``count`` entries: + ``{..., TOS3: TOS2, TOS1: TOS}``. + + .. versionchanged:: 3.5 .. opcode:: BUILD_CONST_KEY_MAP (count) From 5fe6291642380dd40045098c20e368e04e4c0ed0 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 15:39:48 +0100 Subject: [PATCH 2/8] Response to comments --- Doc/library/dis.rst | 88 +++++++++++++++++++++++---------------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index d4e9fef882909c..7d0459687849c9 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -723,47 +723,6 @@ All of the following opcodes use their arguments. are put onto the stack right-to-left. -.. opcode:: BUILD_TUPLE_UNPACK (count) - - Pops ``count`` iterables from the stack, joins them in a single tuple, - and pushes the result. - - .. versionadded:: 3.5 - - -.. opcode:: BUILD_LIST_UNPACK (count) - - This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list - instead of tuple. - - .. versionadded:: 3.5 - - -.. opcode:: BUILD_SET_UNPACK (count) - - This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set - instead of tuple. - - .. versionadded:: 3.5 - - -.. opcode:: BUILD_MAP_UNPACK (count) - - Pops ``count`` mappings from the stack, joins them in a single dictionary, - and pushes the result. - - .. versionadded:: 3.5 - - -.. opcode:: BUILD_MAP_UNPACK_WITH_CALL (count) - - This is similar to :opcode:`BUILD_MAP_UNPACK`, - but is used for ``f(**x, **y, **z)`` call syntax. The stack item at position - ``count + 2`` should be the corresponding callable ``f``. - - .. versionadded:: 3.5 - - .. opcode:: STORE_ATTR (namei) Implements ``TOS.name = TOS1``, where *namei* is the index of name in @@ -813,11 +772,13 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP (count) - Pushes a new dictionary object onto the stack. Pops ``2 * count`` items + Pushes a new dictionary object onto the stack. Pops ``2 * count`` items so that the dictionary holds ``count`` entries: ``{..., TOS3: TOS2, TOS1: TOS}``. .. versionchanged:: 3.5 + The dictionary is created from stack items instead of creating an + empty dictionary pre-sized to hold ``count`` items. .. opcode:: BUILD_CONST_KEY_MAP (count) @@ -837,6 +798,49 @@ All of the following opcodes use their arguments. .. versionadded:: 3.6 +.. opcode:: BUILD_TUPLE_UNPACK (count) + + Pops ``count`` iterables from the stack, joins them in a single tuple, + and pushes the result. This bytecode is used for implementing iterable + unpacking in tuple displays ``(*x, *y, *z)``. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_LIST_UNPACK (count) + + This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list + instead of tuple. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_SET_UNPACK (count) + + This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set + instead of tuple. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_MAP_UNPACK (count) + + Pops ``count`` mappings from the stack, joins them in a single dictionary, + and pushes the result. + + .. versionadded:: 3.5 + + +.. opcode:: BUILD_MAP_UNPACK_WITH_CALL (oparg) + + This is similar to :opcode:`BUILD_MAP_UNPACK`, + but is used for ``f(**x, **y, **z)`` call syntax. The lowest byte of + ``oparg`` is the count of mappings, the relative position of the + corresponding callable ``f`` is encoded in the second byte of ``oparg``. + + .. versionadded:: 3.5 + + .. opcode:: LOAD_ATTR (namei) Replaces TOS with ``getattr(TOS, co_names[namei])``. From a53672b2f78b7cad79a487cbee630c1b44bc5440 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 15:46:57 +0100 Subject: [PATCH 3/8] Formatting (two spaces after period) --- Doc/library/dis.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 7d0459687849c9..8a6e8bb6fc1600 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -801,7 +801,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_TUPLE_UNPACK (count) Pops ``count`` iterables from the stack, joins them in a single tuple, - and pushes the result. This bytecode is used for implementing iterable + and pushes the result. This bytecode is used for implementing iterable unpacking in tuple displays ``(*x, *y, *z)``. .. versionadded:: 3.5 @@ -834,7 +834,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP_UNPACK_WITH_CALL (oparg) This is similar to :opcode:`BUILD_MAP_UNPACK`, - but is used for ``f(**x, **y, **z)`` call syntax. The lowest byte of + but is used for ``f(**x, **y, **z)`` call syntax. The lowest byte of ``oparg`` is the count of mappings, the relative position of the corresponding callable ``f`` is encoded in the second byte of ``oparg``. From 9be8a6b8ce84aa3e58fb1772a218b3f8415ea8f9 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 16:33:03 +0100 Subject: [PATCH 4/8] Response to comments, second round --- Doc/library/dis.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 8a6e8bb6fc1600..832333e4eeb918 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -772,13 +772,13 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP (count) - Pushes a new dictionary object onto the stack. Pops ``2 * count`` items - so that the dictionary holds ``count`` entries: + Pushes a new dictionary object onto the stack. Pops *2 \* count* items + so that the dictionary holds *count* entries: ``{..., TOS3: TOS2, TOS1: TOS}``. .. versionchanged:: 3.5 The dictionary is created from stack items instead of creating an - empty dictionary pre-sized to hold ``count`` items. + empty dictionary pre-sized to hold *count* items. .. opcode:: BUILD_CONST_KEY_MAP (count) @@ -800,7 +800,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_TUPLE_UNPACK (count) - Pops ``count`` iterables from the stack, joins them in a single tuple, + Pops *count* iterables from the stack, joins them in a single tuple, and pushes the result. This bytecode is used for implementing iterable unpacking in tuple displays ``(*x, *y, *z)``. @@ -810,7 +810,8 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_LIST_UNPACK (count) This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list - instead of tuple. + instead of tuple. This bytecode is used for implementing iterable + unpacking in list displays ``[*x, *y, *z]``. .. versionadded:: 3.5 @@ -818,15 +819,17 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_SET_UNPACK (count) This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set - instead of tuple. + instead of tuple. This bytecode is used for implementing iterable + unpacking in set displays ``{*x, *y, *z}``. .. versionadded:: 3.5 .. opcode:: BUILD_MAP_UNPACK (count) - Pops ``count`` mappings from the stack, joins them in a single dictionary, - and pushes the result. + Pops *count* mappings from the stack, merges them in a single dictionary, + and pushes the result. This bytecode is used for implementing iterable + unpacking in dictionary displays ``{**x, **y, **z}``. .. versionadded:: 3.5 @@ -835,8 +838,8 @@ All of the following opcodes use their arguments. This is similar to :opcode:`BUILD_MAP_UNPACK`, but is used for ``f(**x, **y, **z)`` call syntax. The lowest byte of - ``oparg`` is the count of mappings, the relative position of the - corresponding callable ``f`` is encoded in the second byte of ``oparg``. + *oparg* is the count of mappings, the relative position of the + corresponding callable ``f`` is encoded in the second byte of *oparg*. .. versionadded:: 3.5 From 5177ceca30e04f2e5ef872125355e862169c15db Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 16:48:09 +0100 Subject: [PATCH 5/8] Fix formatting --- Doc/library/dis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 832333e4eeb918..092a3db7e84f99 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -772,7 +772,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP (count) - Pushes a new dictionary object onto the stack. Pops *2 \* count* items + Pushes a new dictionary object onto the stack. Pops ``2 * count`` items so that the dictionary holds *count* entries: ``{..., TOS3: TOS2, TOS1: TOS}``. From 8d5281d33fe18e4892f958ee440844baf4aeefe2 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Wed, 22 Feb 2017 16:54:08 +0100 Subject: [PATCH 6/8] Fix terminology --- Doc/library/dis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 092a3db7e84f99..6966b8674a90d3 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -828,7 +828,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP_UNPACK (count) Pops *count* mappings from the stack, merges them in a single dictionary, - and pushes the result. This bytecode is used for implementing iterable + and pushes the result. This bytecode is used for implementing dictionary unpacking in dictionary displays ``{**x, **y, **z}``. .. versionadded:: 3.5 From d32b1d937eff69af47ce06d324aaddb4f9801962 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Fri, 24 Feb 2017 23:35:05 +0100 Subject: [PATCH 7/8] Response to comments (shorter formulation) --- Doc/library/dis.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 6966b8674a90d3..fe91a819d63e51 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -801,8 +801,8 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_TUPLE_UNPACK (count) Pops *count* iterables from the stack, joins them in a single tuple, - and pushes the result. This bytecode is used for implementing iterable - unpacking in tuple displays ``(*x, *y, *z)``. + and pushes the result. Implements iterable unpacking in tuple + displays ``(*x, *y, *z)``. .. versionadded:: 3.5 @@ -810,8 +810,8 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_LIST_UNPACK (count) This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a list - instead of tuple. This bytecode is used for implementing iterable - unpacking in list displays ``[*x, *y, *z]``. + instead of tuple. Implements iterable unpacking in list + displays ``[*x, *y, *z]``. .. versionadded:: 3.5 @@ -819,8 +819,8 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_SET_UNPACK (count) This is similar to :opcode:`BUILD_TUPLE_UNPACK`, but pushes a set - instead of tuple. This bytecode is used for implementing iterable - unpacking in set displays ``{*x, *y, *z}``. + instead of tuple. Implements iterable unpacking in set + displays ``{*x, *y, *z}``. .. versionadded:: 3.5 @@ -828,8 +828,8 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP_UNPACK (count) Pops *count* mappings from the stack, merges them in a single dictionary, - and pushes the result. This bytecode is used for implementing dictionary - unpacking in dictionary displays ``{**x, **y, **z}``. + and pushes the result. Implements dictionary unpacking in dictionary + displays ``{**x, **y, **z}``. .. versionadded:: 3.5 From fb7507cb7d36480668c2066f866fd2147e15cbc9 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 3 Mar 2017 13:27:21 -0800 Subject: [PATCH 8/8] Tweak a word --- Doc/library/dis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index fe91a819d63e51..a15ecdcdb9a4e8 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -827,7 +827,7 @@ All of the following opcodes use their arguments. .. opcode:: BUILD_MAP_UNPACK (count) - Pops *count* mappings from the stack, merges them in a single dictionary, + Pops *count* mappings from the stack, merges them into a single dictionary, and pushes the result. Implements dictionary unpacking in dictionary displays ``{**x, **y, **z}``.