Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1 | :mod:`dis` --- Disassembler for Python bytecode |
| 2 | =============================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: dis |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 5 | :synopsis: Disassembler for Python bytecode. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | |
| 7 | |
Brett Cannon | b034c75 | 2010-07-21 09:50:42 +0000 | [diff] [blame] | 8 | The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by |
| 9 | disassembling it. The CPython bytecode which this module takes as an |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 10 | input is defined in the file :file:`Include/opcode.h` and used by the compiler |
| 11 | and the interpreter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Brett Cannon | b034c75 | 2010-07-21 09:50:42 +0000 | [diff] [blame] | 13 | .. impl-detail:: |
| 14 | |
| 15 | Bytecode is an implementation detail of the CPython interpreter! No |
| 16 | guarantees are made that bytecode will not be added, removed, or changed |
| 17 | between versions of Python. Use of this module should not be considered to |
| 18 | work across Python VMs or Python releases. |
| 19 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | Example: Given the function :func:`myfunc`:: |
| 21 | |
| 22 | def myfunc(alist): |
| 23 | return len(alist) |
| 24 | |
| 25 | the following command can be used to get the disassembly of :func:`myfunc`:: |
| 26 | |
| 27 | >>> dis.dis(myfunc) |
| 28 | 2 0 LOAD_GLOBAL 0 (len) |
| 29 | 3 LOAD_FAST 0 (alist) |
| 30 | 6 CALL_FUNCTION 1 |
| 31 | 9 RETURN_VALUE |
| 32 | |
| 33 | (The "2" is a line number). |
| 34 | |
| 35 | The :mod:`dis` module defines the following functions and constants: |
| 36 | |
| 37 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 38 | .. function:: dis(x=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 40 | Disassemble the *x* object. *x* can denote either a module, a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | class, a method, a function, or a code object. For a module, it disassembles |
| 42 | all functions. For a class, it disassembles all methods. For a single code |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 43 | sequence, it prints one line per bytecode instruction. If no object is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | provided, it disassembles the last traceback. |
| 45 | |
| 46 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 47 | .. function:: distb(tb=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | Disassembles the top-of-stack function of a traceback, using the last traceback |
| 50 | if none was passed. The instruction causing the exception is indicated. |
| 51 | |
| 52 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 53 | .. function:: disassemble(code, lasti=-1) |
| 54 | disco(code, lasti=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | Disassembles a code object, indicating the last instruction if *lasti* was |
| 57 | provided. The output is divided in the following columns: |
| 58 | |
| 59 | #. the line number, for the first instruction of each line |
| 60 | #. the current instruction, indicated as ``-->``, |
| 61 | #. a labelled instruction, indicated with ``>>``, |
| 62 | #. the address of the instruction, |
| 63 | #. the operation code name, |
| 64 | #. operation parameters, and |
| 65 | #. interpretation of the parameters in parentheses. |
| 66 | |
| 67 | The parameter interpretation recognizes local and global variable names, |
| 68 | constant values, branch targets, and compare operators. |
| 69 | |
| 70 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 71 | .. function:: findlinestarts(code) |
| 72 | |
| 73 | This generator function uses the ``co_firstlineno`` and ``co_lnotab`` |
| 74 | attributes of the code object *code* to find the offsets which are starts of |
| 75 | lines in the source code. They are generated as ``(offset, lineno)`` pairs. |
| 76 | |
| 77 | |
| 78 | .. function:: findlabels(code) |
| 79 | |
| 80 | Detect all offsets in the code object *code* which are jump targets, and |
| 81 | return a list of these offsets. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 82 | |
| 83 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | .. data:: opname |
| 85 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 86 | Sequence of operation names, indexable using the bytecode. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
| 88 | |
| 89 | .. data:: opmap |
| 90 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 91 | Dictionary mapping bytecodes to operation names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
| 94 | .. data:: cmp_op |
| 95 | |
| 96 | Sequence of all compare operation names. |
| 97 | |
| 98 | |
| 99 | .. data:: hasconst |
| 100 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 101 | Sequence of bytecodes that have a constant parameter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | |
| 104 | .. data:: hasfree |
| 105 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 106 | Sequence of bytecodes that access a free variable. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
| 108 | |
| 109 | .. data:: hasname |
| 110 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 111 | Sequence of bytecodes that access an attribute by name. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
| 113 | |
| 114 | .. data:: hasjrel |
| 115 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 116 | Sequence of bytecodes that have a relative jump target. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | |
| 118 | |
| 119 | .. data:: hasjabs |
| 120 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 121 | Sequence of bytecodes that have an absolute jump target. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
| 123 | |
| 124 | .. data:: haslocal |
| 125 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 126 | Sequence of bytecodes that access a local variable. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | |
| 129 | .. data:: hascompare |
| 130 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 131 | Sequence of bytecodes of Boolean operations. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | |
| 134 | .. _bytecodes: |
| 135 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 136 | Python Bytecode Instructions |
| 137 | ---------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 139 | The Python compiler currently generates the following bytecode instructions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | |
| 141 | |
| 142 | .. opcode:: STOP_CODE () |
| 143 | |
| 144 | Indicates end-of-code to the compiler, not used by the interpreter. |
| 145 | |
| 146 | |
| 147 | .. opcode:: NOP () |
| 148 | |
| 149 | Do nothing code. Used as a placeholder by the bytecode optimizer. |
| 150 | |
| 151 | |
| 152 | .. opcode:: POP_TOP () |
| 153 | |
| 154 | Removes the top-of-stack (TOS) item. |
| 155 | |
| 156 | |
| 157 | .. opcode:: ROT_TWO () |
| 158 | |
| 159 | Swaps the two top-most stack items. |
| 160 | |
| 161 | |
| 162 | .. opcode:: ROT_THREE () |
| 163 | |
| 164 | Lifts second and third stack item one position up, moves top down to position |
| 165 | three. |
| 166 | |
| 167 | |
| 168 | .. opcode:: ROT_FOUR () |
| 169 | |
| 170 | Lifts second, third and forth stack item one position up, moves top down to |
| 171 | position four. |
| 172 | |
| 173 | |
| 174 | .. opcode:: DUP_TOP () |
| 175 | |
| 176 | Duplicates the reference on top of the stack. |
| 177 | |
| 178 | Unary Operations take the top of the stack, apply the operation, and push the |
| 179 | result back on the stack. |
| 180 | |
| 181 | |
| 182 | .. opcode:: UNARY_POSITIVE () |
| 183 | |
| 184 | Implements ``TOS = +TOS``. |
| 185 | |
| 186 | |
| 187 | .. opcode:: UNARY_NEGATIVE () |
| 188 | |
| 189 | Implements ``TOS = -TOS``. |
| 190 | |
| 191 | |
| 192 | .. opcode:: UNARY_NOT () |
| 193 | |
| 194 | Implements ``TOS = not TOS``. |
| 195 | |
| 196 | |
| 197 | .. opcode:: UNARY_INVERT () |
| 198 | |
| 199 | Implements ``TOS = ~TOS``. |
| 200 | |
| 201 | |
| 202 | .. opcode:: GET_ITER () |
| 203 | |
| 204 | Implements ``TOS = iter(TOS)``. |
| 205 | |
| 206 | Binary operations remove the top of the stack (TOS) and the second top-most |
| 207 | stack item (TOS1) from the stack. They perform the operation, and put the |
| 208 | result back on the stack. |
| 209 | |
| 210 | |
| 211 | .. opcode:: BINARY_POWER () |
| 212 | |
| 213 | Implements ``TOS = TOS1 ** TOS``. |
| 214 | |
| 215 | |
| 216 | .. opcode:: BINARY_MULTIPLY () |
| 217 | |
| 218 | Implements ``TOS = TOS1 * TOS``. |
| 219 | |
| 220 | |
| 221 | .. opcode:: BINARY_FLOOR_DIVIDE () |
| 222 | |
| 223 | Implements ``TOS = TOS1 // TOS``. |
| 224 | |
| 225 | |
| 226 | .. opcode:: BINARY_TRUE_DIVIDE () |
| 227 | |
Ezio Melotti | 5f7dde1 | 2010-01-05 08:38:30 +0000 | [diff] [blame] | 228 | Implements ``TOS = TOS1 / TOS``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
| 230 | |
| 231 | .. opcode:: BINARY_MODULO () |
| 232 | |
| 233 | Implements ``TOS = TOS1 % TOS``. |
| 234 | |
| 235 | |
| 236 | .. opcode:: BINARY_ADD () |
| 237 | |
| 238 | Implements ``TOS = TOS1 + TOS``. |
| 239 | |
| 240 | |
| 241 | .. opcode:: BINARY_SUBTRACT () |
| 242 | |
| 243 | Implements ``TOS = TOS1 - TOS``. |
| 244 | |
| 245 | |
| 246 | .. opcode:: BINARY_SUBSCR () |
| 247 | |
| 248 | Implements ``TOS = TOS1[TOS]``. |
| 249 | |
| 250 | |
| 251 | .. opcode:: BINARY_LSHIFT () |
| 252 | |
| 253 | Implements ``TOS = TOS1 << TOS``. |
| 254 | |
| 255 | |
| 256 | .. opcode:: BINARY_RSHIFT () |
| 257 | |
| 258 | Implements ``TOS = TOS1 >> TOS``. |
| 259 | |
| 260 | |
| 261 | .. opcode:: BINARY_AND () |
| 262 | |
| 263 | Implements ``TOS = TOS1 & TOS``. |
| 264 | |
| 265 | |
| 266 | .. opcode:: BINARY_XOR () |
| 267 | |
| 268 | Implements ``TOS = TOS1 ^ TOS``. |
| 269 | |
| 270 | |
| 271 | .. opcode:: BINARY_OR () |
| 272 | |
| 273 | Implements ``TOS = TOS1 | TOS``. |
| 274 | |
| 275 | In-place operations are like binary operations, in that they remove TOS and |
| 276 | TOS1, and push the result back on the stack, but the operation is done in-place |
| 277 | when TOS1 supports it, and the resulting TOS may be (but does not have to be) |
| 278 | the original TOS1. |
| 279 | |
| 280 | |
| 281 | .. opcode:: INPLACE_POWER () |
| 282 | |
| 283 | Implements in-place ``TOS = TOS1 ** TOS``. |
| 284 | |
| 285 | |
| 286 | .. opcode:: INPLACE_MULTIPLY () |
| 287 | |
| 288 | Implements in-place ``TOS = TOS1 * TOS``. |
| 289 | |
| 290 | |
| 291 | .. opcode:: INPLACE_FLOOR_DIVIDE () |
| 292 | |
| 293 | Implements in-place ``TOS = TOS1 // TOS``. |
| 294 | |
| 295 | |
| 296 | .. opcode:: INPLACE_TRUE_DIVIDE () |
| 297 | |
Ezio Melotti | 5f7dde1 | 2010-01-05 08:38:30 +0000 | [diff] [blame] | 298 | Implements in-place ``TOS = TOS1 / TOS``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 299 | |
| 300 | |
| 301 | .. opcode:: INPLACE_MODULO () |
| 302 | |
| 303 | Implements in-place ``TOS = TOS1 % TOS``. |
| 304 | |
| 305 | |
| 306 | .. opcode:: INPLACE_ADD () |
| 307 | |
| 308 | Implements in-place ``TOS = TOS1 + TOS``. |
| 309 | |
| 310 | |
| 311 | .. opcode:: INPLACE_SUBTRACT () |
| 312 | |
| 313 | Implements in-place ``TOS = TOS1 - TOS``. |
| 314 | |
| 315 | |
| 316 | .. opcode:: INPLACE_LSHIFT () |
| 317 | |
| 318 | Implements in-place ``TOS = TOS1 << TOS``. |
| 319 | |
| 320 | |
| 321 | .. opcode:: INPLACE_RSHIFT () |
| 322 | |
| 323 | Implements in-place ``TOS = TOS1 >> TOS``. |
| 324 | |
| 325 | |
| 326 | .. opcode:: INPLACE_AND () |
| 327 | |
| 328 | Implements in-place ``TOS = TOS1 & TOS``. |
| 329 | |
| 330 | |
| 331 | .. opcode:: INPLACE_XOR () |
| 332 | |
| 333 | Implements in-place ``TOS = TOS1 ^ TOS``. |
| 334 | |
| 335 | |
| 336 | .. opcode:: INPLACE_OR () |
| 337 | |
| 338 | Implements in-place ``TOS = TOS1 | TOS``. |
| 339 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 340 | |
| 341 | .. opcode:: STORE_SUBSCR () |
| 342 | |
| 343 | Implements ``TOS1[TOS] = TOS2``. |
| 344 | |
| 345 | |
| 346 | .. opcode:: DELETE_SUBSCR () |
| 347 | |
| 348 | Implements ``del TOS1[TOS]``. |
| 349 | |
| 350 | Miscellaneous opcodes. |
| 351 | |
| 352 | |
| 353 | .. opcode:: PRINT_EXPR () |
| 354 | |
| 355 | Implements the expression statement for the interactive mode. TOS is removed |
| 356 | from the stack and printed. In non-interactive mode, an expression statement is |
| 357 | terminated with ``POP_STACK``. |
| 358 | |
| 359 | |
| 360 | .. opcode:: BREAK_LOOP () |
| 361 | |
| 362 | Terminates a loop due to a :keyword:`break` statement. |
| 363 | |
| 364 | |
| 365 | .. opcode:: CONTINUE_LOOP (target) |
| 366 | |
| 367 | Continues a loop due to a :keyword:`continue` statement. *target* is the |
| 368 | address to jump to (which should be a ``FOR_ITER`` instruction). |
| 369 | |
| 370 | |
Antoine Pitrou | f289ae6 | 2008-12-18 11:06:25 +0000 | [diff] [blame] | 371 | .. opcode:: SET_ADD (i) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 372 | |
Antoine Pitrou | f289ae6 | 2008-12-18 11:06:25 +0000 | [diff] [blame] | 373 | Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 374 | |
| 375 | |
Antoine Pitrou | f289ae6 | 2008-12-18 11:06:25 +0000 | [diff] [blame] | 376 | .. opcode:: LIST_APPEND (i) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 377 | |
Antoine Pitrou | f289ae6 | 2008-12-18 11:06:25 +0000 | [diff] [blame] | 378 | Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions. |
| 379 | |
| 380 | |
| 381 | .. opcode:: MAP_ADD (i) |
| 382 | |
| 383 | Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict |
| 384 | comprehensions. |
| 385 | |
| 386 | |
| 387 | For all of the SET_ADD, LIST_APPEND and MAP_ADD instructions, while the |
| 388 | added value or key/value pair is popped off, the container object remains on |
| 389 | the stack so that it is available for further iterations of the loop. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 390 | |
| 391 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 392 | .. opcode:: RETURN_VALUE () |
| 393 | |
| 394 | Returns with TOS to the caller of the function. |
| 395 | |
| 396 | |
| 397 | .. opcode:: YIELD_VALUE () |
| 398 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 399 | Pops ``TOS`` and yields it from a :term:`generator`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 400 | |
| 401 | |
| 402 | .. opcode:: IMPORT_STAR () |
| 403 | |
| 404 | Loads all symbols not starting with ``'_'`` directly from the module TOS to the |
| 405 | local namespace. The module is popped after loading all names. This opcode |
| 406 | implements ``from module import *``. |
| 407 | |
| 408 | |
| 409 | .. opcode:: POP_BLOCK () |
| 410 | |
| 411 | Removes one block from the block stack. Per frame, there is a stack of blocks, |
| 412 | denoting nested loops, try statements, and such. |
| 413 | |
| 414 | |
Benjamin Peterson | eec3d71 | 2008-06-11 15:59:43 +0000 | [diff] [blame] | 415 | .. opcode:: POP_EXCEPT () |
| 416 | |
| 417 | Removes one block from the block stack. The popped block must be an exception |
| 418 | handler block, as implicitly created when entering an except handler. |
| 419 | In addition to popping extraneous values from the frame stack, the |
| 420 | last three popped values are used to restore the exception state. |
| 421 | |
| 422 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 423 | .. opcode:: END_FINALLY () |
| 424 | |
| 425 | Terminates a :keyword:`finally` clause. The interpreter recalls whether the |
| 426 | exception has to be re-raised, or whether the function returns, and continues |
| 427 | with the outer-next block. |
| 428 | |
| 429 | |
Benjamin Peterson | 69164c7 | 2008-07-03 14:45:20 +0000 | [diff] [blame] | 430 | .. opcode:: LOAD_BUILD_CLASS () |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 431 | |
Georg Brandl | 5ac2230 | 2008-07-20 21:39:03 +0000 | [diff] [blame] | 432 | Pushes :func:`builtins.__build_class__` onto the stack. It is later called |
Benjamin Peterson | aac8fd3 | 2008-07-20 22:02:26 +0000 | [diff] [blame] | 433 | by ``CALL_FUNCTION`` to construct a class. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 434 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 435 | |
| 436 | .. opcode:: WITH_CLEANUP () |
| 437 | |
Benjamin Peterson | eec3d71 | 2008-06-11 15:59:43 +0000 | [diff] [blame] | 438 | Cleans up the stack when a :keyword:`with` statement block exits. TOS is |
| 439 | the context manager's :meth:`__exit__` bound method. Below TOS are 1--3 |
| 440 | values indicating how/why the finally clause was entered: |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 441 | |
Benjamin Peterson | eec3d71 | 2008-06-11 15:59:43 +0000 | [diff] [blame] | 442 | * SECOND = ``None`` |
| 443 | * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval |
| 444 | * SECOND = ``WHY_*``; no retval below it |
| 445 | * (SECOND, THIRD, FOURTH) = exc_info() |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 446 | |
Benjamin Peterson | eec3d71 | 2008-06-11 15:59:43 +0000 | [diff] [blame] | 447 | In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise |
| 448 | ``TOS(None, None, None)``. In addition, TOS is removed from the stack. |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 449 | |
Benjamin Peterson | eec3d71 | 2008-06-11 15:59:43 +0000 | [diff] [blame] | 450 | If the stack represents an exception, *and* the function call returns |
| 451 | a 'true' value, this information is "zapped" and replaced with a single |
| 452 | ``WHY_SILENCED`` to prevent ``END_FINALLY`` from re-raising the exception. |
| 453 | (But non-local gotos will still be resumed.) |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 454 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 455 | .. XXX explain the WHY stuff! |
| 456 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 457 | |
Georg Brandl | 5ac2230 | 2008-07-20 21:39:03 +0000 | [diff] [blame] | 458 | .. opcode:: STORE_LOCALS |
| 459 | |
| 460 | Pops TOS from the stack and stores it as the current frame's ``f_locals``. |
| 461 | This is used in class construction. |
| 462 | |
| 463 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 464 | All of the following opcodes expect arguments. An argument is two bytes, with |
| 465 | the more significant byte last. |
| 466 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 467 | .. opcode:: STORE_NAME (namei) |
| 468 | |
| 469 | Implements ``name = TOS``. *namei* is the index of *name* in the attribute |
Christian Heimes | 8640e74 | 2008-02-23 16:23:06 +0000 | [diff] [blame] | 470 | :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST`` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 471 | or ``STORE_GLOBAL`` if possible. |
| 472 | |
| 473 | |
| 474 | .. opcode:: DELETE_NAME (namei) |
| 475 | |
| 476 | Implements ``del name``, where *namei* is the index into :attr:`co_names` |
| 477 | attribute of the code object. |
| 478 | |
| 479 | |
| 480 | .. opcode:: UNPACK_SEQUENCE (count) |
| 481 | |
| 482 | Unpacks TOS into *count* individual values, which are put onto the stack |
| 483 | right-to-left. |
| 484 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 485 | |
Georg Brandl | 5ac2230 | 2008-07-20 21:39:03 +0000 | [diff] [blame] | 486 | .. opcode:: UNPACK_EX (counts) |
| 487 | |
| 488 | Implements assignment with a starred target: Unpacks an iterable in TOS into |
| 489 | individual values, where the total number of values can be smaller than the |
| 490 | number of items in the iterable: one the new values will be a list of all |
| 491 | leftover items. |
| 492 | |
| 493 | The low byte of *counts* is the number of values before the list value, the |
| 494 | high byte of *counts* the number of values after it. The resulting values |
| 495 | are put onto the stack right-to-left. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 496 | |
Georg Brandl | 5ac2230 | 2008-07-20 21:39:03 +0000 | [diff] [blame] | 497 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 498 | .. opcode:: DUP_TOPX (count) |
| 499 | |
| 500 | Duplicate *count* items, keeping them in the same order. Due to implementation |
| 501 | limits, *count* should be between 1 and 5 inclusive. |
| 502 | |
| 503 | |
| 504 | .. opcode:: STORE_ATTR (namei) |
| 505 | |
| 506 | Implements ``TOS.name = TOS1``, where *namei* is the index of name in |
| 507 | :attr:`co_names`. |
| 508 | |
| 509 | |
| 510 | .. opcode:: DELETE_ATTR (namei) |
| 511 | |
| 512 | Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`. |
| 513 | |
| 514 | |
| 515 | .. opcode:: STORE_GLOBAL (namei) |
| 516 | |
| 517 | Works as ``STORE_NAME``, but stores the name as a global. |
| 518 | |
| 519 | |
| 520 | .. opcode:: DELETE_GLOBAL (namei) |
| 521 | |
| 522 | Works as ``DELETE_NAME``, but deletes a global name. |
| 523 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 524 | |
| 525 | .. opcode:: LOAD_CONST (consti) |
| 526 | |
| 527 | Pushes ``co_consts[consti]`` onto the stack. |
| 528 | |
| 529 | |
| 530 | .. opcode:: LOAD_NAME (namei) |
| 531 | |
| 532 | Pushes the value associated with ``co_names[namei]`` onto the stack. |
| 533 | |
| 534 | |
| 535 | .. opcode:: BUILD_TUPLE (count) |
| 536 | |
| 537 | Creates a tuple consuming *count* items from the stack, and pushes the resulting |
| 538 | tuple onto the stack. |
| 539 | |
| 540 | |
| 541 | .. opcode:: BUILD_LIST (count) |
| 542 | |
| 543 | Works as ``BUILD_TUPLE``, but creates a list. |
| 544 | |
| 545 | |
| 546 | .. opcode:: BUILD_SET (count) |
| 547 | |
| 548 | Works as ``BUILD_TUPLE``, but creates a set. |
| 549 | |
| 550 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 551 | .. opcode:: BUILD_MAP (count) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 552 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 553 | Pushes a new dictionary object onto the stack. The dictionary is pre-sized |
| 554 | to hold *count* entries. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 555 | |
| 556 | |
| 557 | .. opcode:: LOAD_ATTR (namei) |
| 558 | |
| 559 | Replaces TOS with ``getattr(TOS, co_names[namei])``. |
| 560 | |
| 561 | |
| 562 | .. opcode:: COMPARE_OP (opname) |
| 563 | |
| 564 | Performs a Boolean operation. The operation name can be found in |
| 565 | ``cmp_op[opname]``. |
| 566 | |
| 567 | |
| 568 | .. opcode:: IMPORT_NAME (namei) |
| 569 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 570 | Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide |
| 571 | the *fromlist* and *level* arguments of :func:`__import__`. The module |
| 572 | object is pushed onto the stack. The current namespace is not affected: |
| 573 | for a proper import statement, a subsequent ``STORE_FAST`` instruction |
| 574 | modifies the namespace. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | |
| 576 | |
| 577 | .. opcode:: IMPORT_FROM (namei) |
| 578 | |
| 579 | Loads the attribute ``co_names[namei]`` from the module found in TOS. The |
| 580 | resulting object is pushed onto the stack, to be subsequently stored by a |
| 581 | ``STORE_FAST`` instruction. |
| 582 | |
| 583 | |
| 584 | .. opcode:: JUMP_FORWARD (delta) |
| 585 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 586 | Increments bytecode counter by *delta*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 587 | |
| 588 | |
Jeffrey Yasskin | 9de7ec7 | 2009-02-25 02:25:04 +0000 | [diff] [blame] | 589 | .. opcode:: POP_JUMP_IF_TRUE (target) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 590 | |
Jeffrey Yasskin | 9de7ec7 | 2009-02-25 02:25:04 +0000 | [diff] [blame] | 591 | If TOS is true, sets the bytecode counter to *target*. TOS is popped. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 592 | |
| 593 | |
Jeffrey Yasskin | 9de7ec7 | 2009-02-25 02:25:04 +0000 | [diff] [blame] | 594 | .. opcode:: POP_JUMP_IF_FALSE (target) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 595 | |
Jeffrey Yasskin | 9de7ec7 | 2009-02-25 02:25:04 +0000 | [diff] [blame] | 596 | If TOS is false, sets the bytecode counter to *target*. TOS is popped. |
| 597 | |
| 598 | |
| 599 | .. opcode:: JUMP_IF_TRUE_OR_POP (target) |
| 600 | |
| 601 | If TOS is true, sets the bytecode counter to *target* and leaves TOS |
| 602 | on the stack. Otherwise (TOS is false), TOS is popped. |
| 603 | |
| 604 | |
| 605 | .. opcode:: JUMP_IF_FALSE_OR_POP (target) |
| 606 | |
| 607 | If TOS is false, sets the bytecode counter to *target* and leaves |
| 608 | TOS on the stack. Otherwise (TOS is true), TOS is popped. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 609 | |
| 610 | |
| 611 | .. opcode:: JUMP_ABSOLUTE (target) |
| 612 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 613 | Set bytecode counter to *target*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 614 | |
| 615 | |
| 616 | .. opcode:: FOR_ITER (delta) |
| 617 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 618 | ``TOS`` is an :term:`iterator`. Call its :meth:`__next__` method. If this |
| 619 | yields a new value, push it on the stack (leaving the iterator below it). If |
| 620 | the iterator indicates it is exhausted ``TOS`` is popped, and the byte code |
| 621 | counter is incremented by *delta*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 622 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 623 | |
| 624 | .. opcode:: LOAD_GLOBAL (namei) |
| 625 | |
| 626 | Loads the global named ``co_names[namei]`` onto the stack. |
| 627 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 628 | |
| 629 | .. opcode:: SETUP_LOOP (delta) |
| 630 | |
| 631 | Pushes a block for a loop onto the block stack. The block spans from the |
| 632 | current instruction with a size of *delta* bytes. |
| 633 | |
| 634 | |
| 635 | .. opcode:: SETUP_EXCEPT (delta) |
| 636 | |
| 637 | Pushes a try block from a try-except clause onto the block stack. *delta* points |
| 638 | to the first except block. |
| 639 | |
| 640 | |
| 641 | .. opcode:: SETUP_FINALLY (delta) |
| 642 | |
| 643 | Pushes a try block from a try-except clause onto the block stack. *delta* points |
| 644 | to the finally block. |
| 645 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 646 | .. opcode:: STORE_MAP () |
| 647 | |
| 648 | Store a key and value pair in a dictionary. Pops the key and value while leaving |
| 649 | the dictionary on the stack. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 650 | |
| 651 | .. opcode:: LOAD_FAST (var_num) |
| 652 | |
| 653 | Pushes a reference to the local ``co_varnames[var_num]`` onto the stack. |
| 654 | |
| 655 | |
| 656 | .. opcode:: STORE_FAST (var_num) |
| 657 | |
| 658 | Stores TOS into the local ``co_varnames[var_num]``. |
| 659 | |
| 660 | |
| 661 | .. opcode:: DELETE_FAST (var_num) |
| 662 | |
| 663 | Deletes local ``co_varnames[var_num]``. |
| 664 | |
| 665 | |
| 666 | .. opcode:: LOAD_CLOSURE (i) |
| 667 | |
| 668 | Pushes a reference to the cell contained in slot *i* of the cell and free |
| 669 | variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is |
| 670 | less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i - |
| 671 | len(co_cellvars)]``. |
| 672 | |
| 673 | |
| 674 | .. opcode:: LOAD_DEREF (i) |
| 675 | |
| 676 | Loads the cell contained in slot *i* of the cell and free variable storage. |
| 677 | Pushes a reference to the object the cell contains on the stack. |
| 678 | |
| 679 | |
| 680 | .. opcode:: STORE_DEREF (i) |
| 681 | |
| 682 | Stores TOS into the cell contained in slot *i* of the cell and free variable |
| 683 | storage. |
| 684 | |
| 685 | |
| 686 | .. opcode:: SET_LINENO (lineno) |
| 687 | |
| 688 | This opcode is obsolete. |
| 689 | |
| 690 | |
| 691 | .. opcode:: RAISE_VARARGS (argc) |
| 692 | |
| 693 | Raises an exception. *argc* indicates the number of parameters to the raise |
| 694 | statement, ranging from 0 to 3. The handler will find the traceback as TOS2, |
| 695 | the parameter as TOS1, and the exception as TOS. |
| 696 | |
| 697 | |
| 698 | .. opcode:: CALL_FUNCTION (argc) |
| 699 | |
| 700 | Calls a function. The low byte of *argc* indicates the number of positional |
| 701 | parameters, the high byte the number of keyword parameters. On the stack, the |
| 702 | opcode finds the keyword parameters first. For each keyword argument, the value |
| 703 | is on top of the key. Below the keyword parameters, the positional parameters |
| 704 | are on the stack, with the right-most parameter on top. Below the parameters, |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 705 | the function object to call is on the stack. Pops all function arguments, and |
Benjamin Peterson | 206e307 | 2008-10-19 14:07:49 +0000 | [diff] [blame] | 706 | the function itself off the stack, and pushes the return value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 707 | |
| 708 | |
| 709 | .. opcode:: MAKE_FUNCTION (argc) |
| 710 | |
| 711 | Pushes a new function object on the stack. TOS is the code associated with the |
| 712 | function. The function object is defined to have *argc* default parameters, |
| 713 | which are found below TOS. |
| 714 | |
| 715 | |
| 716 | .. opcode:: MAKE_CLOSURE (argc) |
| 717 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 718 | Creates a new function object, sets its *__closure__* slot, and pushes it on |
| 719 | the stack. TOS is the code associated with the function, TOS1 the tuple |
| 720 | containing cells for the closure's free variables. The function also has |
| 721 | *argc* default parameters, which are found below the cells. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 722 | |
| 723 | |
| 724 | .. opcode:: BUILD_SLICE (argc) |
| 725 | |
| 726 | .. index:: builtin: slice |
| 727 | |
| 728 | Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, |
| 729 | ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 730 | pushed. See the :func:`slice` built-in function for more information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 731 | |
| 732 | |
| 733 | .. opcode:: EXTENDED_ARG (ext) |
| 734 | |
| 735 | Prefixes any opcode which has an argument too big to fit into the default two |
| 736 | bytes. *ext* holds two additional bytes which, taken together with the |
| 737 | subsequent opcode's argument, comprise a four-byte argument, *ext* being the two |
| 738 | most-significant bytes. |
| 739 | |
| 740 | |
| 741 | .. opcode:: CALL_FUNCTION_VAR (argc) |
| 742 | |
| 743 | Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element |
| 744 | on the stack contains the variable argument list, followed by keyword and |
| 745 | positional arguments. |
| 746 | |
| 747 | |
| 748 | .. opcode:: CALL_FUNCTION_KW (argc) |
| 749 | |
| 750 | Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element |
| 751 | on the stack contains the keyword arguments dictionary, followed by explicit |
| 752 | keyword and positional arguments. |
| 753 | |
| 754 | |
| 755 | .. opcode:: CALL_FUNCTION_VAR_KW (argc) |
| 756 | |
| 757 | Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top |
| 758 | element on the stack contains the keyword arguments dictionary, followed by the |
| 759 | variable-arguments tuple, followed by explicit keyword and positional arguments. |
| 760 | |
| 761 | |
| 762 | .. opcode:: HAVE_ARGUMENT () |
| 763 | |
| 764 | This is not really an opcode. It identifies the dividing line between opcodes |
| 765 | which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>= |
| 766 | HAVE_ARGUMENT``. |
| 767 | |