blob: a546f68df0977486e56cd645ba4ea3f3f0bd81fb [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
12disassembling it. The CPython bytecode which this module takes as an
Georg Brandl71515ca2009-05-17 12:29:12 +000013input is defined in the file :file:`Include/opcode.h` and used by the compiler
14and the interpreter.
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
Nick Coghlanb39fd0c2013-05-06 23:59:20 +100043The bytecode analysis API allows pieces of Python code to be wrapped in a
44:class:`Bytecode` object that provides easy access to details of the
45compiled code.
46
47.. class:: Bytecode
48
49 The bytecode operations of a piece of code
50
51 This is a convenient wrapper around many of the functions listed below.
52 Instantiate it with a function, method, string of code, or a code object
53 (as returned by :func:`compile`).
54
55 Iterating over this yields the bytecode operations as :class:`Instruction`
56 instances.
57
58 .. data:: codeobj
59
60 The compiled code object.
61
62 .. method:: display_code(*, file=None)
63
64 Print a formatted view of the bytecode operations, like :func:`dis`.
65
66 .. method:: info()
67
68 Return a formatted multi-line string with detailed information about the
69 code object, like :func:`code_info`.
70
71 .. method:: show_info(*, file=None)
72
73 Print the information about the code object as returned by :meth:`info`.
74
75 .. versionadded:: 3.4
76
77Example::
78
79 >>> bytecode = dis.Bytecode(myfunc)
80 >>> for instr in bytecode:
81 ... print(instr.opname)
82 ...
83 LOAD_GLOBAL
84 LOAD_FAST
85 CALL_FUNCTION
86 RETURN_VALUE
87
88
89Analysis functions
90------------------
91
92The :mod:`dis` module also defines the following analysis functions that
93convert the input directly to the desired output. They can be useful if
94only a single operation is being performed, so the intermediate analysis
95object isn't useful:
Georg Brandl116aa622007-08-15 14:28:22 +000096
Nick Coghlane8814fb2010-09-10 14:08:04 +000097.. function:: code_info(x)
Nick Coghlaneae2da12010-08-17 08:03:36 +000098
Georg Brandl67b21b72010-08-17 15:07:14 +000099 Return a formatted multi-line string with detailed code object information
100 for the supplied function, method, source code string or code object.
Nick Coghlaneae2da12010-08-17 08:03:36 +0000101
Georg Brandl67b21b72010-08-17 15:07:14 +0000102 Note that the exact contents of code info strings are highly implementation
103 dependent and they may change arbitrarily across Python VMs or Python
104 releases.
Nick Coghlaneae2da12010-08-17 08:03:36 +0000105
106 .. versionadded:: 3.2
107
Georg Brandl67b21b72010-08-17 15:07:14 +0000108
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000109.. function:: show_code(x, *, file=None)
Nick Coghlane8814fb2010-09-10 14:08:04 +0000110
111 Print detailed code object information for the supplied function, method,
Ezio Melotti6e6c6ac2013-08-23 22:41:39 +0300112 source code string or code object to *file* (or ``sys.stdout`` if *file*
113 is not specified).
Nick Coghlane8814fb2010-09-10 14:08:04 +0000114
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000115 This is a convenient shorthand for ``print(code_info(x), file=file)``,
116 intended for interactive exploration at the interpreter prompt.
Nick Coghlane8814fb2010-09-10 14:08:04 +0000117
118 .. versionadded:: 3.2
119
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000120 .. versionchanged:: 3.4
121 Added ``file`` parameter
122
123
124.. function:: dis(x=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000125
Georg Brandl67b21b72010-08-17 15:07:14 +0000126 Disassemble the *x* object. *x* can denote either a module, a class, a
127 method, a function, a code object, a string of source code or a byte sequence
128 of raw bytecode. For a module, it disassembles all functions. For a class,
129 it disassembles all methods. For a code object or sequence of raw bytecode,
130 it prints one line per bytecode instruction. Strings are first compiled to
131 code objects with the :func:`compile` built-in function before being
132 disassembled. If no object is provided, this function disassembles the last
133 traceback.
Georg Brandl116aa622007-08-15 14:28:22 +0000134
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000135 The disassembly is written as text to the supplied ``file`` argument if
136 provided and to ``sys.stdout`` otherwise.
Georg Brandl116aa622007-08-15 14:28:22 +0000137
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000138 .. versionchanged:: 3.4
139 Added ``file`` parameter
140
141
142.. function:: distb(tb=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000143
Georg Brandl4833e5b2010-07-03 10:41:33 +0000144 Disassemble the top-of-stack function of a traceback, using the last
145 traceback if none was passed. The instruction causing the exception is
146 indicated.
Georg Brandl116aa622007-08-15 14:28:22 +0000147
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000148 The disassembly is written as text to the supplied ``file`` argument if
149 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
152 Added ``file`` parameter
153
154
155.. function:: disassemble(code, lasti=-1, *, file=None)
156 disco(code, lasti=-1, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000157
Georg Brandl4833e5b2010-07-03 10:41:33 +0000158 Disassemble a code object, indicating the last instruction if *lasti* was
Georg Brandl116aa622007-08-15 14:28:22 +0000159 provided. The output is divided in the following columns:
160
161 #. the line number, for the first instruction of each line
162 #. the current instruction, indicated as ``-->``,
163 #. a labelled instruction, indicated with ``>>``,
164 #. the address of the instruction,
165 #. the operation code name,
166 #. operation parameters, and
167 #. interpretation of the parameters in parentheses.
168
169 The parameter interpretation recognizes local and global variable names,
170 constant values, branch targets, and compare operators.
171
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000172 The disassembly is written as text to the supplied ``file`` argument if
173 provided and to ``sys.stdout`` otherwise.
174
175 .. versionchanged:: 3.4
176 Added ``file`` parameter
177
178
179.. function:: get_instructions(x, *, line_offset=0)
180
181 Return an iterator over the instructions in the supplied function, method,
182 source code string or code object.
183
184 The iterator generates a series of :class:`Instruction` named tuples
185 giving the details of each operation in the supplied code.
186
187 The given *line_offset* is added to the ``starts_line`` attribute of any
188 instructions that start a new line.
189
190 .. versionadded:: 3.4
191
Georg Brandl116aa622007-08-15 14:28:22 +0000192
Benjamin Peterson75edad02009-01-01 15:05:06 +0000193.. function:: findlinestarts(code)
194
195 This generator function uses the ``co_firstlineno`` and ``co_lnotab``
196 attributes of the code object *code* to find the offsets which are starts of
197 lines in the source code. They are generated as ``(offset, lineno)`` pairs.
198
199
200.. function:: findlabels(code)
201
202 Detect all offsets in the code object *code* which are jump targets, and
203 return a list of these offsets.
Georg Brandl48310cd2009-01-03 21:18:54 +0000204
Georg Brandl116aa622007-08-15 14:28:22 +0000205.. _bytecodes:
206
Georg Brandl9afde1c2007-11-01 20:32:30 +0000207Python Bytecode Instructions
208----------------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000209
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000210The :func:`get_instructions` function and :class:`Bytecode` class provide
211details of bytecode instructions as :class:`Instruction` instances:
212
213.. class:: Instruction
214
215 Details for a bytecode operation
216
217 .. data:: opcode
218
219 numeric code for operation, corresponding to the opcode values listed
220 below and the bytecode values in the :ref:`opcode_collections`.
221
222
223 .. data:: opname
224
225 human readable name for operation
226
227
228 .. data:: arg
229
230 numeric argument to operation (if any), otherwise None
231
232
233 .. data:: argval
234
235 resolved arg value (if known), otherwise same as arg
236
237
238 .. data:: argrepr
239
240 human readable description of operation argument
241
242
243 .. data:: offset
244
245 start index of operation within bytecode sequence
246
247
248 .. data:: starts_line
249
250 line started by this opcode (if any), otherwise None
251
252
253 .. data:: is_jump_target
254
255 True if other code jumps to here, otherwise False
256
257 .. versionadded:: 3.4
258
259
Georg Brandl9afde1c2007-11-01 20:32:30 +0000260The Python compiler currently generates the following bytecode instructions.
Georg Brandl116aa622007-08-15 14:28:22 +0000261
262
Georg Brandl4833e5b2010-07-03 10:41:33 +0000263**General instructions**
264
Georg Brandl4833e5b2010-07-03 10:41:33 +0000265.. opcode:: NOP
Georg Brandl116aa622007-08-15 14:28:22 +0000266
267 Do nothing code. Used as a placeholder by the bytecode optimizer.
268
269
Georg Brandl4833e5b2010-07-03 10:41:33 +0000270.. opcode:: POP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000271
272 Removes the top-of-stack (TOS) item.
273
274
Georg Brandl4833e5b2010-07-03 10:41:33 +0000275.. opcode:: ROT_TWO
Georg Brandl116aa622007-08-15 14:28:22 +0000276
277 Swaps the two top-most stack items.
278
279
Georg Brandl4833e5b2010-07-03 10:41:33 +0000280.. opcode:: ROT_THREE
Georg Brandl116aa622007-08-15 14:28:22 +0000281
282 Lifts second and third stack item one position up, moves top down to position
283 three.
284
285
Georg Brandl4833e5b2010-07-03 10:41:33 +0000286.. opcode:: DUP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000287
288 Duplicates the reference on top of the stack.
289
Georg Brandl4833e5b2010-07-03 10:41:33 +0000290
Antoine Pitrou74a69fa2010-09-04 18:43:52 +0000291.. opcode:: DUP_TOP_TWO
292
293 Duplicates the two references on top of the stack, leaving them in the
294 same order.
295
296
Georg Brandl4833e5b2010-07-03 10:41:33 +0000297**Unary operations**
298
299Unary operations take the top of the stack, apply the operation, and push the
Georg Brandl116aa622007-08-15 14:28:22 +0000300result back on the stack.
301
Georg Brandl4833e5b2010-07-03 10:41:33 +0000302.. opcode:: UNARY_POSITIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000303
304 Implements ``TOS = +TOS``.
305
306
Georg Brandl4833e5b2010-07-03 10:41:33 +0000307.. opcode:: UNARY_NEGATIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000308
309 Implements ``TOS = -TOS``.
310
311
Georg Brandl4833e5b2010-07-03 10:41:33 +0000312.. opcode:: UNARY_NOT
Georg Brandl116aa622007-08-15 14:28:22 +0000313
314 Implements ``TOS = not TOS``.
315
316
Georg Brandl4833e5b2010-07-03 10:41:33 +0000317.. opcode:: UNARY_INVERT
Georg Brandl116aa622007-08-15 14:28:22 +0000318
319 Implements ``TOS = ~TOS``.
320
321
Georg Brandl4833e5b2010-07-03 10:41:33 +0000322.. opcode:: GET_ITER
Georg Brandl116aa622007-08-15 14:28:22 +0000323
324 Implements ``TOS = iter(TOS)``.
325
Georg Brandl4833e5b2010-07-03 10:41:33 +0000326
327**Binary operations**
328
Georg Brandl116aa622007-08-15 14:28:22 +0000329Binary operations remove the top of the stack (TOS) and the second top-most
330stack item (TOS1) from the stack. They perform the operation, and put the
331result back on the stack.
332
Georg Brandl4833e5b2010-07-03 10:41:33 +0000333.. opcode:: BINARY_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000334
335 Implements ``TOS = TOS1 ** TOS``.
336
337
Georg Brandl4833e5b2010-07-03 10:41:33 +0000338.. opcode:: BINARY_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000339
340 Implements ``TOS = TOS1 * TOS``.
341
342
Georg Brandl4833e5b2010-07-03 10:41:33 +0000343.. opcode:: BINARY_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000344
345 Implements ``TOS = TOS1 // TOS``.
346
347
Georg Brandl4833e5b2010-07-03 10:41:33 +0000348.. opcode:: BINARY_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000349
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000350 Implements ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000351
352
Georg Brandl4833e5b2010-07-03 10:41:33 +0000353.. opcode:: BINARY_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000354
355 Implements ``TOS = TOS1 % TOS``.
356
357
Georg Brandl4833e5b2010-07-03 10:41:33 +0000358.. opcode:: BINARY_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000359
360 Implements ``TOS = TOS1 + TOS``.
361
362
Georg Brandl4833e5b2010-07-03 10:41:33 +0000363.. opcode:: BINARY_SUBTRACT
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_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000369
370 Implements ``TOS = TOS1[TOS]``.
371
372
Georg Brandl4833e5b2010-07-03 10:41:33 +0000373.. opcode:: BINARY_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000374
375 Implements ``TOS = TOS1 << TOS``.
376
377
Georg Brandl4833e5b2010-07-03 10:41:33 +0000378.. opcode:: BINARY_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000379
380 Implements ``TOS = TOS1 >> TOS``.
381
382
Georg Brandl4833e5b2010-07-03 10:41:33 +0000383.. opcode:: BINARY_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000384
385 Implements ``TOS = TOS1 & TOS``.
386
387
Georg Brandl4833e5b2010-07-03 10:41:33 +0000388.. opcode:: BINARY_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000389
390 Implements ``TOS = TOS1 ^ TOS``.
391
392
Georg Brandl4833e5b2010-07-03 10:41:33 +0000393.. opcode:: BINARY_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000394
395 Implements ``TOS = TOS1 | TOS``.
396
Georg Brandl4833e5b2010-07-03 10:41:33 +0000397
398**In-place operations**
399
Georg Brandl116aa622007-08-15 14:28:22 +0000400In-place operations are like binary operations, in that they remove TOS and
401TOS1, and push the result back on the stack, but the operation is done in-place
402when TOS1 supports it, and the resulting TOS may be (but does not have to be)
403the original TOS1.
404
Georg Brandl4833e5b2010-07-03 10:41:33 +0000405.. opcode:: INPLACE_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000406
407 Implements in-place ``TOS = TOS1 ** TOS``.
408
409
Georg Brandl4833e5b2010-07-03 10:41:33 +0000410.. opcode:: INPLACE_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000411
412 Implements in-place ``TOS = TOS1 * TOS``.
413
414
Georg Brandl4833e5b2010-07-03 10:41:33 +0000415.. opcode:: INPLACE_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000416
417 Implements in-place ``TOS = TOS1 // TOS``.
418
419
Georg Brandl4833e5b2010-07-03 10:41:33 +0000420.. opcode:: INPLACE_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000421
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000422 Implements in-place ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000423
424
Georg Brandl4833e5b2010-07-03 10:41:33 +0000425.. opcode:: INPLACE_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000426
427 Implements in-place ``TOS = TOS1 % TOS``.
428
429
Georg Brandl4833e5b2010-07-03 10:41:33 +0000430.. opcode:: INPLACE_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000431
432 Implements in-place ``TOS = TOS1 + TOS``.
433
434
Georg Brandl4833e5b2010-07-03 10:41:33 +0000435.. opcode:: INPLACE_SUBTRACT
Georg Brandl116aa622007-08-15 14:28:22 +0000436
437 Implements in-place ``TOS = TOS1 - TOS``.
438
439
Georg Brandl4833e5b2010-07-03 10:41:33 +0000440.. opcode:: INPLACE_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000441
442 Implements in-place ``TOS = TOS1 << TOS``.
443
444
Georg Brandl4833e5b2010-07-03 10:41:33 +0000445.. opcode:: INPLACE_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000446
447 Implements in-place ``TOS = TOS1 >> TOS``.
448
449
Georg Brandl4833e5b2010-07-03 10:41:33 +0000450.. opcode:: INPLACE_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000451
452 Implements in-place ``TOS = TOS1 & TOS``.
453
454
Georg Brandl4833e5b2010-07-03 10:41:33 +0000455.. opcode:: INPLACE_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000456
457 Implements in-place ``TOS = TOS1 ^ TOS``.
458
459
Georg Brandl4833e5b2010-07-03 10:41:33 +0000460.. opcode:: INPLACE_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000461
462 Implements in-place ``TOS = TOS1 | TOS``.
463
Georg Brandl116aa622007-08-15 14:28:22 +0000464
Georg Brandl4833e5b2010-07-03 10:41:33 +0000465.. opcode:: STORE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000466
467 Implements ``TOS1[TOS] = TOS2``.
468
469
Georg Brandl4833e5b2010-07-03 10:41:33 +0000470.. opcode:: DELETE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000471
472 Implements ``del TOS1[TOS]``.
473
Georg Brandl116aa622007-08-15 14:28:22 +0000474
Georg Brandl4833e5b2010-07-03 10:41:33 +0000475**Miscellaneous opcodes**
Georg Brandl116aa622007-08-15 14:28:22 +0000476
Georg Brandl4833e5b2010-07-03 10:41:33 +0000477.. opcode:: PRINT_EXPR
Georg Brandl116aa622007-08-15 14:28:22 +0000478
479 Implements the expression statement for the interactive mode. TOS is removed
480 from the stack and printed. In non-interactive mode, an expression statement is
481 terminated with ``POP_STACK``.
482
483
Georg Brandl4833e5b2010-07-03 10:41:33 +0000484.. opcode:: BREAK_LOOP
Georg Brandl116aa622007-08-15 14:28:22 +0000485
486 Terminates a loop due to a :keyword:`break` statement.
487
488
489.. opcode:: CONTINUE_LOOP (target)
490
491 Continues a loop due to a :keyword:`continue` statement. *target* is the
492 address to jump to (which should be a ``FOR_ITER`` instruction).
493
494
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000495.. opcode:: SET_ADD (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000496
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000497 Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions.
Georg Brandl116aa622007-08-15 14:28:22 +0000498
499
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000500.. opcode:: LIST_APPEND (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000501
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000502 Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
503
504
505.. opcode:: MAP_ADD (i)
506
507 Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict
508 comprehensions.
509
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000510For all of the SET_ADD, LIST_APPEND and MAP_ADD instructions, while the
511added value or key/value pair is popped off, the container object remains on
512the stack so that it is available for further iterations of the loop.
Georg Brandl116aa622007-08-15 14:28:22 +0000513
514
Georg Brandl4833e5b2010-07-03 10:41:33 +0000515.. opcode:: RETURN_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000516
517 Returns with TOS to the caller of the function.
518
519
Georg Brandl4833e5b2010-07-03 10:41:33 +0000520.. opcode:: YIELD_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000521
Georg Brandl9afde1c2007-11-01 20:32:30 +0000522 Pops ``TOS`` and yields it from a :term:`generator`.
Georg Brandl116aa622007-08-15 14:28:22 +0000523
524
Nick Coghlan1f7ce622012-01-13 21:43:40 +1000525.. opcode:: YIELD_FROM
526
527 Pops ``TOS`` and delegates to it as a subiterator from a :term:`generator`.
528
529 .. versionadded:: 3.3
530
531
Georg Brandl4833e5b2010-07-03 10:41:33 +0000532.. opcode:: IMPORT_STAR
Georg Brandl116aa622007-08-15 14:28:22 +0000533
534 Loads all symbols not starting with ``'_'`` directly from the module TOS to the
535 local namespace. The module is popped after loading all names. This opcode
536 implements ``from module import *``.
537
538
Georg Brandl4833e5b2010-07-03 10:41:33 +0000539.. opcode:: POP_BLOCK
Georg Brandl116aa622007-08-15 14:28:22 +0000540
541 Removes one block from the block stack. Per frame, there is a stack of blocks,
542 denoting nested loops, try statements, and such.
543
544
Georg Brandl4833e5b2010-07-03 10:41:33 +0000545.. opcode:: POP_EXCEPT
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000546
547 Removes one block from the block stack. The popped block must be an exception
548 handler block, as implicitly created when entering an except handler.
549 In addition to popping extraneous values from the frame stack, the
550 last three popped values are used to restore the exception state.
551
552
Georg Brandl4833e5b2010-07-03 10:41:33 +0000553.. opcode:: END_FINALLY
Georg Brandl116aa622007-08-15 14:28:22 +0000554
555 Terminates a :keyword:`finally` clause. The interpreter recalls whether the
556 exception has to be re-raised, or whether the function returns, and continues
557 with the outer-next block.
558
559
Georg Brandl4833e5b2010-07-03 10:41:33 +0000560.. opcode:: LOAD_BUILD_CLASS
Georg Brandl116aa622007-08-15 14:28:22 +0000561
Georg Brandl5ac22302008-07-20 21:39:03 +0000562 Pushes :func:`builtins.__build_class__` onto the stack. It is later called
Benjamin Petersonaac8fd32008-07-20 22:02:26 +0000563 by ``CALL_FUNCTION`` to construct a class.
Georg Brandl116aa622007-08-15 14:28:22 +0000564
Guido van Rossum04110fb2007-08-24 16:32:05 +0000565
Benjamin Peterson876b2f22009-06-28 03:18:59 +0000566.. opcode:: SETUP_WITH (delta)
567
568 This opcode performs several operations before a with block starts. First,
569 it loads :meth:`~object.__exit__` from the context manager and pushes it onto
570 the stack for later use by :opcode:`WITH_CLEANUP`. Then,
571 :meth:`~object.__enter__` is called, and a finally block pointing to *delta*
572 is pushed. Finally, the result of calling the enter method is pushed onto
573 the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
574 store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
575 :opcode:`UNPACK_SEQUENCE`).
576
577
Georg Brandl4833e5b2010-07-03 10:41:33 +0000578.. opcode:: WITH_CLEANUP
Guido van Rossum04110fb2007-08-24 16:32:05 +0000579
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000580 Cleans up the stack when a :keyword:`with` statement block exits. TOS is
581 the context manager's :meth:`__exit__` bound method. Below TOS are 1--3
582 values indicating how/why the finally clause was entered:
Guido van Rossum04110fb2007-08-24 16:32:05 +0000583
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000584 * SECOND = ``None``
585 * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval
586 * SECOND = ``WHY_*``; no retval below it
587 * (SECOND, THIRD, FOURTH) = exc_info()
Guido van Rossum04110fb2007-08-24 16:32:05 +0000588
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000589 In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise
590 ``TOS(None, None, None)``. In addition, TOS is removed from the stack.
Guido van Rossum04110fb2007-08-24 16:32:05 +0000591
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000592 If the stack represents an exception, *and* the function call returns
593 a 'true' value, this information is "zapped" and replaced with a single
594 ``WHY_SILENCED`` to prevent ``END_FINALLY`` from re-raising the exception.
595 (But non-local gotos will still be resumed.)
Guido van Rossum04110fb2007-08-24 16:32:05 +0000596
Georg Brandl9afde1c2007-11-01 20:32:30 +0000597 .. XXX explain the WHY stuff!
598
Guido van Rossum04110fb2007-08-24 16:32:05 +0000599
Georg Brandl116aa622007-08-15 14:28:22 +0000600All of the following opcodes expect arguments. An argument is two bytes, with
601the more significant byte last.
602
Georg Brandl116aa622007-08-15 14:28:22 +0000603.. opcode:: STORE_NAME (namei)
604
605 Implements ``name = TOS``. *namei* is the index of *name* in the attribute
Christian Heimes8640e742008-02-23 16:23:06 +0000606 :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST``
Georg Brandl116aa622007-08-15 14:28:22 +0000607 or ``STORE_GLOBAL`` if possible.
608
609
610.. opcode:: DELETE_NAME (namei)
611
612 Implements ``del name``, where *namei* is the index into :attr:`co_names`
613 attribute of the code object.
614
615
616.. opcode:: UNPACK_SEQUENCE (count)
617
618 Unpacks TOS into *count* individual values, which are put onto the stack
619 right-to-left.
620
Georg Brandl116aa622007-08-15 14:28:22 +0000621
Georg Brandl5ac22302008-07-20 21:39:03 +0000622.. opcode:: UNPACK_EX (counts)
623
624 Implements assignment with a starred target: Unpacks an iterable in TOS into
625 individual values, where the total number of values can be smaller than the
626 number of items in the iterable: one the new values will be a list of all
627 leftover items.
628
629 The low byte of *counts* is the number of values before the list value, the
630 high byte of *counts* the number of values after it. The resulting values
631 are put onto the stack right-to-left.
Georg Brandl48310cd2009-01-03 21:18:54 +0000632
Georg Brandl5ac22302008-07-20 21:39:03 +0000633
Georg Brandl116aa622007-08-15 14:28:22 +0000634.. opcode:: STORE_ATTR (namei)
635
636 Implements ``TOS.name = TOS1``, where *namei* is the index of name in
637 :attr:`co_names`.
638
639
640.. opcode:: DELETE_ATTR (namei)
641
642 Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
643
644
645.. opcode:: STORE_GLOBAL (namei)
646
647 Works as ``STORE_NAME``, but stores the name as a global.
648
649
650.. opcode:: DELETE_GLOBAL (namei)
651
652 Works as ``DELETE_NAME``, but deletes a global name.
653
Georg Brandl116aa622007-08-15 14:28:22 +0000654
655.. opcode:: LOAD_CONST (consti)
656
657 Pushes ``co_consts[consti]`` onto the stack.
658
659
660.. opcode:: LOAD_NAME (namei)
661
662 Pushes the value associated with ``co_names[namei]`` onto the stack.
663
664
665.. opcode:: BUILD_TUPLE (count)
666
667 Creates a tuple consuming *count* items from the stack, and pushes the resulting
668 tuple onto the stack.
669
670
671.. opcode:: BUILD_LIST (count)
672
673 Works as ``BUILD_TUPLE``, but creates a list.
674
675
676.. opcode:: BUILD_SET (count)
677
678 Works as ``BUILD_TUPLE``, but creates a set.
679
680
Christian Heimesa62da1d2008-01-12 19:39:10 +0000681.. opcode:: BUILD_MAP (count)
Georg Brandl116aa622007-08-15 14:28:22 +0000682
Christian Heimesa62da1d2008-01-12 19:39:10 +0000683 Pushes a new dictionary object onto the stack. The dictionary is pre-sized
684 to hold *count* entries.
Georg Brandl116aa622007-08-15 14:28:22 +0000685
686
687.. opcode:: LOAD_ATTR (namei)
688
689 Replaces TOS with ``getattr(TOS, co_names[namei])``.
690
691
692.. opcode:: COMPARE_OP (opname)
693
694 Performs a Boolean operation. The operation name can be found in
695 ``cmp_op[opname]``.
696
697
698.. opcode:: IMPORT_NAME (namei)
699
Christian Heimesa342c012008-04-20 21:01:16 +0000700 Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
701 the *fromlist* and *level* arguments of :func:`__import__`. The module
702 object is pushed onto the stack. The current namespace is not affected:
703 for a proper import statement, a subsequent ``STORE_FAST`` instruction
704 modifies the namespace.
Georg Brandl116aa622007-08-15 14:28:22 +0000705
706
707.. opcode:: IMPORT_FROM (namei)
708
709 Loads the attribute ``co_names[namei]`` from the module found in TOS. The
710 resulting object is pushed onto the stack, to be subsequently stored by a
711 ``STORE_FAST`` instruction.
712
713
714.. opcode:: JUMP_FORWARD (delta)
715
Georg Brandl9afde1c2007-11-01 20:32:30 +0000716 Increments bytecode counter by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000717
718
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000719.. opcode:: POP_JUMP_IF_TRUE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000720
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000721 If TOS is true, sets the bytecode counter to *target*. TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000722
723
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000724.. opcode:: POP_JUMP_IF_FALSE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000725
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000726 If TOS is false, sets the bytecode counter to *target*. TOS is popped.
727
728
729.. opcode:: JUMP_IF_TRUE_OR_POP (target)
730
731 If TOS is true, sets the bytecode counter to *target* and leaves TOS
732 on the stack. Otherwise (TOS is false), TOS is popped.
733
734
735.. opcode:: JUMP_IF_FALSE_OR_POP (target)
736
737 If TOS is false, sets the bytecode counter to *target* and leaves
738 TOS on the stack. Otherwise (TOS is true), TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000739
740
741.. opcode:: JUMP_ABSOLUTE (target)
742
Georg Brandl9afde1c2007-11-01 20:32:30 +0000743 Set bytecode counter to *target*.
Georg Brandl116aa622007-08-15 14:28:22 +0000744
745
746.. opcode:: FOR_ITER (delta)
747
Ezio Melotti7fa82222012-10-12 13:42:08 +0300748 ``TOS`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.
749 If this yields a new value, push it on the stack (leaving the iterator below
750 it). If the iterator indicates it is exhausted ``TOS`` is popped, and the
751 byte code counter is incremented by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000752
Georg Brandl116aa622007-08-15 14:28:22 +0000753
754.. opcode:: LOAD_GLOBAL (namei)
755
756 Loads the global named ``co_names[namei]`` onto the stack.
757
Georg Brandl116aa622007-08-15 14:28:22 +0000758
759.. opcode:: SETUP_LOOP (delta)
760
761 Pushes a block for a loop onto the block stack. The block spans from the
762 current instruction with a size of *delta* bytes.
763
764
765.. opcode:: SETUP_EXCEPT (delta)
766
767 Pushes a try block from a try-except clause onto the block stack. *delta* points
768 to the first except block.
769
770
771.. opcode:: SETUP_FINALLY (delta)
772
773 Pushes a try block from a try-except clause onto the block stack. *delta* points
774 to the finally block.
775
Georg Brandl4833e5b2010-07-03 10:41:33 +0000776.. opcode:: STORE_MAP
Christian Heimesa62da1d2008-01-12 19:39:10 +0000777
778 Store a key and value pair in a dictionary. Pops the key and value while leaving
779 the dictionary on the stack.
Georg Brandl116aa622007-08-15 14:28:22 +0000780
781.. opcode:: LOAD_FAST (var_num)
782
783 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
784
785
786.. opcode:: STORE_FAST (var_num)
787
788 Stores TOS into the local ``co_varnames[var_num]``.
789
790
791.. opcode:: DELETE_FAST (var_num)
792
793 Deletes local ``co_varnames[var_num]``.
794
795
796.. opcode:: LOAD_CLOSURE (i)
797
798 Pushes a reference to the cell contained in slot *i* of the cell and free
799 variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
800 less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
801 len(co_cellvars)]``.
802
803
804.. opcode:: LOAD_DEREF (i)
805
806 Loads the cell contained in slot *i* of the cell and free variable storage.
807 Pushes a reference to the object the cell contains on the stack.
808
809
Benjamin Peterson3b0431d2013-04-30 09:41:40 -0400810.. opcode:: LOAD_CLASSDEREF (i)
811
812 Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
813 consulting the cell. This is used for loading free variables in class
814 bodies.
815
816
Georg Brandl116aa622007-08-15 14:28:22 +0000817.. opcode:: STORE_DEREF (i)
818
819 Stores TOS into the cell contained in slot *i* of the cell and free variable
820 storage.
821
822
Amaury Forgeot d'Arcba117ef2010-09-10 21:39:53 +0000823.. opcode:: DELETE_DEREF (i)
824
825 Empties the cell contained in slot *i* of the cell and free variable storage.
826 Used by the :keyword:`del` statement.
827
828
Georg Brandl116aa622007-08-15 14:28:22 +0000829.. opcode:: RAISE_VARARGS (argc)
830
831 Raises an exception. *argc* indicates the number of parameters to the raise
832 statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
833 the parameter as TOS1, and the exception as TOS.
834
835
836.. opcode:: CALL_FUNCTION (argc)
837
838 Calls a function. The low byte of *argc* indicates the number of positional
839 parameters, the high byte the number of keyword parameters. On the stack, the
840 opcode finds the keyword parameters first. For each keyword argument, the value
841 is on top of the key. Below the keyword parameters, the positional parameters
842 are on the stack, with the right-most parameter on top. Below the parameters,
Georg Brandl48310cd2009-01-03 21:18:54 +0000843 the function object to call is on the stack. Pops all function arguments, and
Benjamin Peterson206e3072008-10-19 14:07:49 +0000844 the function itself off the stack, and pushes the return value.
Georg Brandl116aa622007-08-15 14:28:22 +0000845
846
847.. opcode:: MAKE_FUNCTION (argc)
848
Eli Bendersky60ee0492012-03-24 18:52:45 +0200849 Pushes a new function object on the stack. TOS is the
850 :term:`qualified name` of the function; TOS1 is the code associated with
851 the function. The function object is defined to have *argc* default parameters,
852 which are found below TOS1.
Georg Brandl116aa622007-08-15 14:28:22 +0000853
854
855.. opcode:: MAKE_CLOSURE (argc)
856
Guido van Rossum04110fb2007-08-24 16:32:05 +0000857 Creates a new function object, sets its *__closure__* slot, and pushes it on
Andrew Svetlova5c43092012-11-23 15:28:34 +0200858 the stack. TOS is the :term:`qualified name` of the function, TOS1 is the
859 code associated with the function, and TOS2 is the tuple containing cells for
860 the closure's free variables. The function also has *argc* default parameters,
861 which are found below the cells.
Georg Brandl116aa622007-08-15 14:28:22 +0000862
863
864.. opcode:: BUILD_SLICE (argc)
865
866 .. index:: builtin: slice
867
868 Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
869 ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000870 pushed. See the :func:`slice` built-in function for more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000871
872
873.. opcode:: EXTENDED_ARG (ext)
874
875 Prefixes any opcode which has an argument too big to fit into the default two
876 bytes. *ext* holds two additional bytes which, taken together with the
877 subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
878 most-significant bytes.
879
880
881.. opcode:: CALL_FUNCTION_VAR (argc)
882
883 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
884 on the stack contains the variable argument list, followed by keyword and
885 positional arguments.
886
887
888.. opcode:: CALL_FUNCTION_KW (argc)
889
890 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
891 on the stack contains the keyword arguments dictionary, followed by explicit
892 keyword and positional arguments.
893
894
895.. opcode:: CALL_FUNCTION_VAR_KW (argc)
896
897 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top
898 element on the stack contains the keyword arguments dictionary, followed by the
899 variable-arguments tuple, followed by explicit keyword and positional arguments.
900
901
Georg Brandl4833e5b2010-07-03 10:41:33 +0000902.. opcode:: HAVE_ARGUMENT
Georg Brandl116aa622007-08-15 14:28:22 +0000903
904 This is not really an opcode. It identifies the dividing line between opcodes
905 which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
906 HAVE_ARGUMENT``.
907
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000908.. _opcode_collections:
909
910Opcode collections
911------------------
912
913These collections are provided for automatic introspection of bytecode
914instructions:
915
916.. data:: opname
917
918 Sequence of operation names, indexable using the bytecode.
919
920
921.. data:: opmap
922
923 Dictionary mapping operation names to bytecodes.
924
925
926.. data:: cmp_op
927
928 Sequence of all compare operation names.
929
930
931.. data:: hasconst
932
933 Sequence of bytecodes that have a constant parameter.
934
935
936.. data:: hasfree
937
938 Sequence of bytecodes that access a free variable (note that 'free' in
939 this context refers to names in the current scope that are referenced by
940 inner scopes or names in outer scopes that are referenced from this scope.
941 It does *not* include references to global or builtin scopes).
942
943
944.. data:: hasname
945
946 Sequence of bytecodes that access an attribute by name.
947
948
949.. data:: hasjrel
950
951 Sequence of bytecodes that have a relative jump target.
952
953
954.. data:: hasjabs
955
956 Sequence of bytecodes that have an absolute jump target.
957
958
959.. data:: haslocal
960
961 Sequence of bytecodes that access a local variable.
962
963
964.. data:: hascompare
965
966 Sequence of bytecodes of Boolean operations.