concurim 0.1.0__tar.gz

concurim-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+node_modules/
+frontend/test-results/
+frontend/playwright-report/
+*.concurim
+!tests/fixtures/*.concurim
+!src/concurim/samples/*.concurim
+.env

concurim-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First vertical slice, then the GUI-first milestone, then locks, pools and
+asyncio.
+
+- The home screen shows the logo beside the name.
+- The home screen groups examples into short lists. The home screen
+  and the player link to the GitHub repository. The README leads with
+  the commands.
+- A short guide in `docs/`: getting started, concepts, recording,
+  reading a run, and which example to open.
+- Barriers (`threading` and `asyncio`): who has arrived, the release
+  when the party is complete, and abort or reset. The home screen includes
+  a three-worker example.
+- A program that does not compile is refused before it starts. A run that
+  gets stuck still leaves a trace: the buffer is flushed about once a second
+  and again on SIGINT or SIGTERM, and the viewer says who is still waiting
+  on locks one another holds. `concurim record --open` opens that picture.
+  Packaging metadata is ready for PyPI; 0.1.0 has not been uploaded.
+- Events and conditions (`threading` and `asyncio`), `asyncio.TaskGroup`,
+  `multiprocessing` `Pool` and `Process` (copied versus shared arguments),
+  and `Future.cancel()`, callbacks and `as_completed` for thread pools.
+- Viewer: **Lineage** tab, **Resources** layout, `concurim compare` (side by
+  side, GIL on/off, facts only), and `concurim export` (mp4/webm/gif/PNG,
+  deterministic frames with smooth, reproducible motion, optional
+  `concurim[video]` for ffmpeg), plus an **Export…** dialog in the viewer,
+  with an optional logo watermark in the top-left.
+- Observability levels `sync` (`threading.Lock/RLock/Semaphore/
+  BoundedSemaphore`, `ThreadPoolExecutor`) and `asyncio` (tasks, `Queue`,
+  `Lock`, `Semaphore`); managed `TracedLock`, `TracedRLock`,
+  `TracedSemaphore`, `TracedBoundedSemaphore`, `TracedThreadPoolExecutor`,
+  `TracedAsync*`. Replay explains who holds or waits for each lock; asyncio
+  tasks are drawn like threads; executors like queues of tasks.
+- `ProcessPoolExecutor` (auto at `sync`, managed `TracedProcessPoolExecutor`):
+  workers appear as processes; example `process-pool`.
+- Code view: a task that has just started shades its **whole function body**,
+  and a background sampler (`sample_interval_ms`, with source included) then
+  follows the line each thread, asyncio task and pool worker is on (shown `≈`,
+  approximate).
+- Viewer: **fullscreen** animation with media-style controls (`z`), a **Code**
+  mode lighting each busy worker's line in its item's colour, and a layout
+  polish (orbs inside nodes, no overflowing text).
+- Five more examples (lock contention, semaphore, thread pool, asyncio tasks,
+  asyncio queue); queue items now keep their identity at `queues`.
+- **Group workers** and `×N` folding of repeating log events.
+- Viewer split into two chunks (home ~316 kB, viewer ~223 kB).
+- CI: free-threaded 3.14t, and an experimental Windows job.
+
+- Home screen: drop a `.concurim` trace, `.py` file or project folder; bundled
+  examples; explicit, reviewable "Record execution" with cancel and exit codes.
+- Zero-code recording levels (`--auto none|threads|queues`), reversible.
+- React Flow canvas with draggable, remembered layout; Motion-animated item
+  tokens; Animation/Timeline views over one recording; pacing modes; jumps.
+- Local server: per-launch token on all POSTs, Origin/Host checks, body
+  limits, private scratch workspaces.
+- Examples moved to `src/concurim/samples` (recordings ship in the wheel).
+
+- `TracedQueue` (`queue.Queue` subclass), `TracedThread`, `work()` spans,
+  explicit lineage, `record()` API.
+- `.concurim` trace format with JSON Schema, bounded buffer, truncation flag,
+  optional embedded source and payload previews.
+- Replay engine with per-event state, blocking/join/shutdown handling, and
+  rule-based explanations that separate observed from inferred.
+- Local viewer: animated producer/queue/consumer canvas, timeline with
+  spans and occupancy, playback controls, source panel, inspector, event log.
+- CLI: `record`, `view`, `demo`, `inspect`.

concurim-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Thanks for helping! Concurim values **accuracy over spectacle**: a visualization
+must follow recorded events, and anything inferred must be labelled.
+
+## Setup
+
+```bash
+uv sync
+uv run pytest && uv run ruff check . && uv run ruff format --check . \
+  && uv run ty check src
+cd frontend && npm ci && npm test
+```
+
+The compiled viewer lives in `src/concurim/viewer/static` and is committed so
+the package works without Node. After frontend changes run
+`scripts/build.sh` and commit the result (CI fails if it is stale).
+Regenerate frontend fixtures with `uv run python scripts/make_fixtures.py`
+(real capture; then refresh Playwright snapshots with
+`npx playwright test --update-snapshots`).
+
+## Adding an instrumented primitive
+
+1. Add event types in `recorder/events.py` and to the JSON Schema.
+2. Wrap the primitive in `instrumentation/`. Emit state-changing events at the
+   point where the real state changes (under the primitive's own lock if the
+   primitive offers a hook); use `mark_internal(__file__)` for source
+   attribution; never take locks that could invert with the collector's.
+3. Add a reducer handler in `replay/state.py` and a rule in `replay/rules_*.py`.
+4. Test with real threads. Never assert one incidental interleaving; assert
+   invariants and use events/barriers to force the situation you test.
+5. Update `docs/limitations.md`.
+
+## Style
+
+Google style, 80 columns (hard limit 100), a short docstring per function,
+files under ~300 lines (split before they grow), no duplicated logic.
+Prefer the simplest design; do not add dependencies lightly (runtime
+dependencies are currently zero).
+
+## Publishing
+
+0.1.0 is not on PyPI yet. The `pyproject.toml` metadata (SPDX license,
+readme, classifiers, project URLs, the `concurim` script) is what the
+upload will use. From a clean tree, after `scripts/build.sh`:
+
+```bash
+uv build
+uvx twine check dist/*
+```
+
+Upload only when cutting the release. Do not upload from a dirty tree, and
+do not upload over an existing version: PyPI rejects a repeated version.
+
+```bash
+uvx twine upload dist/*
+```
+
+Install paths once that version is on PyPI: `uvx concurim` (home screen;
+the server copies itself onto the interpreter you pick) and
+`uv add --dev concurim` when `concurim record` must import the project.
+
+## Frontend development note
+
+`npm run dev` proxies `/api` to the server, but POST features (opening
+examples, dropping files, running programs) fail there: they need the
+per-launch token the real server embeds only in the HTML it serves. For those, run `npm run build` and use `uv run concurim`.
+Playwright starts two servers (`concurim demo` on 8799, the home screen on
+8798) via `uv run`.

concurim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Concurim contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

concurim-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: concurim
+Version: 0.1.0
+Summary: See how Python runs together: record and replay concurrent execution.
+Project-URL: Homepage, https://github.com/ej-sanmartin/concurim
+Project-URL: Documentation, https://github.com/ej-sanmartin/concurim/blob/main/docs/index.md
+Project-URL: Source, https://github.com/ej-sanmartin/concurim
+Project-URL: Issues, https://github.com/ej-sanmartin/concurim/issues
+Project-URL: Changelog, https://github.com/ej-sanmartin/concurim/blob/main/CHANGELOG.md
+Author: Concurim contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,concurrency,debugging,observability,queue,threading,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Provides-Extra: video
+Requires-Dist: imageio-ffmpeg>=0.5; extra == 'video'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/images/logo.png" alt="Concurim" width="200"/>
+</p>
+
+# Concurim
+
+**See how Python runs together.** Concurim records what your threads and
+asyncio tasks actually do, then replays that one run as an animation.
+
+## Setup
+
+From a checkout. After 0.1.0 is on PyPI, `uvx concurim` opens the same
+home screen.
+
+```bash
+git clone https://github.com/ej-sanmartin/concurim.git
+cd concurim
+uv sync
+
+uv run concurim
+uv run concurim demo
+uv run concurim record --open --auto sync my_app.py
+uv run concurim record --open --include-source -o run.concurim my_app.py arg1
+uv run concurim view run.concurim
+uv run concurim inspect run.concurim
+uv run concurim compare one.concurim two.concurim
+uv run concurim export run.concurim -o clip.mp4 --events 5:40
+```
+
+`uv run concurim` opens the page. Drop a `.py` file or a folder, read the
+plan, then click **Record execution**. Drop a `.concurim` file, or open
+an example, and nothing runs. Options on `record` come before the script.
+`uvx concurim record` cannot import a project's packages; install it
+there with `uv add --dev concurim` and use `uv run`.
+
+![Concurim viewer, dark theme](docs/images/viewer-dark.png)
+
+*A recording of [`threaded_pipeline.py`](src/concurim/samples/threaded_pipeline.py)
+(event 41 of 120): two producers and two consumers share a queue of
+capacity 3.*
+
+> **Status: 0.1 (alpha).** Not on PyPI yet. Threads, queues, locks,
+> events, barriers, pools, and asyncio are included.
+> [What is and is not observed](docs/limitations.md).
+
+## Guide
+
+| | |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | The page, the commands, a stuck run |
+| [Concepts](docs/concepts.md) | One schedule, observed versus inferred, what you can trust |
+| [Recording](docs/recording.md) | Home screen, `--auto`, `record()`, `Traced*` |
+| [Reading a run](docs/reading-a-run.md) | Animation, Code, Timeline, compare, export |
+| [Teaching](docs/teaching.md) | Which example to open |
+| [Cost](docs/cost.md) | Overhead of recording |
+| [Limitations](docs/limitations.md) | Caveats |
+| [Trace format](docs/trace-format.md) | The `.concurim` file |
+| [Security](SECURITY.md) | Local only. Review a trace before sharing it |
+| [Contributing](CONTRIBUTING.md) | Tests, style, publishing |
+| [Changelog](CHANGELOG.md) | What 0.1.0 contains |
+
+The viewer binds `127.0.0.1` and has no telemetry. Source and payload
+previews are off unless you ask for them.
+
+MIT licensed.

concurim-0.1.0/README.md

@@ -0,0 +1,65 @@
+<p align="center">
+  <img src="docs/images/logo.png" alt="Concurim" width="200"/>
+</p>
+
+# Concurim
+
+**See how Python runs together.** Concurim records what your threads and
+asyncio tasks actually do, then replays that one run as an animation.
+
+## Setup
+
+From a checkout. After 0.1.0 is on PyPI, `uvx concurim` opens the same
+home screen.
+
+```bash
+git clone https://github.com/ej-sanmartin/concurim.git
+cd concurim
+uv sync
+
+uv run concurim
+uv run concurim demo
+uv run concurim record --open --auto sync my_app.py
+uv run concurim record --open --include-source -o run.concurim my_app.py arg1
+uv run concurim view run.concurim
+uv run concurim inspect run.concurim
+uv run concurim compare one.concurim two.concurim
+uv run concurim export run.concurim -o clip.mp4 --events 5:40
+```
+
+`uv run concurim` opens the page. Drop a `.py` file or a folder, read the
+plan, then click **Record execution**. Drop a `.concurim` file, or open
+an example, and nothing runs. Options on `record` come before the script.
+`uvx concurim record` cannot import a project's packages; install it
+there with `uv add --dev concurim` and use `uv run`.
+
+![Concurim viewer, dark theme](docs/images/viewer-dark.png)
+
+*A recording of [`threaded_pipeline.py`](src/concurim/samples/threaded_pipeline.py)
+(event 41 of 120): two producers and two consumers share a queue of
+capacity 3.*
+
+> **Status: 0.1 (alpha).** Not on PyPI yet. Threads, queues, locks,
+> events, barriers, pools, and asyncio are included.
+> [What is and is not observed](docs/limitations.md).
+
+## Guide
+
+| | |
+| --- | --- |
+| [Getting started](docs/getting-started.md) | The page, the commands, a stuck run |
+| [Concepts](docs/concepts.md) | One schedule, observed versus inferred, what you can trust |
+| [Recording](docs/recording.md) | Home screen, `--auto`, `record()`, `Traced*` |
+| [Reading a run](docs/reading-a-run.md) | Animation, Code, Timeline, compare, export |
+| [Teaching](docs/teaching.md) | Which example to open |
+| [Cost](docs/cost.md) | Overhead of recording |
+| [Limitations](docs/limitations.md) | Caveats |
+| [Trace format](docs/trace-format.md) | The `.concurim` file |
+| [Security](SECURITY.md) | Local only. Review a trace before sharing it |
+| [Contributing](CONTRIBUTING.md) | Tests, style, publishing |
+| [Changelog](CHANGELOG.md) | What 0.1.0 contains |
+
+The viewer binds `127.0.0.1` and has no telemetry. Source and payload
+previews are off unless you ask for them.
+
+MIT licensed.

concurim-0.1.0/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Model
+
+- The viewer is local-only: it binds `127.0.0.1`, rejects other `Host`
+  headers, sends a strict CSP, serves static files
+  with path containment, and serves source text only from the loaded trace.
+- The viewer has a small write surface: opening a trace, uploading a program to
+  a private scratch directory, and starting/cancelling a run. Every `POST`
+  needs a per-launch token (embedded only in the served page), a same-origin
+  `Origin`, and is size-limited. Scratch files use sanitized paths and caps.
+- **Recording runs your Python code with your user's permissions. There is no
+  sandbox.** A run starts only after the plan (command, working directory,
+  arguments, interpreter) is shown and "Record execution" is clicked. Dropping
+  a `.concurim` trace never executes anything.
+- Traces are data: they are parsed with `json` and validated; size limits
+  apply; nothing is unpickled or executed. Strings are rendered as text.
+- No telemetry, uploads, accounts, or network use.
+- Auto-instrumentation (`--auto sync|asyncio`) temporarily replaces
+  standard-library factories in the recorded process only, and restores them
+  on exit. It never touches the viewer or other processes.
+- Recording can expose information. Source embedding and payload previews are
+  opt-in; previews cover only built-in primitives, are redacted by configured
+  patterns *before* truncation, and never call `repr()` on user objects.
+
+## Reporting
+
+Please report vulnerabilities privately through GitHub Security Advisories on
+the repository (or by email to the maintainers once published) instead of a
+public issue. Include a trace or steps to reproduce. We aim to acknowledge
+within a few days.
+
+## Sharing traces
+
+A `.concurim` file may contain file paths, thread names, queue names and, if
+enabled, source code or data previews. Review with `concurim inspect` and the
+viewer's **Trace** tab before sharing.

concurim-0.1.0/docs/concepts.md

@@ -0,0 +1,37 @@
+# Concepts
+
+Concurim records one schedule: the one this process actually ran. It
+does not search for other interleavings, and it does not show who held
+the GIL.
+
+**Observed** facts come from an event. A solid border, a queue's
+contents, and "blocked on this lock" are observed. **Inferred** facts
+are a guess the viewer labels as such. A dashed border means the actor
+is treated as running because nothing has said it is blocked. The
+explanation card says when a sentence is inferred.
+
+Recording changes timing. The picture is faithful to the instrumented
+run, which is a bit slower than the same program with Concurim absent.
+
+A file that does not compile is not a run. A program that starts and
+then raises is a run, and the exception is in the trace. A program that
+gets stuck is a run that ends at the last observed event. If threads are
+waiting on locks one another holds, the viewer says so. That cycle is
+read off this run. Queues and events do not name who has to move next,
+so they are not drawn as a cycle.
+
+Anything the chosen observability level cannot see is listed as not
+observed. It is not filled in. The full list is in
+[limitations](limitations.md).
+
+## What you can trust
+
+- Queue contents change only on recorded events, in true mutation order.
+- Queued and unfinished are different numbers. A dequeued item leaves
+  the queue and stays unfinished until `task_done()`.
+- `task_done()` does not say which item finished. Concurim attributes it
+  only when you pass `object_id=`. Otherwise the pairing is labeled
+  inferred.
+- A truncated recording, an object that was not instrumented, and
+  anything unobservable (CPU scheduling, the GIL) is stated in the trace
+  and in the UI.

concurim-0.1.0/docs/cost.md

@@ -0,0 +1,16 @@
+# Cost
+
+Measured on an Apple-silicon laptop, CPython 3.13
+(`scripts/benchmark.py`):
+
+| | |
+| --- | --- |
+| `TracedQueue` while not recording | ~2× a bare `queue.Queue` call (≈0.5 µs more) |
+| Recording, detailed or light | ≈10 µs per put+get pair (≈20× a bare, work-free loop) |
+| Memory while recording | ≈550 B/event (in-memory buffer) |
+| Trace size | ≈19 B/event on disk (zip) |
+| Load + replay | ≈1.5 s for 80k events |
+
+The overhead matters when threads do no real work between instrumented
+calls. With real work in between, it is usually small. Re-measure on
+the machine you care about.

concurim-0.1.0/docs/getting-started.md

@@ -0,0 +1,68 @@
+# Getting started
+
+Open the home screen and drop a program, or record from the terminal.
+Either way you get one picture of the run that actually happened.
+
+Commands below use `uv run concurim` from a checkout of this repo.
+After 0.1.0 is on PyPI, `uvx concurim` is the same home screen, and
+`uv add --dev concurim` is how `concurim record` can import a project's
+own packages.
+
+## Open the page
+
+```bash
+git clone https://github.com/ej-sanmartin/concurim.git
+cd concurim
+uv sync
+uv run concurim
+```
+
+The browser opens on this computer. From there:
+
+- Drop a `.concurim` file, or open an example. Nothing runs.
+- Drop a `.py` file or a project folder. Pick the entry point,
+  interpreter, arguments, and observability level, read the plan, then
+  click **Record execution**. The program does not run until that click.
+  When it finishes, the picture opens.
+- **Watch so far**, while a run is still going, opens the latest saved
+  moment. That picture stays where you opened it.
+
+```bash
+uv run concurim --port 8794 --no-browser   # page only, you open the URL
+```
+
+## Record from the terminal
+
+Options come before the script. Everything after the script path is
+passed to your program.
+
+```bash
+uv run concurim record --open my_app.py
+uv run concurim record --open --auto sync my_app.py
+uv run concurim record --open --include-source -o run.concurim my_app.py arg1
+uv run concurim view run.concurim
+uv run concurim inspect run.concurim
+```
+
+`--auto` defaults to `threads`. Use `queues`, `sync`, or `asyncio` when
+the program uses those primitives and does not import Concurim itself.
+`--include-source` is what the Code view needs. A file that does not
+compile is refused, and no trace is written.
+
+```bash
+uv run concurim demo
+uv run concurim compare one.concurim two.concurim
+uv run concurim export run.concurim -o clip.mp4 --events 5:40
+```
+
+`demo` records the bundled pipeline and opens it. `export` needs a
+Chrome-family browser and ffmpeg (`uv run --with imageio-ffmpeg`, or
+`concurim[video]` once the package is published). It only reads the
+trace.
+
+Ctrl-C during `record` still leaves a trace. Playback ends at the last
+observed event. See [limitations](limitations.md) for what a stuck run
+can and cannot show.
+
+Next: [concepts](concepts.md), [recording](recording.md),
+[reading a run](reading-a-run.md).

concurim-0.1.0/docs/index.md

@@ -0,0 +1,23 @@
+# Concurim documentation
+
+The [README](../README.md) is the tour. These pages are the short guide.
+
+## Read these
+
+| | |
+| --- | --- |
+| [Getting started](getting-started.md) | Open the page, or record from the terminal |
+| [Concepts](concepts.md) | One schedule, observed versus inferred |
+| [Recording](recording.md) | Home screen, CLI, `record()`, `Traced*` |
+| [Reading a run](reading-a-run.md) | Animation, Code, Timeline, compare, export |
+| [Teaching](teaching.md) | Which bundled example shows which idea |
+| [Cost](cost.md) | Overhead of recording |
+| [Limitations](limitations.md) | What is observed, stuck programs, what is refused |
+| [Trace format](trace-format.md) | The `.concurim` zip, for anyone building on the file |
+| [Security](../SECURITY.md) | Local viewer, no telemetry, what a trace can contain |
+| [Contributing](../CONTRIBUTING.md) | Tests, style, and how a PyPI upload will work |
+| [Changelog](../CHANGELOG.md) | What 0.1.0 contains |
+
+Video captions, a live picture that keeps updating, and a single HTML
+file you can send someone are listed in [limitations](limitations.md)
+and are not in 0.1.0.