BytecodeAssembler 0.2

Generate Python code objects by

peak.util.assembler is a simple bytecode assembler module that handles most low-level bytecode generation 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 the desired semantics of your bytecode instead of on these mechanical issues.

In addition to a low-level opcode-oriented API for directly generating specific bytecodes, this module also offers an extensible mini-AST framework for generating code from high-level specifications. This framework does most of the work needed to transform tree-like structures into linear bytecode instructions, and includes the ability to do compile-time constant folding.

Changes since version 0.1:

• Constant handling has been fixed so that it doesn’t confuse equal values of differing types (e.g. 1.0 and True), or equal unhashable objects (e.g. two empty lists).

• Removed nil, ast_curry() and folding_curry(), replacing them with the nodetype() decorator and fold_args(); please see the docs for more details.

• Added stack tracking across jumps, globally verifying stack level prediction consistency and automatically rejecting attempts to generate dead code. It should now be virtually impossible to accidentally generate bytecode that can crash the interpreter. (If you find a way, let me know!)

Changes since version 0.0.1:

• Added massive quantities of new documentation and examples

• Full block, loop, and closure support

• High-level functional code generation from trees, with smart labels and blocks, constant folding, extensibility, smart local variable names, etc.

• The .label() method was renamed to .here() to distinguish it from the new smart Label objects.

• Docs and tests were moved to README.txt instead of assembler.txt

• Added a demo that implements a “switch”-like statement template that shows how to extend the code generation system and how to abuse END_FINALLY to implement a “computed goto” in bytecode.

• Various bug fixes

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

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

• The dis() module in Python 2.3 has a bug that makes it show incorrect line numbers when the difference between two adjacent line numbers is greater than 255. This causes two shallow failures in the current test suite when it’s run under Python 2.3.

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

Please also keep in mind that this is a work in progress, and the API may change if I come up with a better way to do something.

Questions and discussion regarding this software should be directed to the PEAK Mailing List.