BytecodeAssembler 0.0.1

Generate Python code objects by "assembling" bytecode

This is a simple assembler that handles most low-level bytecode details like jump offsets, stack size tracking, line number table generation, constant and variable name index tracking, etc. That way, you can focus your attention on on the desired semantics of your bytecode instead of on these mechanical issues.

Simple usage:

>>> from peak.util.assembler import Code
>>> c = Code()
>>> c.LOAD_CONST(42)
>>> c.RETURN_VALUE()

>>> eval(c.code())
42

>>> from dis import dis
>>> dis(c.code())
  0           0 LOAD_CONST               0 (42)
              3 RETURN_VALUE

Labels and backpatching forward references:

>>> c = Code()
>>> ref = c.JUMP_ABSOLUTE()     # jump w/unspecified target
>>> c.LOAD_CONST(1)
>>> ref()                       # resolve the forward reference
>>> c.RETURN_VALUE()
>>> dis(c.code())
  0           0 JUMP_ABSOLUTE            6
              3 LOAD_CONST               0 (1)
        >>    6 RETURN_VALUE


>>> c = Code()
>>> lbl = c.label()     # create a label at this point in the code
>>> c.LOAD_CONST(1)
>>> ref = c.JUMP_ABSOLUTE(lbl)  # and jump to it
>>> dis(c.code())
  0     >>    0 LOAD_CONST               0 (1)
              3 JUMP_ABSOLUTE            0

For more examples, see assembler.txt in the peak.util package directory. You can also use codeobject.set_lineno(number) to set the current line number.

There are a few features that aren’t tested yet, and not all opcodes may be fully supported. Notably, the following features are NOT reliably supported yet:

• Closures and cell variables

• Wide jump addressing (for generated bytecode>64K in size)

• The computed stack effects of the MAKE_CLOSURE, MAKE_FUNCTION, END_FINALLY, and POP_BLOCK opcodes may not be correct.

• Line number tables seem to have some problems under Python 2.3, although they work fine in Python 2.4. I don’t yet know whether this is a problem with my code or with the dis module.

If you find any other issues, please let me know.