blob: fb669094e832e7abad6f085cf6ae6ff35bb95c10 [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,
112 source code string or code object to stdout.
113
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000114 This is a convenient shorthand for ``print(code_info(x), file=file)``,
115 intended for interactive exploration at the interpreter prompt.
Nick Coghlane8814fb2010-09-10 14:08:04 +0000116
117 .. versionadded:: 3.2
118
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000119 .. versionchanged:: 3.4
120 Added ``file`` parameter
121
122
123.. function:: dis(x=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000124
Georg Brandl67b21b72010-08-17 15:07:14 +0000125 Disassemble the *x* object. *x* can denote either a module, a class, a
126 method, a function, a code object, a string of source code or a byte sequence
127 of raw bytecode. For a module, it disassembles all functions. For a class,
128 it disassembles all methods. For a code object or sequence of raw bytecode,
129 it prints one line per bytecode instruction. Strings are first compiled to
130 code objects with the :func:`compile` built-in function before being
131 disassembled. If no object is provided, this function disassembles the last
132 traceback.
Georg Brandl116aa622007-08-15 14:28:22 +0000133
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000134 The disassembly is written as text to the supplied ``file`` argument if
135 provided and to ``sys.stdout`` otherwise.
Georg Brandl116aa622007-08-15 14:28:22 +0000136
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000137 .. versionchanged:: 3.4
138 Added ``file`` parameter
139
140
141.. function:: distb(tb=None, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000142
Georg Brandl4833e5b2010-07-03 10:41:33 +0000143 Disassemble the top-of-stack function of a traceback, using the last
144 traceback if none was passed. The instruction causing the exception is
145 indicated.
Georg Brandl116aa622007-08-15 14:28:22 +0000146
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000147 The disassembly is written as text to the supplied ``file`` argument if
148 provided and to ``sys.stdout`` otherwise.
Georg Brandl116aa622007-08-15 14:28:22 +0000149
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000150 .. versionchanged:: 3.4
151 Added ``file`` parameter
152
153
154.. function:: disassemble(code, lasti=-1, *, file=None)
155 disco(code, lasti=-1, *, file=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000156
Georg Brandl4833e5b2010-07-03 10:41:33 +0000157 Disassemble a code object, indicating the last instruction if *lasti* was
Georg Brandl116aa622007-08-15 14:28:22 +0000158 provided. The output is divided in the following columns:
159
160 #. the line number, for the first instruction of each line
161 #. the current instruction, indicated as ``-->``,
162 #. a labelled instruction, indicated with ``>>``,
163 #. the address of the instruction,
164 #. the operation code name,
165 #. operation parameters, and
166 #. interpretation of the parameters in parentheses.
167
168 The parameter interpretation recognizes local and global variable names,
169 constant values, branch targets, and compare operators.
170
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000171 The disassembly is written as text to the supplied ``file`` argument if
172 provided and to ``sys.stdout`` otherwise.
173
174 .. versionchanged:: 3.4
175 Added ``file`` parameter
176
177
178.. function:: get_instructions(x, *, line_offset=0)
179
180 Return an iterator over the instructions in the supplied function, method,
181 source code string or code object.
182
183 The iterator generates a series of :class:`Instruction` named tuples
184 giving the details of each operation in the supplied code.
185
186 The given *line_offset* is added to the ``starts_line`` attribute of any
187 instructions that start a new line.
188
189 .. versionadded:: 3.4
190
Georg Brandl116aa622007-08-15 14:28:22 +0000191
Benjamin Peterson75edad02009-01-01 15:05:06 +0000192.. function:: findlinestarts(code)
193
194 This generator function uses the ``co_firstlineno`` and ``co_lnotab``
195 attributes of the code object *code* to find the offsets which are starts of
196 lines in the source code. They are generated as ``(offset, lineno)`` pairs.
197
198
199.. function:: findlabels(code)
200
201 Detect all offsets in the code object *code* which are jump targets, and
202 return a list of these offsets.
Georg Brandl48310cd2009-01-03 21:18:54 +0000203
Georg Brandl116aa622007-08-15 14:28:22 +0000204.. _bytecodes:
205
Georg Brandl9afde1c2007-11-01 20:32:30 +0000206Python Bytecode Instructions
207----------------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000208
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000209The :func:`get_instructions` function and :class:`Bytecode` class provide
210details of bytecode instructions as :class:`Instruction` instances:
211
212.. class:: Instruction
213
214 Details for a bytecode operation
215
216 .. data:: opcode
217
218 numeric code for operation, corresponding to the opcode values listed
219 below and the bytecode values in the :ref:`opcode_collections`.
220
221
222 .. data:: opname
223
224 human readable name for operation
225
226
227 .. data:: arg
228
229 numeric argument to operation (if any), otherwise None
230
231
232 .. data:: argval
233
234 resolved arg value (if known), otherwise same as arg
235
236
237 .. data:: argrepr
238
239 human readable description of operation argument
240
241
242 .. data:: offset
243
244 start index of operation within bytecode sequence
245
246
247 .. data:: starts_line
248
249 line started by this opcode (if any), otherwise None
250
251
252 .. data:: is_jump_target
253
254 True if other code jumps to here, otherwise False
255
256 .. versionadded:: 3.4
257
258
Georg Brandl9afde1c2007-11-01 20:32:30 +0000259The Python compiler currently generates the following bytecode instructions.
Georg Brandl116aa622007-08-15 14:28:22 +0000260
261
Georg Brandl4833e5b2010-07-03 10:41:33 +0000262**General instructions**
263
Georg Brandl4833e5b2010-07-03 10:41:33 +0000264.. opcode:: NOP
Georg Brandl116aa622007-08-15 14:28:22 +0000265
266 Do nothing code. Used as a placeholder by the bytecode optimizer.
267
268
Georg Brandl4833e5b2010-07-03 10:41:33 +0000269.. opcode:: POP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000270
271 Removes the top-of-stack (TOS) item.
272
273
Georg Brandl4833e5b2010-07-03 10:41:33 +0000274.. opcode:: ROT_TWO
Georg Brandl116aa622007-08-15 14:28:22 +0000275
276 Swaps the two top-most stack items.
277
278
Georg Brandl4833e5b2010-07-03 10:41:33 +0000279.. opcode:: ROT_THREE
Georg Brandl116aa622007-08-15 14:28:22 +0000280
281 Lifts second and third stack item one position up, moves top down to position
282 three.
283
284
Georg Brandl4833e5b2010-07-03 10:41:33 +0000285.. opcode:: DUP_TOP
Georg Brandl116aa622007-08-15 14:28:22 +0000286
287 Duplicates the reference on top of the stack.
288
Georg Brandl4833e5b2010-07-03 10:41:33 +0000289
Antoine Pitrou74a69fa2010-09-04 18:43:52 +0000290.. opcode:: DUP_TOP_TWO
291
292 Duplicates the two references on top of the stack, leaving them in the
293 same order.
294
295
Georg Brandl4833e5b2010-07-03 10:41:33 +0000296**Unary operations**
297
298Unary operations take the top of the stack, apply the operation, and push the
Georg Brandl116aa622007-08-15 14:28:22 +0000299result back on the stack.
300
Georg Brandl4833e5b2010-07-03 10:41:33 +0000301.. opcode:: UNARY_POSITIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000302
303 Implements ``TOS = +TOS``.
304
305
Georg Brandl4833e5b2010-07-03 10:41:33 +0000306.. opcode:: UNARY_NEGATIVE
Georg Brandl116aa622007-08-15 14:28:22 +0000307
308 Implements ``TOS = -TOS``.
309
310
Georg Brandl4833e5b2010-07-03 10:41:33 +0000311.. opcode:: UNARY_NOT
Georg Brandl116aa622007-08-15 14:28:22 +0000312
313 Implements ``TOS = not TOS``.
314
315
Georg Brandl4833e5b2010-07-03 10:41:33 +0000316.. opcode:: UNARY_INVERT
Georg Brandl116aa622007-08-15 14:28:22 +0000317
318 Implements ``TOS = ~TOS``.
319
320
Georg Brandl4833e5b2010-07-03 10:41:33 +0000321.. opcode:: GET_ITER
Georg Brandl116aa622007-08-15 14:28:22 +0000322
323 Implements ``TOS = iter(TOS)``.
324
Georg Brandl4833e5b2010-07-03 10:41:33 +0000325
326**Binary operations**
327
Georg Brandl116aa622007-08-15 14:28:22 +0000328Binary operations remove the top of the stack (TOS) and the second top-most
329stack item (TOS1) from the stack. They perform the operation, and put the
330result back on the stack.
331
Georg Brandl4833e5b2010-07-03 10:41:33 +0000332.. opcode:: BINARY_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000333
334 Implements ``TOS = TOS1 ** TOS``.
335
336
Georg Brandl4833e5b2010-07-03 10:41:33 +0000337.. opcode:: BINARY_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000338
339 Implements ``TOS = TOS1 * TOS``.
340
341
Georg Brandl4833e5b2010-07-03 10:41:33 +0000342.. opcode:: BINARY_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000343
344 Implements ``TOS = TOS1 // TOS``.
345
346
Georg Brandl4833e5b2010-07-03 10:41:33 +0000347.. opcode:: BINARY_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000348
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000349 Implements ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000350
351
Georg Brandl4833e5b2010-07-03 10:41:33 +0000352.. opcode:: BINARY_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000353
354 Implements ``TOS = TOS1 % TOS``.
355
356
Georg Brandl4833e5b2010-07-03 10:41:33 +0000357.. opcode:: BINARY_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000358
359 Implements ``TOS = TOS1 + TOS``.
360
361
Georg Brandl4833e5b2010-07-03 10:41:33 +0000362.. opcode:: BINARY_SUBTRACT
Georg Brandl116aa622007-08-15 14:28:22 +0000363
364 Implements ``TOS = TOS1 - TOS``.
365
366
Georg Brandl4833e5b2010-07-03 10:41:33 +0000367.. opcode:: BINARY_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000368
369 Implements ``TOS = TOS1[TOS]``.
370
371
Georg Brandl4833e5b2010-07-03 10:41:33 +0000372.. opcode:: BINARY_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000373
374 Implements ``TOS = TOS1 << TOS``.
375
376
Georg Brandl4833e5b2010-07-03 10:41:33 +0000377.. opcode:: BINARY_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000378
379 Implements ``TOS = TOS1 >> TOS``.
380
381
Georg Brandl4833e5b2010-07-03 10:41:33 +0000382.. opcode:: BINARY_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000383
384 Implements ``TOS = TOS1 & TOS``.
385
386
Georg Brandl4833e5b2010-07-03 10:41:33 +0000387.. opcode:: BINARY_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000388
389 Implements ``TOS = TOS1 ^ TOS``.
390
391
Georg Brandl4833e5b2010-07-03 10:41:33 +0000392.. opcode:: BINARY_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000393
394 Implements ``TOS = TOS1 | TOS``.
395
Georg Brandl4833e5b2010-07-03 10:41:33 +0000396
397**In-place operations**
398
Georg Brandl116aa622007-08-15 14:28:22 +0000399In-place operations are like binary operations, in that they remove TOS and
400TOS1, and push the result back on the stack, but the operation is done in-place
401when TOS1 supports it, and the resulting TOS may be (but does not have to be)
402the original TOS1.
403
Georg Brandl4833e5b2010-07-03 10:41:33 +0000404.. opcode:: INPLACE_POWER
Georg Brandl116aa622007-08-15 14:28:22 +0000405
406 Implements in-place ``TOS = TOS1 ** TOS``.
407
408
Georg Brandl4833e5b2010-07-03 10:41:33 +0000409.. opcode:: INPLACE_MULTIPLY
Georg Brandl116aa622007-08-15 14:28:22 +0000410
411 Implements in-place ``TOS = TOS1 * TOS``.
412
413
Georg Brandl4833e5b2010-07-03 10:41:33 +0000414.. opcode:: INPLACE_FLOOR_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000415
416 Implements in-place ``TOS = TOS1 // TOS``.
417
418
Georg Brandl4833e5b2010-07-03 10:41:33 +0000419.. opcode:: INPLACE_TRUE_DIVIDE
Georg Brandl116aa622007-08-15 14:28:22 +0000420
Ezio Melotti7de0a6e2010-01-05 08:37:27 +0000421 Implements in-place ``TOS = TOS1 / TOS``.
Georg Brandl116aa622007-08-15 14:28:22 +0000422
423
Georg Brandl4833e5b2010-07-03 10:41:33 +0000424.. opcode:: INPLACE_MODULO
Georg Brandl116aa622007-08-15 14:28:22 +0000425
426 Implements in-place ``TOS = TOS1 % TOS``.
427
428
Georg Brandl4833e5b2010-07-03 10:41:33 +0000429.. opcode:: INPLACE_ADD
Georg Brandl116aa622007-08-15 14:28:22 +0000430
431 Implements in-place ``TOS = TOS1 + TOS``.
432
433
Georg Brandl4833e5b2010-07-03 10:41:33 +0000434.. opcode:: INPLACE_SUBTRACT
Georg Brandl116aa622007-08-15 14:28:22 +0000435
436 Implements in-place ``TOS = TOS1 - TOS``.
437
438
Georg Brandl4833e5b2010-07-03 10:41:33 +0000439.. opcode:: INPLACE_LSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000440
441 Implements in-place ``TOS = TOS1 << TOS``.
442
443
Georg Brandl4833e5b2010-07-03 10:41:33 +0000444.. opcode:: INPLACE_RSHIFT
Georg Brandl116aa622007-08-15 14:28:22 +0000445
446 Implements in-place ``TOS = TOS1 >> TOS``.
447
448
Georg Brandl4833e5b2010-07-03 10:41:33 +0000449.. opcode:: INPLACE_AND
Georg Brandl116aa622007-08-15 14:28:22 +0000450
451 Implements in-place ``TOS = TOS1 & TOS``.
452
453
Georg Brandl4833e5b2010-07-03 10:41:33 +0000454.. opcode:: INPLACE_XOR
Georg Brandl116aa622007-08-15 14:28:22 +0000455
456 Implements in-place ``TOS = TOS1 ^ TOS``.
457
458
Georg Brandl4833e5b2010-07-03 10:41:33 +0000459.. opcode:: INPLACE_OR
Georg Brandl116aa622007-08-15 14:28:22 +0000460
461 Implements in-place ``TOS = TOS1 | TOS``.
462
Georg Brandl116aa622007-08-15 14:28:22 +0000463
Georg Brandl4833e5b2010-07-03 10:41:33 +0000464.. opcode:: STORE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000465
466 Implements ``TOS1[TOS] = TOS2``.
467
468
Georg Brandl4833e5b2010-07-03 10:41:33 +0000469.. opcode:: DELETE_SUBSCR
Georg Brandl116aa622007-08-15 14:28:22 +0000470
471 Implements ``del TOS1[TOS]``.
472
Georg Brandl116aa622007-08-15 14:28:22 +0000473
Georg Brandl4833e5b2010-07-03 10:41:33 +0000474**Miscellaneous opcodes**
Georg Brandl116aa622007-08-15 14:28:22 +0000475
Georg Brandl4833e5b2010-07-03 10:41:33 +0000476.. opcode:: PRINT_EXPR
Georg Brandl116aa622007-08-15 14:28:22 +0000477
478 Implements the expression statement for the interactive mode. TOS is removed
479 from the stack and printed. In non-interactive mode, an expression statement is
480 terminated with ``POP_STACK``.
481
482
Georg Brandl4833e5b2010-07-03 10:41:33 +0000483.. opcode:: BREAK_LOOP
Georg Brandl116aa622007-08-15 14:28:22 +0000484
485 Terminates a loop due to a :keyword:`break` statement.
486
487
488.. opcode:: CONTINUE_LOOP (target)
489
490 Continues a loop due to a :keyword:`continue` statement. *target* is the
491 address to jump to (which should be a ``FOR_ITER`` instruction).
492
493
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000494.. opcode:: SET_ADD (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000495
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000496 Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions.
Georg Brandl116aa622007-08-15 14:28:22 +0000497
498
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000499.. opcode:: LIST_APPEND (i)
Georg Brandl116aa622007-08-15 14:28:22 +0000500
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000501 Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
502
503
504.. opcode:: MAP_ADD (i)
505
506 Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict
507 comprehensions.
508
Antoine Pitrouf289ae62008-12-18 11:06:25 +0000509For all of the SET_ADD, LIST_APPEND and MAP_ADD instructions, while the
510added value or key/value pair is popped off, the container object remains on
511the stack so that it is available for further iterations of the loop.
Georg Brandl116aa622007-08-15 14:28:22 +0000512
513
Georg Brandl4833e5b2010-07-03 10:41:33 +0000514.. opcode:: RETURN_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000515
516 Returns with TOS to the caller of the function.
517
518
Georg Brandl4833e5b2010-07-03 10:41:33 +0000519.. opcode:: YIELD_VALUE
Georg Brandl116aa622007-08-15 14:28:22 +0000520
Georg Brandl9afde1c2007-11-01 20:32:30 +0000521 Pops ``TOS`` and yields it from a :term:`generator`.
Georg Brandl116aa622007-08-15 14:28:22 +0000522
523
Nick Coghlan1f7ce622012-01-13 21:43:40 +1000524.. opcode:: YIELD_FROM
525
526 Pops ``TOS`` and delegates to it as a subiterator from a :term:`generator`.
527
528 .. versionadded:: 3.3
529
530
Georg Brandl4833e5b2010-07-03 10:41:33 +0000531.. opcode:: IMPORT_STAR
Georg Brandl116aa622007-08-15 14:28:22 +0000532
533 Loads all symbols not starting with ``'_'`` directly from the module TOS to the
534 local namespace. The module is popped after loading all names. This opcode
535 implements ``from module import *``.
536
537
Georg Brandl4833e5b2010-07-03 10:41:33 +0000538.. opcode:: POP_BLOCK
Georg Brandl116aa622007-08-15 14:28:22 +0000539
540 Removes one block from the block stack. Per frame, there is a stack of blocks,
541 denoting nested loops, try statements, and such.
542
543
Georg Brandl4833e5b2010-07-03 10:41:33 +0000544.. opcode:: POP_EXCEPT
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000545
546 Removes one block from the block stack. The popped block must be an exception
547 handler block, as implicitly created when entering an except handler.
548 In addition to popping extraneous values from the frame stack, the
549 last three popped values are used to restore the exception state.
550
551
Georg Brandl4833e5b2010-07-03 10:41:33 +0000552.. opcode:: END_FINALLY
Georg Brandl116aa622007-08-15 14:28:22 +0000553
554 Terminates a :keyword:`finally` clause. The interpreter recalls whether the
555 exception has to be re-raised, or whether the function returns, and continues
556 with the outer-next block.
557
558
Georg Brandl4833e5b2010-07-03 10:41:33 +0000559.. opcode:: LOAD_BUILD_CLASS
Georg Brandl116aa622007-08-15 14:28:22 +0000560
Georg Brandl5ac22302008-07-20 21:39:03 +0000561 Pushes :func:`builtins.__build_class__` onto the stack. It is later called
Benjamin Petersonaac8fd32008-07-20 22:02:26 +0000562 by ``CALL_FUNCTION`` to construct a class.
Georg Brandl116aa622007-08-15 14:28:22 +0000563
Guido van Rossum04110fb2007-08-24 16:32:05 +0000564
Benjamin Peterson876b2f22009-06-28 03:18:59 +0000565.. opcode:: SETUP_WITH (delta)
566
567 This opcode performs several operations before a with block starts. First,
568 it loads :meth:`~object.__exit__` from the context manager and pushes it onto
569 the stack for later use by :opcode:`WITH_CLEANUP`. Then,
570 :meth:`~object.__enter__` is called, and a finally block pointing to *delta*
571 is pushed. Finally, the result of calling the enter method is pushed onto
572 the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
573 store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
574 :opcode:`UNPACK_SEQUENCE`).
575
576
Georg Brandl4833e5b2010-07-03 10:41:33 +0000577.. opcode:: WITH_CLEANUP
Guido van Rossum04110fb2007-08-24 16:32:05 +0000578
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000579 Cleans up the stack when a :keyword:`with` statement block exits. TOS is
580 the context manager's :meth:`__exit__` bound method. Below TOS are 1--3
581 values indicating how/why the finally clause was entered:
Guido van Rossum04110fb2007-08-24 16:32:05 +0000582
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000583 * SECOND = ``None``
584 * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval
585 * SECOND = ``WHY_*``; no retval below it
586 * (SECOND, THIRD, FOURTH) = exc_info()
Guido van Rossum04110fb2007-08-24 16:32:05 +0000587
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000588 In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise
589 ``TOS(None, None, None)``. In addition, TOS is removed from the stack.
Guido van Rossum04110fb2007-08-24 16:32:05 +0000590
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000591 If the stack represents an exception, *and* the function call returns
592 a 'true' value, this information is "zapped" and replaced with a single
593 ``WHY_SILENCED`` to prevent ``END_FINALLY`` from re-raising the exception.
594 (But non-local gotos will still be resumed.)
Guido van Rossum04110fb2007-08-24 16:32:05 +0000595
Georg Brandl9afde1c2007-11-01 20:32:30 +0000596 .. XXX explain the WHY stuff!
597
Guido van Rossum04110fb2007-08-24 16:32:05 +0000598
Georg Brandl5ac22302008-07-20 21:39:03 +0000599.. opcode:: STORE_LOCALS
600
601 Pops TOS from the stack and stores it as the current frame's ``f_locals``.
602 This is used in class construction.
603
604
Georg Brandl116aa622007-08-15 14:28:22 +0000605All of the following opcodes expect arguments. An argument is two bytes, with
606the more significant byte last.
607
Georg Brandl116aa622007-08-15 14:28:22 +0000608.. opcode:: STORE_NAME (namei)
609
610 Implements ``name = TOS``. *namei* is the index of *name* in the attribute
Christian Heimes8640e742008-02-23 16:23:06 +0000611 :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST``
Georg Brandl116aa622007-08-15 14:28:22 +0000612 or ``STORE_GLOBAL`` if possible.
613
614
615.. opcode:: DELETE_NAME (namei)
616
617 Implements ``del name``, where *namei* is the index into :attr:`co_names`
618 attribute of the code object.
619
620
621.. opcode:: UNPACK_SEQUENCE (count)
622
623 Unpacks TOS into *count* individual values, which are put onto the stack
624 right-to-left.
625
Georg Brandl116aa622007-08-15 14:28:22 +0000626
Georg Brandl5ac22302008-07-20 21:39:03 +0000627.. opcode:: UNPACK_EX (counts)
628
629 Implements assignment with a starred target: Unpacks an iterable in TOS into
630 individual values, where the total number of values can be smaller than the
631 number of items in the iterable: one the new values will be a list of all
632 leftover items.
633
634 The low byte of *counts* is the number of values before the list value, the
635 high byte of *counts* the number of values after it. The resulting values
636 are put onto the stack right-to-left.
Georg Brandl48310cd2009-01-03 21:18:54 +0000637
Georg Brandl5ac22302008-07-20 21:39:03 +0000638
Georg Brandl116aa622007-08-15 14:28:22 +0000639.. opcode:: STORE_ATTR (namei)
640
641 Implements ``TOS.name = TOS1``, where *namei* is the index of name in
642 :attr:`co_names`.
643
644
645.. opcode:: DELETE_ATTR (namei)
646
647 Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
648
649
650.. opcode:: STORE_GLOBAL (namei)
651
652 Works as ``STORE_NAME``, but stores the name as a global.
653
654
655.. opcode:: DELETE_GLOBAL (namei)
656
657 Works as ``DELETE_NAME``, but deletes a global name.
658
Georg Brandl116aa622007-08-15 14:28:22 +0000659
660.. opcode:: LOAD_CONST (consti)
661
662 Pushes ``co_consts[consti]`` onto the stack.
663
664
665.. opcode:: LOAD_NAME (namei)
666
667 Pushes the value associated with ``co_names[namei]`` onto the stack.
668
669
670.. opcode:: BUILD_TUPLE (count)
671
672 Creates a tuple consuming *count* items from the stack, and pushes the resulting
673 tuple onto the stack.
674
675
676.. opcode:: BUILD_LIST (count)
677
678 Works as ``BUILD_TUPLE``, but creates a list.
679
680
681.. opcode:: BUILD_SET (count)
682
683 Works as ``BUILD_TUPLE``, but creates a set.
684
685
Christian Heimesa62da1d2008-01-12 19:39:10 +0000686.. opcode:: BUILD_MAP (count)
Georg Brandl116aa622007-08-15 14:28:22 +0000687
Christian Heimesa62da1d2008-01-12 19:39:10 +0000688 Pushes a new dictionary object onto the stack. The dictionary is pre-sized
689 to hold *count* entries.
Georg Brandl116aa622007-08-15 14:28:22 +0000690
691
692.. opcode:: LOAD_ATTR (namei)
693
694 Replaces TOS with ``getattr(TOS, co_names[namei])``.
695
696
697.. opcode:: COMPARE_OP (opname)
698
699 Performs a Boolean operation. The operation name can be found in
700 ``cmp_op[opname]``.
701
702
703.. opcode:: IMPORT_NAME (namei)
704
Christian Heimesa342c012008-04-20 21:01:16 +0000705 Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
706 the *fromlist* and *level* arguments of :func:`__import__`. The module
707 object is pushed onto the stack. The current namespace is not affected:
708 for a proper import statement, a subsequent ``STORE_FAST`` instruction
709 modifies the namespace.
Georg Brandl116aa622007-08-15 14:28:22 +0000710
711
712.. opcode:: IMPORT_FROM (namei)
713
714 Loads the attribute ``co_names[namei]`` from the module found in TOS. The
715 resulting object is pushed onto the stack, to be subsequently stored by a
716 ``STORE_FAST`` instruction.
717
718
719.. opcode:: JUMP_FORWARD (delta)
720
Georg Brandl9afde1c2007-11-01 20:32:30 +0000721 Increments bytecode counter by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000722
723
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000724.. opcode:: POP_JUMP_IF_TRUE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000725
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000726 If TOS is true, sets the bytecode counter to *target*. TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000727
728
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000729.. opcode:: POP_JUMP_IF_FALSE (target)
Georg Brandl116aa622007-08-15 14:28:22 +0000730
Jeffrey Yasskin9de7ec72009-02-25 02:25:04 +0000731 If TOS is false, sets the bytecode counter to *target*. TOS is popped.
732
733
734.. opcode:: JUMP_IF_TRUE_OR_POP (target)
735
736 If TOS is true, sets the bytecode counter to *target* and leaves TOS
737 on the stack. Otherwise (TOS is false), TOS is popped.
738
739
740.. opcode:: JUMP_IF_FALSE_OR_POP (target)
741
742 If TOS is false, sets the bytecode counter to *target* and leaves
743 TOS on the stack. Otherwise (TOS is true), TOS is popped.
Georg Brandl116aa622007-08-15 14:28:22 +0000744
745
746.. opcode:: JUMP_ABSOLUTE (target)
747
Georg Brandl9afde1c2007-11-01 20:32:30 +0000748 Set bytecode counter to *target*.
Georg Brandl116aa622007-08-15 14:28:22 +0000749
750
751.. opcode:: FOR_ITER (delta)
752
Ezio Melotti7fa82222012-10-12 13:42:08 +0300753 ``TOS`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.
754 If this yields a new value, push it on the stack (leaving the iterator below
755 it). If the iterator indicates it is exhausted ``TOS`` is popped, and the
756 byte code counter is incremented by *delta*.
Georg Brandl116aa622007-08-15 14:28:22 +0000757
Georg Brandl116aa622007-08-15 14:28:22 +0000758
759.. opcode:: LOAD_GLOBAL (namei)
760
761 Loads the global named ``co_names[namei]`` onto the stack.
762
Georg Brandl116aa622007-08-15 14:28:22 +0000763
764.. opcode:: SETUP_LOOP (delta)
765
766 Pushes a block for a loop onto the block stack. The block spans from the
767 current instruction with a size of *delta* bytes.
768
769
770.. opcode:: SETUP_EXCEPT (delta)
771
772 Pushes a try block from a try-except clause onto the block stack. *delta* points
773 to the first except block.
774
775
776.. opcode:: SETUP_FINALLY (delta)
777
778 Pushes a try block from a try-except clause onto the block stack. *delta* points
779 to the finally block.
780
Georg Brandl4833e5b2010-07-03 10:41:33 +0000781.. opcode:: STORE_MAP
Christian Heimesa62da1d2008-01-12 19:39:10 +0000782
783 Store a key and value pair in a dictionary. Pops the key and value while leaving
784 the dictionary on the stack.
Georg Brandl116aa622007-08-15 14:28:22 +0000785
786.. opcode:: LOAD_FAST (var_num)
787
788 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
789
790
791.. opcode:: STORE_FAST (var_num)
792
793 Stores TOS into the local ``co_varnames[var_num]``.
794
795
796.. opcode:: DELETE_FAST (var_num)
797
798 Deletes local ``co_varnames[var_num]``.
799
800
801.. opcode:: LOAD_CLOSURE (i)
802
803 Pushes a reference to the cell contained in slot *i* of the cell and free
804 variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
805 less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
806 len(co_cellvars)]``.
807
808
809.. opcode:: LOAD_DEREF (i)
810
811 Loads the cell contained in slot *i* of the cell and free variable storage.
812 Pushes a reference to the object the cell contains on the stack.
813
814
Benjamin Peterson3b0431d2013-04-30 09:41:40 -0400815.. opcode:: LOAD_CLASSDEREF (i)
816
817 Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
818 consulting the cell. This is used for loading free variables in class
819 bodies.
820
821
Georg Brandl116aa622007-08-15 14:28:22 +0000822.. opcode:: STORE_DEREF (i)
823
824 Stores TOS into the cell contained in slot *i* of the cell and free variable
825 storage.
826
827
Amaury Forgeot d'Arcba117ef2010-09-10 21:39:53 +0000828.. opcode:: DELETE_DEREF (i)
829
830 Empties the cell contained in slot *i* of the cell and free variable storage.
831 Used by the :keyword:`del` statement.
832
833
Georg Brandl116aa622007-08-15 14:28:22 +0000834.. opcode:: RAISE_VARARGS (argc)
835
836 Raises an exception. *argc* indicates the number of parameters to the raise
837 statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
838 the parameter as TOS1, and the exception as TOS.
839
840
841.. opcode:: CALL_FUNCTION (argc)
842
843 Calls a function. The low byte of *argc* indicates the number of positional
844 parameters, the high byte the number of keyword parameters. On the stack, the
845 opcode finds the keyword parameters first. For each keyword argument, the value
846 is on top of the key. Below the keyword parameters, the positional parameters
847 are on the stack, with the right-most parameter on top. Below the parameters,
Georg Brandl48310cd2009-01-03 21:18:54 +0000848 the function object to call is on the stack. Pops all function arguments, and
Benjamin Peterson206e3072008-10-19 14:07:49 +0000849 the function itself off the stack, and pushes the return value.
Georg Brandl116aa622007-08-15 14:28:22 +0000850
851
852.. opcode:: MAKE_FUNCTION (argc)
853
Eli Bendersky60ee0492012-03-24 18:52:45 +0200854 Pushes a new function object on the stack. TOS is the
855 :term:`qualified name` of the function; TOS1 is the code associated with
856 the function. The function object is defined to have *argc* default parameters,
857 which are found below TOS1.
Georg Brandl116aa622007-08-15 14:28:22 +0000858
859
860.. opcode:: MAKE_CLOSURE (argc)
861
Guido van Rossum04110fb2007-08-24 16:32:05 +0000862 Creates a new function object, sets its *__closure__* slot, and pushes it on
Andrew Svetlova5c43092012-11-23 15:28:34 +0200863 the stack. TOS is the :term:`qualified name` of the function, TOS1 is the
864 code associated with the function, and TOS2 is the tuple containing cells for
865 the closure's free variables. The function also has *argc* default parameters,
866 which are found below the cells.
Georg Brandl116aa622007-08-15 14:28:22 +0000867
868
869.. opcode:: BUILD_SLICE (argc)
870
871 .. index:: builtin: slice
872
873 Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
874 ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000875 pushed. See the :func:`slice` built-in function for more information.
Georg Brandl116aa622007-08-15 14:28:22 +0000876
877
878.. opcode:: EXTENDED_ARG (ext)
879
880 Prefixes any opcode which has an argument too big to fit into the default two
881 bytes. *ext* holds two additional bytes which, taken together with the
882 subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
883 most-significant bytes.
884
885
886.. opcode:: CALL_FUNCTION_VAR (argc)
887
888 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
889 on the stack contains the variable argument list, followed by keyword and
890 positional arguments.
891
892
893.. opcode:: CALL_FUNCTION_KW (argc)
894
895 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
896 on the stack contains the keyword arguments dictionary, followed by explicit
897 keyword and positional arguments.
898
899
900.. opcode:: CALL_FUNCTION_VAR_KW (argc)
901
902 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top
903 element on the stack contains the keyword arguments dictionary, followed by the
904 variable-arguments tuple, followed by explicit keyword and positional arguments.
905
906
Georg Brandl4833e5b2010-07-03 10:41:33 +0000907.. opcode:: HAVE_ARGUMENT
Georg Brandl116aa622007-08-15 14:28:22 +0000908
909 This is not really an opcode. It identifies the dividing line between opcodes
910 which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
911 HAVE_ARGUMENT``.
912
Nick Coghlanb39fd0c2013-05-06 23:59:20 +1000913.. _opcode_collections:
914
915Opcode collections
916------------------
917
918These collections are provided for automatic introspection of bytecode
919instructions:
920
921.. data:: opname
922
923 Sequence of operation names, indexable using the bytecode.
924
925
926.. data:: opmap
927
928 Dictionary mapping operation names to bytecodes.
929
930
931.. data:: cmp_op
932
933 Sequence of all compare operation names.
934
935
936.. data:: hasconst
937
938 Sequence of bytecodes that have a constant parameter.
939
940
941.. data:: hasfree
942
943 Sequence of bytecodes that access a free variable (note that 'free' in
944 this context refers to names in the current scope that are referenced by
945 inner scopes or names in outer scopes that are referenced from this scope.
946 It does *not* include references to global or builtin scopes).
947
948
949.. data:: hasname
950
951 Sequence of bytecodes that access an attribute by name.
952
953
954.. data:: hasjrel
955
956 Sequence of bytecodes that have a relative jump target.
957
958
959.. data:: hasjabs
960
961 Sequence of bytecodes that have an absolute jump target.
962
963
964.. data:: haslocal
965
966 Sequence of bytecodes that access a local variable.
967
968
969.. data:: hascompare
970
971 Sequence of bytecodes of Boolean operations.