Metadata-Version: 2.3
Name: friendly-dis
Version: 0.1.0
Summary: Drop-in replacement for stdlib dis with human-friendly instruction descriptions
Author: Luke Plant
Author-email: Luke Plant <luke@lukeplant.me.uk>
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# friendly-dis

A drop-in replacement for Python's [`dis`](https://docs.python.org/3/library/dis.html) module that adds human-friendly descriptions to every bytecode instruction.

## Installation

```bash
pip install friendly-dis
```

## Usage

### As a library

```python
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

```bash
# 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.
