PageRenderTime 80ms CodeModel.GetById 32ms app.highlight 42ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/library/dis.rst

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