Skip to content

Status & roadmap

KlorPy is a working vertical slice of choreographic programming in Python, built roadmap-item by roadmap-item against the Klor (Clojure) original. It is not a production library — it is a documented, tested prototype.

Status

  • 47 tests passing — tests/test_core.py, test_tuples.py, test_loops.py, test_sockets.py, test_check.py.
  • Runnable demos — examples.py (one process), examples_network.py (two OS processes over TCP).
  • The package installs via pyproject.toml (stdlib-only runtime; pytest as a dev extra).

What's done

# Item Where
1 Per-role parameter binding / erasure (x: A) Types, Choreography.bind_param
2 pack/unpack, (A, B) tuples, tuple returns Operators
3 Universal-agreement if + match/case Choice
4 Lockstep while loops Loops
5 Static location type checker Types, klorpy.check
6 Real TCP transport Networking
7 Subset-decided (broadcast) while + break/continue Loops

Remaining (additive conveniences)

  • defchor forward-declaration / mutual recursion (higher-order choreography values).
  • agree! — programmer-declared agreement between roles (Klor's documented unsafe escape hatch).
  • Richer match patterns (guards, OR/structure patterns), for sugar.

None of these are control-flow gaps; the language is coherent without them.

No mypy plugin

The roadmap originally floated surfacing the type checker through a mypy plugin. We deliberately built a plain pass (klorpy.check) instead:

  • a DSL embedded in a decorated function defeats mypy's per-function analysis — a plugin could not inspect the choreography body reliably;
  • the location invariants (agreement lattice, knowledge-of-choice, branch/loop/ return consistency) are not expressible in mypy's structural type model;
  • myself more value would be fragile machinery for marginal user value.

The checker operates on the analyzed AST, runs at definition time, and has its own tests.

Building this documentation

The site you are reading is generated by Zensical, a modern static-site generator (mkdocs-material compatible).

$ cd prototype/python
$ zensical build        # static site -> ./site
$ zensical serve        # live preview at http://localhost:8000

Configuration lives in zensical.toml; sources are the Markdown files under docs/; navigation is explicit in zensical.toml under [project] nav.