blob: 7a214edcc78911b4a5d907a95622c79041771582 [file] [log] [blame]
Georg Brandl9afde1c2007-11-01 20:32:30 +00001:mod:`dis` --- Disassembler for Python bytecode
2===============================================
Georg Brandl116aa622007-08-15 14:28:22 +00003
4.. module:: dis
Georg Brandl9afde1c2007-11-01 20:32:30 +00005 :synopsis: Disassembler for Python bytecode.
Georg Brandl116aa622007-08-15 14:28:22 +00006
Raymond Hettinger10480942011-01-10 03:26:08 +00007**Source code:** :source:`Lib/dis.py`
Georg Brandl116aa622007-08-15 14:28:22 +00008
Raymond Hettinger4f707fd2011-01-10 19:54:11 +00009--------------
10
Brett Cannon8315fd12010-07-02 22:03:00 +000011The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050012disassembling it. The CPython bytecode which this module takes as an input is
13defined in the file :file:`Include/opcode.h` and used by the compiler and the
14interpreter.
Georg Brandl116aa622007-08-15 14:28:22 +000015
Georg Brandl19b7a872010-07-03 10:21:50 +000016.. impl-detail::
17
Raymond Hettinger10480942011-01-10 03:26:08 +000018 Bytecode is an implementation detail of the CPython interpreter. No
Georg Brandl19b7a872010-07-03 10:21:50 +000019 guarantees are made that bytecode will not be added, removed, or changed
20 between versions of Python. Use of this module should not be considered to
21 work across Python VMs or Python releases.
22
Brett Cannon8315fd12010-07-02 22:03:00 +000023
Georg Brandl116aa622007-08-15 14:28:22 +000024Example: Given the function :func:`myfunc`::
25
26 def myfunc(alist):
27 return len(alist)
28
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100029the following command can be used to display the disassembly of
30:func:`myfunc`::
Georg Brandl116aa622007-08-15 14:28:22 +000031
32 >>> dis.dis(myfunc)
33 2 0 LOAD_GLOBAL 0 (len)
34 3 LOAD_FAST 0 (alist)
35 6 CALL_FUNCTION 1
36 9 RETURN_VALUE
37
38(The "2" is a line number).
39
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100040Bytecode analysis
41-----------------
Georg Brandl116aa622007-08-15 14:28:22 +000042
R David Murray0bce6e72014-01-07 14:30:17 -050043.. versionadded:: 3.4
44
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100045The bytecode analysis API allows pieces of Python code to be wrapped in a
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050046:class:`Bytecode` object that provides easy access to details of the compiled
47code.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100048
Nick Coghlan50c48b82013-11-23 00:57:00 +100049.. class:: Bytecode(x, *, first_line=None, current_offset=None)
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100050
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100051
Benjamin Peterson2f3d4402015-03-02 09:36:48 -050052 Analyse the bytecode corresponding to a function, generator, method, string
53 of source code, or a code object (as returned by :func:`compile`).
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100054
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050055 This is a convenience wrapper around many of the functions listed below, most
56 notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
57 instance yields the bytecode operations as :class:`Instruction` instances.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100058
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050059 If *first_line* is not None, it indicates the line number that should be
60 reported for the first source line in the disassembled code. Otherwise, the
61 source line information (if any) is taken directly from the disassembled code
62 object.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100063
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050064 If *current_offset* is not None, it refers to an instruction offset in the
65 disassembled code. Setting this means :meth:`.dis` will display a "current
66 instruction" marker against the specified opcode.
Nick Coghlan50c48b82013-11-23 00:57:00 +100067
68 .. classmethod:: from_traceback(tb)
69
Benjamin Petersonbdf525b2015-03-02 09:31:40 -050070 Construct a :class:`Bytecode` instance from the given traceback, setting
71 *current_offset* to the instruction responsible for the exception.
Nick Coghlan50c48b82013-11-23 00:57:00 +100072
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100073 .. data:: codeobj
74
75 The compiled code object.
76
Nick Coghlan90b8e7d2013-11-06 22:08:36 +100077 .. data:: first_line
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100078
Nick Coghlan90b8e7d2013-11-06 22:08:36 +100079 The first source line of the code object (if available)
80
81 .. method:: dis()
82
Benjamin Peterson29fec922015-03-02 09:27:43 -050083 Return a formatted view of the bytecode operations (the same as printed by
84 :func:`dis.dis`, but returned as a multi-line string).
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100085
86 .. method:: info()
87
88 Return a formatted multi-line string with detailed information about the
89 code object, like :func:`code_info`.
90
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100091Example::
92
93 >>> bytecode = dis.Bytecode(myfunc)
94 >>> for instr in bytecode:
95 ... print(instr.opname)
96 ...
97 LOAD_GLOBAL
98 LOAD_FAST
99 CALL_FUNCTION
100 RETURN_VALUE
101
102
103Analysis functions
104------------------
105
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500106The :mod:`dis` module also defines the following analysis functions that convert
107the input directly to the desired output. They can be useful if only a single
108operation is being performed, so the intermediate analysis object isn't useful:
Georg Brandl116aa622007-08-15 14:28:22 +0000109
Nick Coghlane8814fb2010-09-10 14:08:04 +0000110.. function:: code_info(x)
Nick Coghlaneae2da12010-08-17 08:03:36 +0000111
Georg Brandl67b21b72010-08-17 15:07:14 +0000112 Return a formatted multi-line string with detailed code object information
Nick Coghlanefd5df92014-07-25 23:02:56 +1000113 for the supplied function, generator, method, source code string or code object.
Nick Coghlaneae2da12010-08-17 08:03:36 +0000114
Georg Brandl67b21b72010-08-17 15:07:14 +0000115 Note that the exact contents of code info strings are highly implementation
116 dependent and they may change arbitrarily across Python VMs or Python
117 releases.
Nick Coghlaneae2da12010-08-17 08:03:36 +0000118
119 .. versionadded:: 3.2
120
Georg Brandl67b21b72010-08-17 15:07:14 +0000121
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000122.. function:: show_code(x, *, file=None)
Nick Coghlane8814fb2010-09-10 14:08:04 +0000123
124 Print detailed code object information for the supplied function, method,
Ezio Melotti6e6c6ac2013-08-23 22:41:39 +0300125 source code string or code object to *file* (or ``sys.stdout`` if *file*
126 is not specified).
Nick Coghlane8814fb2010-09-10 14:08:04 +0000127
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000128 This is a convenient shorthand for ``print(code_info(x), file=file)``,
129 intended for interactive exploration at the interpreter prompt.
Nick Coghlane8814fb2010-09-10 14:08:04 +0000130
131 .. versionadded:: 3.2
132
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000133 .. versionchanged:: 3.4
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200134 Added *file* parameter.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000135
136
137.. function:: dis(x=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000138
Georg Brandl67b21b72010-08-17 15:07:14 +0000139 Disassemble the *x* object. *x* can denote either a module, a class, a
Nick Coghlanefd5df92014-07-25 23:02:56 +1000140 method, a function, a generator, a code object, a string of source code or
141 a byte sequence of raw bytecode. For a module, it disassembles all functions.
142 For a class, it disassembles all methods. For a code object or sequence of
143 raw bytecode, it prints one line per bytecode instruction. Strings are first
144 compiled to code objects with the :func:`compile` built-in function before being
Georg Brandl67b21b72010-08-17 15:07:14 +0000145 disassembled. If no object is provided, this function disassembles the last
146 traceback.
Georg Brandl116aa622007-08-15 14:28:22 +0000147
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200148 The disassembly is written as text to the supplied *file* argument if
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000149 provided and to ``sys.stdout`` otherwise.
Georg Brandl116aa622007-08-15 14:28:22 +0000150
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000151 .. versionchanged:: 3.4
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200152 Added *file* parameter.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000153
154
155.. function:: distb(tb=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000156
Georg Brandl4833e5b2010-07-03 10:41:33 +0000157 Disassemble the top-of-stack function of a traceback, using the last
158 traceback if none was passed. The instruction causing the exception is
159 indicated.
Georg Brandl116aa622007-08-15 14:28:22 +0000160
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200161 The disassembly is written as text to the supplied *file* argument if
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000162 provided and to ``sys.stdout`` otherwise.
Georg Brandl116aa622007-08-15 14:28:22 +0000163
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000164 .. versionchanged:: 3.4
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200165 Added *file* parameter.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000166
167
168.. function:: disassemble(code, lasti=-1, *, file=None)
169 disco(code, lasti=-1, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000170
Georg Brandl4833e5b2010-07-03 10:41:33 +0000171 Disassemble a code object, indicating the last instruction if *lasti* was
Georg Brandl116aa622007-08-15 14:28:22 +0000172 provided. The output is divided in the following columns:
173
174 #. the line number, for the first instruction of each line
175 #. the current instruction, indicated as ``-->``,
176 #. a labelled instruction, indicated with ``>>``,
177 #. the address of the instruction,
178 #. the operation code name,
179 #. operation parameters, and
180 #. interpretation of the parameters in parentheses.
181
182 The parameter interpretation recognizes local and global variable names,
183 constant values, branch targets, and compare operators.
184
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200185 The disassembly is written as text to the supplied *file* argument if
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000186 provided and to ``sys.stdout`` otherwise.
187
188 .. versionchanged:: 3.4
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200189 Added *file* parameter.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000190
191
Nick Coghlan90b8e7d2013-11-06 22:08:36 +1000192.. function:: get_instructions(x, *, first_line=None)
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000193
194 Return an iterator over the instructions in the supplied function, method,
195 source code string or code object.
196
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500197 The iterator generates a series of :class:`Instruction` named tuples giving
198 the details of each operation in the supplied code.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000199
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500200 If *first_line* is not None, it indicates the line number that should be
201 reported for the first source line in the disassembled code. Otherwise, the
202 source line information (if any) is taken directly from the disassembled code
203 object.
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000204
205 .. versionadded:: 3.4
206
Georg Brandl116aa622007-08-15 14:28:22 +0000207
Benjamin Peterson75edad02009-01-01 15:05:06 +0000208.. function:: findlinestarts(code)
209
210 This generator function uses the ``co_firstlineno`` and ``co_lnotab``
211 attributes of the code object *code* to find the offsets which are starts of
212 lines in the source code. They are generated as ``(offset, lineno)`` pairs.
213
214
215.. function:: findlabels(code)
216
217 Detect all offsets in the code object *code* which are jump targets, and
218 return a list of these offsets.
Georg Brandl48310cd2009-01-03 21:18:54 +0000219
Larry Hastings3a907972013-11-23 14:49:22 -0800220
221.. function:: stack_effect(opcode, [oparg])
222
223 Compute the stack effect of *opcode* with argument *oparg*.
224
225 .. versionadded:: 3.4
226
Georg Brandl116aa622007-08-15 14:28:22 +0000227.. _bytecodes:
228
Georg Brandl9afde1c2007-11-01 20:32:30 +0000229Python Bytecode Instructions
230----------------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000231
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000232The :func:`get_instructions` function and :class:`Bytecode` class provide
233details of bytecode instructions as :class:`Instruction` instances:
234
235.. class:: Instruction
236
237 Details for a bytecode operation
238
239 .. data:: opcode
240
241 numeric code for operation, corresponding to the opcode values listed
242 below and the bytecode values in the :ref:`opcode_collections`.
243
244
245 .. data:: opname
246
247 human readable name for operation
248
249
250 .. data:: arg
251
252 numeric argument to operation (if any), otherwise None
253
254
255 .. data:: argval
256
257 resolved arg value (if known), otherwise same as arg
258
259
260 .. data:: argrepr
261
262 human readable description of operation argument
263
264
265 .. data:: offset
266
267 start index of operation within bytecode sequence
268
269
270 .. data:: starts_line
271
272 line started by this opcode (if any), otherwise None
273
274
275 .. data:: is_jump_target
276
Serhiy Storchaka0e90e992013-11-29 12:19:53 +0200277 ``True`` if other code jumps to here, otherwise ``False``
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000278
279 .. versionadded:: 3.4
280
281
Georg Brandl9afde1c2007-11-01 20:32:30 +0000282The Python compiler currently generates the following bytecode instructions.
Georg Brandl116aa622007-08-15 14:28:22 +0000283
284
Georg Brandl4833e5b2010-07-03 10:41:33 +0000285**General instructions**
286
Georg Brandl4833e5b2010-07-03 10:41:33 +0000287.. opcode:: NOP
Georg Brandl116aa622007-08-15 14:28:22 +0000288
289 Do nothing code. Used as a placeholder by the bytecode optimizer.
290
291
Georg Brandl4833e5b2010-07-03 10:41:33 +0000292.. opcode:: POP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000293
294 Removes the top-of-stack (TOS) item.
295
296
Georg Brandl4833e5b2010-07-03 10:41:33 +0000297.. opcode:: ROT_TWO
Georg Brandl116aa622007-08-15 14:28:22 +0000298
299 Swaps the two top-most stack items.
300
301
Georg Brandl4833e5b2010-07-03 10:41:33 +0000302.. opcode:: ROT_THREE
Georg Brandl116aa622007-08-15 14:28:22 +0000303
304 Lifts second and third stack item one position up, moves top down to position
305 three.
306
307
Georg Brandl4833e5b2010-07-03 10:41:33 +0000308.. opcode:: DUP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000309
310 Duplicates the reference on top of the stack.
311
Georg Brandl4833e5b2010-07-03 10:41:33 +0000312
Antoine Pitrou74a69fa2010-09-04 18:43:52 +0000313.. opcode:: DUP_TOP_TWO
314
315 Duplicates the two references on top of the stack, leaving them in the
316 same order.
317
318
Georg Brandl4833e5b2010-07-03 10:41:33 +0000319**Unary operations**
320
321Unary operations take the top of the stack, apply the operation, and push the
Georg Brandl116aa622007-08-15 14:28:22 +0000322result back on the stack.
323
Georg Brandl4833e5b2010-07-03 10:41:33 +0000324.. opcode:: UNARY_POSITIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000325
326 Implements ``TOS = +TOS``.
327
328
Georg Brandl4833e5b2010-07-03 10:41:33 +0000329.. opcode:: UNARY_NEGATIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000330
331 Implements ``TOS = -TOS``.
332
333
Georg Brandl4833e5b2010-07-03 10:41:33 +0000334.. opcode:: UNARY_NOT
Georg Brandl116aa622007-08-15 14:28:22 +0000335
336 Implements ``TOS = not TOS``.
337
338
Georg Brandl4833e5b2010-07-03 10:41:33 +0000339.. opcode:: UNARY_INVERT
Georg Brandl116aa622007-08-15 14:28:22 +0000340
341 Implements ``TOS = ~TOS``.
342
343
Georg Brandl4833e5b2010-07-03 10:41:33 +0000344.. opcode:: GET_ITER
Georg Brandl116aa622007-08-15 14:28:22 +0000345
346 Implements ``TOS = iter(TOS)``.
347
Georg Brandl4833e5b2010-07-03 10:41:33 +0000348
Yury Selivanov5376ba92015-06-22 12:19:30 -0400349.. opcode:: GET_YIELD_FROM_ITER
350
351 If ``TOS`` is a :term:`generator iterator` or :term:`coroutine` object
352 it is left as is. Otherwise, implements ``TOS = iter(TOS)``.
353
354 .. versionadded:: 3.5
355
356
Georg Brandl4833e5b2010-07-03 10:41:33 +0000357**Binary operations**
358
Georg Brandl116aa622007-08-15 14:28:22 +0000359Binary operations remove the top of the stack (TOS) and the second top-most
360stack item (TOS1) from the stack. They perform the operation, and put the
361result back on the stack.
362
Georg Brandl4833e5b2010-07-03 10:41:33 +0000363.. opcode:: BINARY_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000364
365 Implements ``TOS = TOS1 ** TOS``.
366
367
Georg Brandl4833e5b2010-07-03 10:41:33 +0000368.. opcode:: BINARY_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000369
370 Implements ``TOS = TOS1 * TOS``.
371
372
Benjamin Petersond51374e2014-04-09 23:55:56 -0400373.. opcode:: BINARY_MATRIX_MULTIPLY
374
375 Implements ``TOS = TOS1 @ TOS``.
376
Berker Peksagda0870c2015-03-12 20:56:45 +0200377 .. versionadded:: 3.5
378
Benjamin Petersond51374e2014-04-09 23:55:56 -0400379
Georg Brandl4833e5b2010-07-03 10:41:33 +0000380.. opcode:: BINARY_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000381
382 Implements ``TOS = TOS1 // TOS``.
383
384
Georg Brandl4833e5b2010-07-03 10:41:33 +0000385.. opcode:: BINARY_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000386
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000387 Implements ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000388
389
Georg Brandl4833e5b2010-07-03 10:41:33 +0000390.. opcode:: BINARY_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000391
392 Implements ``TOS = TOS1 % TOS``.
393
394
Georg Brandl4833e5b2010-07-03 10:41:33 +0000395.. opcode:: BINARY_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000396
397 Implements ``TOS = TOS1 + TOS``.
398
399
Georg Brandl4833e5b2010-07-03 10:41:33 +0000400.. opcode:: BINARY_SUBTRACT
Georg Brandl116aa622007-08-15 14:28:22 +0000401
402 Implements ``TOS = TOS1 - TOS``.
403
404
Georg Brandl4833e5b2010-07-03 10:41:33 +0000405.. opcode:: BINARY_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000406
407 Implements ``TOS = TOS1[TOS]``.
408
409
Georg Brandl4833e5b2010-07-03 10:41:33 +0000410.. opcode:: BINARY_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000411
412 Implements ``TOS = TOS1 << TOS``.
413
414
Georg Brandl4833e5b2010-07-03 10:41:33 +0000415.. opcode:: BINARY_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000416
417 Implements ``TOS = TOS1 >> TOS``.
418
419
Georg Brandl4833e5b2010-07-03 10:41:33 +0000420.. opcode:: BINARY_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000421
422 Implements ``TOS = TOS1 & TOS``.
423
424
Georg Brandl4833e5b2010-07-03 10:41:33 +0000425.. opcode:: BINARY_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000426
427 Implements ``TOS = TOS1 ^ TOS``.
428
429
Georg Brandl4833e5b2010-07-03 10:41:33 +0000430.. opcode:: BINARY_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000431
432 Implements ``TOS = TOS1 | TOS``.
433
Georg Brandl4833e5b2010-07-03 10:41:33 +0000434
435**In-place operations**
436
Georg Brandl116aa622007-08-15 14:28:22 +0000437In-place operations are like binary operations, in that they remove TOS and
438TOS1, and push the result back on the stack, but the operation is done in-place
439when TOS1 supports it, and the resulting TOS may be (but does not have to be)
440the original TOS1.
441
Georg Brandl4833e5b2010-07-03 10:41:33 +0000442.. opcode:: INPLACE_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000443
444 Implements in-place ``TOS = TOS1 ** TOS``.
445
446
Georg Brandl4833e5b2010-07-03 10:41:33 +0000447.. opcode:: INPLACE_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000448
449 Implements in-place ``TOS = TOS1 * TOS``.
450
451
Benjamin Petersond51374e2014-04-09 23:55:56 -0400452.. opcode:: INPLACE_MATRIX_MULTIPLY
453
454 Implements in-place ``TOS = TOS1 @ TOS``.
455
Berker Peksagda0870c2015-03-12 20:56:45 +0200456 .. versionadded:: 3.5
457
Benjamin Petersond51374e2014-04-09 23:55:56 -0400458
Georg Brandl4833e5b2010-07-03 10:41:33 +0000459.. opcode:: INPLACE_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000460
461 Implements in-place ``TOS = TOS1 // TOS``.
462
463
Georg Brandl4833e5b2010-07-03 10:41:33 +0000464.. opcode:: INPLACE_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000465
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000466 Implements in-place ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000467
468
Georg Brandl4833e5b2010-07-03 10:41:33 +0000469.. opcode:: INPLACE_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000470
471 Implements in-place ``TOS = TOS1 % TOS``.
472
473
Georg Brandl4833e5b2010-07-03 10:41:33 +0000474.. opcode:: INPLACE_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000475
476 Implements in-place ``TOS = TOS1 + TOS``.
477
478
Georg Brandl4833e5b2010-07-03 10:41:33 +0000479.. opcode:: INPLACE_SUBTRACT
Georg Brandl116aa622007-08-15 14:28:22 +0000480
481 Implements in-place ``TOS = TOS1 - TOS``.
482
483
Georg Brandl4833e5b2010-07-03 10:41:33 +0000484.. opcode:: INPLACE_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000485
486 Implements in-place ``TOS = TOS1 << TOS``.
487
488
Georg Brandl4833e5b2010-07-03 10:41:33 +0000489.. opcode:: INPLACE_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000490
491 Implements in-place ``TOS = TOS1 >> TOS``.
492
493
Georg Brandl4833e5b2010-07-03 10:41:33 +0000494.. opcode:: INPLACE_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000495
496 Implements in-place ``TOS = TOS1 & TOS``.
497
498
Georg Brandl4833e5b2010-07-03 10:41:33 +0000499.. opcode:: INPLACE_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000500
501 Implements in-place ``TOS = TOS1 ^ TOS``.
502
503
Georg Brandl4833e5b2010-07-03 10:41:33 +0000504.. opcode:: INPLACE_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000505
506 Implements in-place ``TOS = TOS1 | TOS``.
507
Georg Brandl116aa622007-08-15 14:28:22 +0000508
Georg Brandl4833e5b2010-07-03 10:41:33 +0000509.. opcode:: STORE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000510
511 Implements ``TOS1[TOS] = TOS2``.
512
513
Georg Brandl4833e5b2010-07-03 10:41:33 +0000514.. opcode:: DELETE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000515
516 Implements ``del TOS1[TOS]``.
517
Georg Brandl116aa622007-08-15 14:28:22 +0000518
Yury Selivanov66f88282015-06-24 11:04:15 -0400519**Coroutine opcodes**
Yury Selivanov75445082015-05-11 22:57:16 -0400520
521.. opcode:: GET_AWAITABLE
522
Yury Selivanov66f88282015-06-24 11:04:15 -0400523 Implements ``TOS = get_awaitable(TOS)``, where ``get_awaitable(o)``
524 returns ``o`` if ``o`` is a coroutine object or a generator object with
525 the CO_ITERABLE_COROUTINE flag, or resolves
526 ``o.__await__``.
Yury Selivanov75445082015-05-11 22:57:16 -0400527
528
529.. opcode:: GET_AITER
530
531 Implements ``TOS = get_awaitable(TOS.__aiter__())``. See ``GET_AWAITABLE``
532 for details about ``get_awaitable``
533
534
535.. opcode:: GET_ANEXT
536
537 Implements ``PUSH(get_awaitable(TOS.__anext__()))``. See ``GET_AWAITABLE``
538 for details about ``get_awaitable``
539
540
541.. opcode:: BEFORE_ASYNC_WITH
542
543 Resolves ``__aenter__`` and ``__aexit__`` from the object on top of the
544 stack. Pushes ``__aexit__`` and result of ``__aenter__()`` to the stack.
545
546
547.. opcode:: SETUP_ASYNC_WITH
548
549 Creates a new frame object.
550
551
552
Georg Brandl4833e5b2010-07-03 10:41:33 +0000553**Miscellaneous opcodes**
Georg Brandl116aa622007-08-15 14:28:22 +0000554
Georg Brandl4833e5b2010-07-03 10:41:33 +0000555.. opcode:: PRINT_EXPR
Georg Brandl116aa622007-08-15 14:28:22 +0000556
557 Implements the expression statement for the interactive mode. TOS is removed
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500558 from the stack and printed. In non-interactive mode, an expression statement
559 is terminated with :opcode:`POP_TOP`.
Georg Brandl116aa622007-08-15 14:28:22 +0000560
561
Georg Brandl4833e5b2010-07-03 10:41:33 +0000562.. opcode:: BREAK_LOOP
Georg Brandl116aa622007-08-15 14:28:22 +0000563
564 Terminates a loop due to a :keyword:`break` statement.
565
566
567.. opcode:: CONTINUE_LOOP (target)
568
569 Continues a loop due to a :keyword:`continue` statement. *target* is the
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200570 address to jump to (which should be a :opcode:`FOR_ITER` instruction).
Georg Brandl116aa622007-08-15 14:28:22 +0000571
572
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000573.. opcode:: SET_ADD (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000574
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000575 Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions.
Georg Brandl116aa622007-08-15 14:28:22 +0000576
577
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000578.. opcode:: LIST_APPEND (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000579
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000580 Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
581
582
583.. opcode:: MAP_ADD (i)
584
585 Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict
586 comprehensions.
587
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200588For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD`
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500589instructions, while the added value or key/value pair is popped off, the
590container object remains on the stack so that it is available for further
591iterations of the loop.
Georg Brandl116aa622007-08-15 14:28:22 +0000592
593
Georg Brandl4833e5b2010-07-03 10:41:33 +0000594.. opcode:: RETURN_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000595
596 Returns with TOS to the caller of the function.
597
598
Georg Brandl4833e5b2010-07-03 10:41:33 +0000599.. opcode:: YIELD_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000600
Berker Peksagab4040e2015-03-02 06:33:30 +0200601 Pops TOS and yields it from a :term:`generator`.
Georg Brandl116aa622007-08-15 14:28:22 +0000602
603
Nick Coghlan1f7ce622012-01-13 21:43:40 +1000604.. opcode:: YIELD_FROM
605
Berker Peksagab4040e2015-03-02 06:33:30 +0200606 Pops TOS and delegates to it as a subiterator from a :term:`generator`.
Nick Coghlan1f7ce622012-01-13 21:43:40 +1000607
608 .. versionadded:: 3.3
609
610
Georg Brandl4833e5b2010-07-03 10:41:33 +0000611.. opcode:: IMPORT_STAR
Georg Brandl116aa622007-08-15 14:28:22 +0000612
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500613 Loads all symbols not starting with ``'_'`` directly from the module TOS to
614 the local namespace. The module is popped after loading all names. This
615 opcode implements ``from module import *``.
Georg Brandl116aa622007-08-15 14:28:22 +0000616
617
Georg Brandl4833e5b2010-07-03 10:41:33 +0000618.. opcode:: POP_BLOCK
Georg Brandl116aa622007-08-15 14:28:22 +0000619
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500620 Removes one block from the block stack. Per frame, there is a stack of
621 blocks, denoting nested loops, try statements, and such.
Georg Brandl116aa622007-08-15 14:28:22 +0000622
623
Georg Brandl4833e5b2010-07-03 10:41:33 +0000624.. opcode:: POP_EXCEPT
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000625
626 Removes one block from the block stack. The popped block must be an exception
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500627 handler block, as implicitly created when entering an except handler. In
628 addition to popping extraneous values from the frame stack, the last three
629 popped values are used to restore the exception state.
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000630
631
Georg Brandl4833e5b2010-07-03 10:41:33 +0000632.. opcode:: END_FINALLY
Georg Brandl116aa622007-08-15 14:28:22 +0000633
634 Terminates a :keyword:`finally` clause. The interpreter recalls whether the
635 exception has to be re-raised, or whether the function returns, and continues
636 with the outer-next block.
637
638
Georg Brandl4833e5b2010-07-03 10:41:33 +0000639.. opcode:: LOAD_BUILD_CLASS
Georg Brandl116aa622007-08-15 14:28:22 +0000640
Georg Brandl5ac22302008-07-20 21:39:03 +0000641 Pushes :func:`builtins.__build_class__` onto the stack. It is later called
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200642 by :opcode:`CALL_FUNCTION` to construct a class.
Georg Brandl116aa622007-08-15 14:28:22 +0000643
Guido van Rossum04110fb2007-08-24 16:32:05 +0000644
Benjamin Peterson876b2f22009-06-28 03:18:59 +0000645.. opcode:: SETUP_WITH (delta)
646
647 This opcode performs several operations before a with block starts. First,
648 it loads :meth:`~object.__exit__` from the context manager and pushes it onto
649 the stack for later use by :opcode:`WITH_CLEANUP`. Then,
650 :meth:`~object.__enter__` is called, and a finally block pointing to *delta*
651 is pushed. Finally, the result of calling the enter method is pushed onto
652 the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
653 store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
654 :opcode:`UNPACK_SEQUENCE`).
655
656
Yury Selivanov75445082015-05-11 22:57:16 -0400657.. opcode:: WITH_CLEANUP_START
Guido van Rossum04110fb2007-08-24 16:32:05 +0000658
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500659 Cleans up the stack when a :keyword:`with` statement block exits. TOS is the
660 context manager's :meth:`__exit__` bound method. Below TOS are 1--3 values
661 indicating how/why the finally clause was entered:
Guido van Rossum04110fb2007-08-24 16:32:05 +0000662
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000663 * SECOND = ``None``
664 * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval
665 * SECOND = ``WHY_*``; no retval below it
666 * (SECOND, THIRD, FOURTH) = exc_info()
Guido van Rossum04110fb2007-08-24 16:32:05 +0000667
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000668 In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise
Yury Selivanov75445082015-05-11 22:57:16 -0400669 ``TOS(None, None, None)``. Pushes SECOND and result of the call
670 to the stack.
671
672
673.. opcode:: WITH_CLEANUP_FINISH
674
675 Pops exception type and result of 'exit' function call from the stack.
Guido van Rossum04110fb2007-08-24 16:32:05 +0000676
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500677 If the stack represents an exception, *and* the function call returns a
678 'true' value, this information is "zapped" and replaced with a single
679 ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the
680 exception. (But non-local gotos will still be resumed.)
Guido van Rossum04110fb2007-08-24 16:32:05 +0000681
Georg Brandl9afde1c2007-11-01 20:32:30 +0000682 .. XXX explain the WHY stuff!
683
Guido van Rossum04110fb2007-08-24 16:32:05 +0000684
Georg Brandl116aa622007-08-15 14:28:22 +0000685All of the following opcodes expect arguments. An argument is two bytes, with
686the more significant byte last.
687
Georg Brandl116aa622007-08-15 14:28:22 +0000688.. opcode:: STORE_NAME (namei)
689
690 Implements ``name = TOS``. *namei* is the index of *name* in the attribute
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500691 :attr:`co_names` of the code object. The compiler tries to use
692 :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
Georg Brandl116aa622007-08-15 14:28:22 +0000693
694
695.. opcode:: DELETE_NAME (namei)
696
697 Implements ``del name``, where *namei* is the index into :attr:`co_names`
698 attribute of the code object.
699
700
701.. opcode:: UNPACK_SEQUENCE (count)
702
703 Unpacks TOS into *count* individual values, which are put onto the stack
704 right-to-left.
705
Georg Brandl116aa622007-08-15 14:28:22 +0000706
Georg Brandl5ac22302008-07-20 21:39:03 +0000707.. opcode:: UNPACK_EX (counts)
708
709 Implements assignment with a starred target: Unpacks an iterable in TOS into
710 individual values, where the total number of values can be smaller than the
711 number of items in the iterable: one the new values will be a list of all
712 leftover items.
713
714 The low byte of *counts* is the number of values before the list value, the
715 high byte of *counts* the number of values after it. The resulting values
716 are put onto the stack right-to-left.
Georg Brandl48310cd2009-01-03 21:18:54 +0000717
Georg Brandl5ac22302008-07-20 21:39:03 +0000718
Georg Brandl116aa622007-08-15 14:28:22 +0000719.. opcode:: STORE_ATTR (namei)
720
721 Implements ``TOS.name = TOS1``, where *namei* is the index of name in
722 :attr:`co_names`.
723
724
725.. opcode:: DELETE_ATTR (namei)
726
727 Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
728
729
730.. opcode:: STORE_GLOBAL (namei)
731
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200732 Works as :opcode:`STORE_NAME`, but stores the name as a global.
Georg Brandl116aa622007-08-15 14:28:22 +0000733
734
735.. opcode:: DELETE_GLOBAL (namei)
736
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200737 Works as :opcode:`DELETE_NAME`, but deletes a global name.
Georg Brandl116aa622007-08-15 14:28:22 +0000738
Georg Brandl116aa622007-08-15 14:28:22 +0000739
740.. opcode:: LOAD_CONST (consti)
741
742 Pushes ``co_consts[consti]`` onto the stack.
743
744
745.. opcode:: LOAD_NAME (namei)
746
747 Pushes the value associated with ``co_names[namei]`` onto the stack.
748
749
750.. opcode:: BUILD_TUPLE (count)
751
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500752 Creates a tuple consuming *count* items from the stack, and pushes the
753 resulting tuple onto the stack.
Georg Brandl116aa622007-08-15 14:28:22 +0000754
755
756.. opcode:: BUILD_LIST (count)
757
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200758 Works as :opcode:`BUILD_TUPLE`, but creates a list.
Georg Brandl116aa622007-08-15 14:28:22 +0000759
760
761.. opcode:: BUILD_SET (count)
762
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200763 Works as :opcode:`BUILD_TUPLE`, but creates a set.
Georg Brandl116aa622007-08-15 14:28:22 +0000764
765
Christian Heimesa62da1d2008-01-12 19:39:10 +0000766.. opcode:: BUILD_MAP (count)
Georg Brandl116aa622007-08-15 14:28:22 +0000767
Christian Heimesa62da1d2008-01-12 19:39:10 +0000768 Pushes a new dictionary object onto the stack. The dictionary is pre-sized
769 to hold *count* entries.
Georg Brandl116aa622007-08-15 14:28:22 +0000770
771
772.. opcode:: LOAD_ATTR (namei)
773
774 Replaces TOS with ``getattr(TOS, co_names[namei])``.
775
776
777.. opcode:: COMPARE_OP (opname)
778
779 Performs a Boolean operation. The operation name can be found in
780 ``cmp_op[opname]``.
781
782
783.. opcode:: IMPORT_NAME (namei)
784
Christian Heimesa342c012008-04-20 21:01:16 +0000785 Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
786 the *fromlist* and *level* arguments of :func:`__import__`. The module
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500787 object is pushed onto the stack. The current namespace is not affected: for
788 a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
Christian Heimesa342c012008-04-20 21:01:16 +0000789 modifies the namespace.
Georg Brandl116aa622007-08-15 14:28:22 +0000790
791
792.. opcode:: IMPORT_FROM (namei)
793
794 Loads the attribute ``co_names[namei]`` from the module found in TOS. The
795 resulting object is pushed onto the stack, to be subsequently stored by a
Serhiy Storchakaf751a9e2014-11-11 10:02:11 +0200796 :opcode:`STORE_FAST` instruction.
Georg Brandl116aa622007-08-15 14:28:22 +0000797
798
799.. opcode:: JUMP_FORWARD (delta)
800
Georg Brandl9afde1c2007-11-01 20:32:30 +0000801 Increments bytecode counter by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000802
803
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000804.. opcode:: POP_JUMP_IF_TRUE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000805
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000806 If TOS is true, sets the bytecode counter to *target*. TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000807
808
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000809.. opcode:: POP_JUMP_IF_FALSE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000810
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000811 If TOS is false, sets the bytecode counter to *target*. TOS is popped.
812
813
814.. opcode:: JUMP_IF_TRUE_OR_POP (target)
815
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500816 If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
817 stack. Otherwise (TOS is false), TOS is popped.
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000818
819
820.. opcode:: JUMP_IF_FALSE_OR_POP (target)
821
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500822 If TOS is false, sets the bytecode counter to *target* and leaves TOS on the
823 stack. Otherwise (TOS is true), TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000824
825
826.. opcode:: JUMP_ABSOLUTE (target)
827
Georg Brandl9afde1c2007-11-01 20:32:30 +0000828 Set bytecode counter to *target*.
Georg Brandl116aa622007-08-15 14:28:22 +0000829
830
831.. opcode:: FOR_ITER (delta)
832
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500833 TOS is an :term:`iterator`. Call its :meth:`~iterator.__next__` method. If
834 this yields a new value, push it on the stack (leaving the iterator below
835 it). If the iterator indicates it is exhausted TOS is popped, and the byte
836 code counter is incremented by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000837
Georg Brandl116aa622007-08-15 14:28:22 +0000838
839.. opcode:: LOAD_GLOBAL (namei)
840
841 Loads the global named ``co_names[namei]`` onto the stack.
842
Georg Brandl116aa622007-08-15 14:28:22 +0000843
844.. opcode:: SETUP_LOOP (delta)
845
846 Pushes a block for a loop onto the block stack. The block spans from the
847 current instruction with a size of *delta* bytes.
848
849
850.. opcode:: SETUP_EXCEPT (delta)
851
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500852 Pushes a try block from a try-except clause onto the block stack. *delta*
853 points to the first except block.
Georg Brandl116aa622007-08-15 14:28:22 +0000854
855
856.. opcode:: SETUP_FINALLY (delta)
857
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500858 Pushes a try block from a try-except clause onto the block stack. *delta*
859 points to the finally block.
Georg Brandl116aa622007-08-15 14:28:22 +0000860
861
862.. opcode:: LOAD_FAST (var_num)
863
864 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
865
866
867.. opcode:: STORE_FAST (var_num)
868
869 Stores TOS into the local ``co_varnames[var_num]``.
870
871
872.. opcode:: DELETE_FAST (var_num)
873
874 Deletes local ``co_varnames[var_num]``.
875
876
877.. opcode:: LOAD_CLOSURE (i)
878
879 Pushes a reference to the cell contained in slot *i* of the cell and free
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500880 variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
881 less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
Georg Brandl116aa622007-08-15 14:28:22 +0000882 len(co_cellvars)]``.
883
884
885.. opcode:: LOAD_DEREF (i)
886
887 Loads the cell contained in slot *i* of the cell and free variable storage.
888 Pushes a reference to the object the cell contains on the stack.
889
890
Benjamin Peterson3b0431d2013-04-30 09:41:40 -0400891.. opcode:: LOAD_CLASSDEREF (i)
892
893 Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
894 consulting the cell. This is used for loading free variables in class
895 bodies.
896
897
Georg Brandl116aa622007-08-15 14:28:22 +0000898.. opcode:: STORE_DEREF (i)
899
900 Stores TOS into the cell contained in slot *i* of the cell and free variable
901 storage.
902
903
Amaury Forgeot d'Arcba117ef2010-09-10 21:39:53 +0000904.. opcode:: DELETE_DEREF (i)
905
906 Empties the cell contained in slot *i* of the cell and free variable storage.
907 Used by the :keyword:`del` statement.
908
909
Georg Brandl116aa622007-08-15 14:28:22 +0000910.. opcode:: RAISE_VARARGS (argc)
911
912 Raises an exception. *argc* indicates the number of parameters to the raise
913 statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
914 the parameter as TOS1, and the exception as TOS.
915
916
917.. opcode:: CALL_FUNCTION (argc)
918
919 Calls a function. The low byte of *argc* indicates the number of positional
920 parameters, the high byte the number of keyword parameters. On the stack, the
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500921 opcode finds the keyword parameters first. For each keyword argument, the
922 value is on top of the key. Below the keyword parameters, the positional
923 parameters are on the stack, with the right-most parameter on top. Below the
924 parameters, the function object to call is on the stack. Pops all function
925 arguments, and the function itself off the stack, and pushes the return
926 value.
Georg Brandl116aa622007-08-15 14:28:22 +0000927
928
929.. opcode:: MAKE_FUNCTION (argc)
930
Georg Brandlc96ef1f2013-10-12 18:41:18 +0200931 Pushes a new function object on the stack. From bottom to top, the consumed
932 stack must consist of
933
934 * ``argc & 0xFF`` default argument objects in positional order
935 * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the name
936 just below the object on the stack, for keyword-only parameters
937 * ``(argc >> 16) & 0x7FFF`` parameter annotation objects
938 * a tuple listing the parameter names for the annotations (only if there are
939 ony annotation objects)
940 * the code associated with the function (at TOS1)
941 * the :term:`qualified name` of the function (at TOS)
Georg Brandl116aa622007-08-15 14:28:22 +0000942
943
944.. opcode:: MAKE_CLOSURE (argc)
945
Guido van Rossum04110fb2007-08-24 16:32:05 +0000946 Creates a new function object, sets its *__closure__* slot, and pushes it on
Andrew Svetlova5c43092012-11-23 15:28:34 +0200947 the stack. TOS is the :term:`qualified name` of the function, TOS1 is the
948 code associated with the function, and TOS2 is the tuple containing cells for
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500949 the closure's free variables. The function also has *argc* default
950 parameters, which are found below the cells.
Georg Brandl116aa622007-08-15 14:28:22 +0000951
952
953.. opcode:: BUILD_SLICE (argc)
954
955 .. index:: builtin: slice
956
957 Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
958 ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000959 pushed. See the :func:`slice` built-in function for more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000960
961
962.. opcode:: EXTENDED_ARG (ext)
963
964 Prefixes any opcode which has an argument too big to fit into the default two
965 bytes. *ext* holds two additional bytes which, taken together with the
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500966 subsequent opcode's argument, comprise a four-byte argument, *ext* being the
967 two most-significant bytes.
Georg Brandl116aa622007-08-15 14:28:22 +0000968
969
970.. opcode:: CALL_FUNCTION_VAR (argc)
971
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500972 Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
973 top element on the stack contains the variable argument list, followed by
974 keyword and positional arguments.
Georg Brandl116aa622007-08-15 14:28:22 +0000975
976
977.. opcode:: CALL_FUNCTION_KW (argc)
978
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500979 Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
980 top element on the stack contains the keyword arguments dictionary, followed
981 by explicit keyword and positional arguments.
Georg Brandl116aa622007-08-15 14:28:22 +0000982
983
984.. opcode:: CALL_FUNCTION_VAR_KW (argc)
985
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500986 Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
987 top element on the stack contains the keyword arguments dictionary, followed
988 by the variable-arguments tuple, followed by explicit keyword and positional
989 arguments.
Georg Brandl116aa622007-08-15 14:28:22 +0000990
991
Georg Brandl4833e5b2010-07-03 10:41:33 +0000992.. opcode:: HAVE_ARGUMENT
Georg Brandl116aa622007-08-15 14:28:22 +0000993
Benjamin Petersonbdf525b2015-03-02 09:31:40 -0500994 This is not really an opcode. It identifies the dividing line between
995 opcodes which don't take arguments ``< HAVE_ARGUMENT`` and those which do
996 ``>= HAVE_ARGUMENT``.
Georg Brandl116aa622007-08-15 14:28:22 +0000997
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000998.. _opcode_collections:
999
1000Opcode collections
1001------------------
1002
1003These collections are provided for automatic introspection of bytecode
1004instructions:
1005
1006.. data:: opname
1007
1008 Sequence of operation names, indexable using the bytecode.
1009
1010
1011.. data:: opmap
1012
1013 Dictionary mapping operation names to bytecodes.
1014
1015
1016.. data:: cmp_op
1017
1018 Sequence of all compare operation names.
1019
1020
1021.. data:: hasconst
1022
1023 Sequence of bytecodes that have a constant parameter.
1024
1025
1026.. data:: hasfree
1027
Benjamin Petersonbdf525b2015-03-02 09:31:40 -05001028 Sequence of bytecodes that access a free variable (note that 'free' in this
1029 context refers to names in the current scope that are referenced by inner
1030 scopes or names in outer scopes that are referenced from this scope. It does
1031 *not* include references to global or builtin scopes).
Nick Coghlanb39fd0c2013-05-06 23:59:20 +10001032
1033
1034.. data:: hasname
1035
1036 Sequence of bytecodes that access an attribute by name.
1037
1038
1039.. data:: hasjrel
1040
1041 Sequence of bytecodes that have a relative jump target.
1042
1043
1044.. data:: hasjabs
1045
1046 Sequence of bytecodes that have an absolute jump target.
1047
1048
1049.. data:: haslocal
1050
1051 Sequence of bytecodes that access a local variable.
1052
1053
1054.. data:: hascompare
1055
1056 Sequence of bytecodes of Boolean operations.