friendly-dis

A drop-in replacement for Python's dis module that adds human-friendly descriptions to every bytecode instruction.

Installation

pip install friendly-dis

Usage

As a library

import friendly_dis

# Disassemble a string of source code
friendly_dis.dis("x = 1; print(x)")

# Disassemble a function
def example(a, b):
    return a + b

friendly_dis.dis(example)

# Disassemble a code object
code = compile("x = 1", "<test>", "exec")
friendly_dis.disassemble(code)

As a CLI

# Disassemble a file
python -m friendly_dis script.py

# Or via the entry point
friendly-dis script.py

# Disassemble from stdin
echo "x = 1" | python -m friendly_dis

Example output

  0           RESUME                   0         # Internal: resume execution of a code object

  1           LOAD_SMALL_INT           1         # Load small integer 1 onto the stack
              STORE_NAME               0 (x)     # Store top of stack into name 'x'
              LOAD_NAME                1 (print)  # Load name 'print' onto the stack
              PUSH_NULL                          # Push a NULL onto the stack
              LOAD_NAME                0 (x)     # Load name 'x' onto the stack
              CALL                     1         # Call function with 1 argument
              POP_TOP                            # Remove the top of stack
              LOAD_CONST               1 (None)  # Load constant None onto the stack
              RETURN_VALUE                       # Return the top of stack to the caller

API

The module provides the same interface as dis:

• dis(x, *, file=None, depth=None, show_caches=False, adaptive=False) — Disassemble classes, methods, functions, code objects, or source strings.
• disassemble(co, lasti=-1, *, file=None, show_caches=False, adaptive=False) — Disassemble a code object.
• distb(tb=None, *, file=None, show_caches=False, adaptive=False) — Disassemble a traceback.
• describe(opname, arg, argval, argrepr) — Get a human-friendly description for any bytecode instruction.

Compatibility

Supports CPython 3.12+, including 3.14's new opcodes and specialized instructions.

License

MIT

History

This project was created almost entirely by a coding agent, with little human checking. Use at own risk.