Python Bytecode Generator and Modifier

Common errors

• ModuleNotFoundError: No module named 'bytecode'

  cause The 'bytecode' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.
  fix Install the library using pip: `pip install bytecode`

• AttributeError: module 'bytecode' has no attribute 'BinaryOp'

  cause This error typically occurs when using an older version of the 'bytecode' library that does not include the 'BinaryOp' enum, which was introduced in version 0.14.0.
  fix Upgrade the 'bytecode' library to a version 0.14.0 or newer: `pip install --upgrade bytecode`

• TypeError: operation LOAD_ATTR argument must be a str, got tuple

  cause This `TypeError` indicates an incompatibility between the 'bytecode' library version and the Python version being used (e.g., Python 3.12), where certain bytecode operations expect a string argument but receive a tuple due to changes in how bytecode is handled.
  fix Ensure you are using a version of 'bytecode' that is compatible with your Python interpreter version. Upgrading 'bytecode' often resolves such issues: `pip install --upgrade bytecode`

Warnings

• breaking The structure of Python bytecode is an internal implementation detail of CPython and can change significantly between major Python versions. While `bytecode` aims to abstract this, code built for one Python version may behave differently or break on another due to underlying CPython changes, especially when generating bytecode that isn't fully generic.
  Fix: Always test bytecode generation and modification across all target Python versions. Utilize `bytecode`'s version-aware features and abstractions where possible, rather than relying on raw opcode values specific to one Python version.
• breaking The `bytecode` library's API has undergone changes to accommodate new CPython bytecode formats and features, particularly with Python 3.11, 3.13, and 3.14 support. For example, `BaseInstr` was removed and `Instr` became the base class in 0.17.0, and new enums are now used for certain opcode arguments (e.g., `BINARY_OP`, `CONVERT_VALUE`).
  Fix: Review the `bytecode` changelog for each major release, especially when upgrading or targeting newer Python versions. Adapt your code to use the latest API, such as replacing `BaseInstr` with `Instr` and using enum members for opcode arguments where required.
• gotcha Direct manipulation of bytecode is a low-level operation and requires a deep understanding of the Python Virtual Machine's stack-based execution model, opcode semantics, and operand types. Misinterpreting stack effects or opcode arguments can lead to incorrect or crashing bytecode.
  Fix: Consult the `dis` module's documentation for the target Python version to understand opcode behavior. Start with simple bytecode structures and progressively build complexity, frequently testing the generated code. Use `dis.dis()` on simple Python functions to see how CPython compiles them into bytecode as a reference.

Install

• pip install bytecode Install latest version

Imports

• Bytecode

  from bytecode import Bytecode

• Instr

  from bytecode import Instr

• ConcreteBytecode

  from bytecode import ConcreteBytecode

• ControlFlowGraph

  from bytecode import ControlFlowGraph

Quickstart

This quickstart demonstrates how to create a simple `Bytecode` object using `Instr` instances, convert it to a standard Python code object, and then execute it to print 'Hello World!'.

from bytecode import Instr, Bytecode

# Create bytecode for print('Hello World!')
bytecode_obj = Bytecode([
    Instr('LOAD_GLOBAL', (True, 'print')), # Load the global 'print' function
    Instr('LOAD_CONST', 'Hello World!'), # Load the string 'Hello World!'
    Instr('CALL', 1), # Call 'print' with 1 argument
    Instr('POP_TOP'), # Pop the return value (None) from the stack
    Instr('LOAD_CONST', None), # Load None
    Instr('RETURN_VALUE') # Return None
])

# Convert the bytecode object to a CPython code object
code = bytecode_obj.to_code()

# Execute the generated code
exec(code)