Wrap a data structure, run your algorithm unchanged, and watch every step render in your terminal with the cells you touched highlighted. Reads light up in one colour, writes in another, and each frame shows only what that step touched.

No decorators. No callbacks. No rewriting your solution to fit a framework.

from algoviz import VizList

dp = VizList([0] * 4, title_name='Coin Change')
dp[0] = 1
for coin in (1, 2):
    for value in range(coin, 4):
        dp[value] += dp[value - coin]

Coin Change Init
┏━━━┳━━━┳━━━┳━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃
┡━━━╇━━━╇━━━╇━━━┩
│ 0 │ 0 │ 0 │ 0 │
└───┴───┴───┴───┘
   Coin Change
┏━━━┳━━━┳━━━┳━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃
┡━━━╇━━━╇━━━╇━━━┩
│ 1 │ 0 │ 0 │ 0 │
└───┴───┴───┴───┘

Why

Reading a DP recurrence tells you what the code does. It does not tell you what the table looks like three iterations in, which is where the bug usually is. AlgoViz prints that table on every write, so the state is in front of you instead of in your head.

It is built for the moment you are stuck on a problem, teaching someone who is, or writing up a solution and want the intermediate states to show.

Installation

pip install algoviz

uv add algoviz

Requires Python 3.10 or newer. The only dependency is rich.

Quick start

Every structure takes the data you already have and hands back something that behaves the same way:

from algoviz import VizList, VizStack, VizHeap, VizGrid

VizList([0] * 5)              # 1D and 2D tables
VizStack()                    # LIFO, top always labelled
VizHeap([5, 3, 8], max_heap=True)
VizGrid(['110', '011'])       # terrain plus a visited/queued overlay

The structures

ListNode and TreeNode use the same .val / .next / .left / .right shape LeetCode uses, so existing solutions paste in unchanged.

Implementing it yourself

When the structure is the exercise, the library gets out of the way. Each of these hands you the real nodes so your own code does the walking, and a hook to light up the step you are on:

from algoviz import TrieNode, VizTrie

viz = VizTrie(title_name='Trie')
node = viz.root_node
for char in 'cat':               # your insert, not the library's
    node.children.setdefault(char, TrieNode())
    node = node.children[char]
    viz.visit(node, writing=True)
node.is_word = True

Sizing note for VizTrie. Keep it to roughly a dozen short words. The render is one line per node, and a trie's node count grows with the total number of characters, not the number of words, so 20 words of 5 to 8 letters is already about 62 nodes and fills a terminal in a single frame. The other structures are far less dense: 20 values in a VizHeap is 20 nodes, and in a VizList it is 3 lines. Nothing breaks past that point, it just stops being readable.

Demo gallery

Thirty runnable solutions live in demo/. Every one is executed and checked against the correct answer in CI, so none of them can rot.

Each demo writes its own algorithm. Where the library offers a shortcut that would be the answer, the demo deliberately does not call it: the level-order demo drives its own queue, the top-K demo maintains its own bounded heap, and the trie demo builds its own nodes.

python demo/num_islands.py

Arrays and dynamic programming

Two pointers and prefix sums

Stacks, queues, and deques

Heaps, maps, and sets

Grids, lists, trees, and graphs

Highlights

Two pointers

VizList takes named pointers by index, so the labels track your loop variables and the invariant is visible instead of implied.

from algoviz import VizList

colors = VizList([2, 0, 2, 1, 1, 0], title_name='Sort Colors')
colors.set_pointer('low', 0)
colors.set_pointer('mid', 0)
colors.set_pointer('high', 5)

            Sort Colors
┏━━━━━━━━━━┳━━━┳━━━┳━━━┳━━━┳━━━━━━━┓
┃ 0        ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃ 5     ┃
┡━━━━━━━━━━╇━━━╇━━━╇━━━╇━━━╇━━━━━━━┩
│ 2        │ 0 │ 2 │ 1 │ 1 │ 0     │
│ ↑low,mid │   │   │   │   │ ↑high │
└──────────┴───┴───┴───┴───┴───────┘

A pointer that runs past the end is remembered but not drawn, so loops that terminate by walking off the array need no special-casing.

Stack

The top is always labelled, and a popped value stays visible for exactly one frame so you can see what left.

from algoviz import VizStack

stack = VizStack(title_name='Parens')
for char in '([])':
    stack.push(char) if char in '([' else stack.pop()

       Parens
┏━━━━━━━━━━┳━━━━━━━┓
┃          ┃ value ┃
┡━━━━━━━━━━╇━━━━━━━┩
│ ✗ popped │ [     │
│ ← top    │ (     │
└──────────┴───────┘

Heap

Renders the backing array and the tree it represents, which is the part a flat list never shows you.

from algoviz import VizHeap

heap = VizHeap([5, 3, 8, 1], title_name='Min Heap')
heap.push(2)

      Min Heap
┏━━━┳━━━┳━━━┳━━━┳━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃
┡━━━╇━━━╇━━━╇━━━╇━━━┩
│ 1 │ 2 │ 8 │ 5 │ 3 │
└───┴───┴───┴───┴───┘
Min Heap (tree)
1
├── 2
│   ├── 5
│   └── 3
└── 8

Ordering comes straight from the standard library's heapq, so what you see is the real thing rather than a reimplementation. Pass max_heap=True for a max-heap.

Grid

Grid cells usually hold terrain. What matters is the overlay: which cells are visited, queued, or on the current path.

from algoviz import VizGrid

grid = VizGrid(['11000', '11000', '00100'], title_name='Islands')
grid.mark_start(0, 0)
for row, col in grid.neighbors(0, 0):
    grid.mark_queued(row, col)

neighbors() handles bounds for you, diagonal=True gives all eight, and grid.batch() suspends redrawing so you get one frame per BFS level instead of one per cell.

Linked list

Named pointers make two-pointer and cycle problems legible, and a cyclic list renders its back-edge instead of hanging.

from algoviz import VizLinkedList

linked = VizLinkedList([1, 2, 3, 4, 5])
slow = fast = linked.head
while fast and fast.next:
    slow, fast = slow.next, fast.next.next
    linked.set_pointer('slow', slow)
    linked.set_pointer('fast', fast)

Union-find

Path compression and union by rank are both implemented, and the render shows each element's parent alongside the current components, so you can watch compression flatten the tree.

from algoviz import VizUnionFind

uf = VizUnionFind(5)
uf.union(0, 1)
uf.union(3, 4)
uf.component_count  # 3

Configuration

Every structure accepts the same settings, as keyword overrides or a shared VizConfig:

from algoviz import VizConfig, VizList

VizList([1, 2, 3], get_color='green', set_color='magenta', sleep_time=0.3)

quiet = VizConfig(auto_print=False, show_init=False)
dp = VizList([0] * 5, config=quiet)
dp[2] = 7
dp.show()  # draw only when you ask

Set sleep_time and let it run to get an animation. Set auto_print=False and call .show() yourself to control exactly which frames appear.

Development

This project uses uv.

uv sync             # create the environment
uv run pytest       # 584 tests
uv run pytest --cov # with coverage
uv run ruff check   # lint
uv run ruff format  # format
uv run mypy         # type check
uv build            # build sdist and wheel

CI runs the suite on Python 3.10 through 3.14 across Linux, macOS, and Windows, plus lint, format, types, and a packaging check.

Upgrading from 0.2.x

Version 0.3.0 rewrote the core. Three changes can affect existing code:

1. VizList is a MutableSequence, not a list subclass. It behaves like a list everywhere that matters, but isinstance(dp, list) is now False. The old inheritance was broken regardless: the real list storage was always empty, so anything reading it saw the wrong data. Use dp.data when you need a plain list.
2. a + b no longer mutates a. The old __add__ called extend, so concatenation modified the left operand in place. It now returns a new list, as + should.
3. print(expr) is sandboxed. Expressions still use # for the underlying data, but they evaluate with no builtins and no access to internals.

Python 3.9 users can stay on 0.2.3.

Contributing

Issues and pull requests are welcome. Please run uv run pytest, uv run ruff check, and uv run mypy before opening one. New demos should include their expected output in tests/test_demos.py, which is what keeps the gallery honest.

License

MIT. See LICENSE.txt.