Repository navigation
v3.0.0a1
Pre-releaseswgoh-comlink v3.0.0a1 (first alpha)
Date: 2026-05-19
Channel: GitHub Releases only — not on PyPI.
Governance: ADR-0008
The first community-tryable v3 alpha. Bundles the work from four
research phases (v3.0 → v3.3) into one installable wheel. Bug
reports welcome via the v3 issue label.
Install
This alpha is hosted on the maintainer fork
MarTrepodi/comlink-python;
the upstream swgoh-utils repo stays on v2.x until reintegration.
pip install https://github.com/MarTrepodi/comlink-python/releases/download/v3.0.0a1/swgoh_comlink-3.0.0a1-py3-none-any.whlOr from a git ref:
pip install git+https://github.com/MarTrepodi/comlink-python.git@v3.0.0a1Recommended: install into a dedicated virtual environment with a
rollback path to the public v2.x release — see
docs/v3/install-alpha.md.
The PyPI package swgoh_comlink is still v2.x — pip install --pre swgoh_comlink will NOT pick up this alpha. v3 lives only on
GitHub Releases until reintegration with upstream.
Highlights
Phase v3.0 — Core resilience + msgspec foundation. Hand-rolled
retry policy via stamina>=24.3, profiles (profile="bot",
profile="cli", …). msgspec.Struct decoders for every endpoint;
raw=True opt-out per call. Lazy-import __init__.py (PEP 562) so
import swgoh_comlink no longer pulls httpx/msgspec eagerly —
import time drops from ~110 ms to ~15 ms cold. GameDataCache
(diskcache + msgpack + in-process memo) hits ~99 % cache hit
rate on long-running callers.
Phase v3.1 — Typed game-data segments + async cache + client
split. Generic compat.decode_segment(raw, segment) with the
STOCK_SEGMENT_TYPES registry types all 14 /data segments
(Units, SkillDefinition, Equipment, StatMod, StatModSet, …) as
msgspec.Struct. Aggregate decode time 1.79× faster at
0.66× memory vs json.loads + dict access. aget_game_data /
aget_localization on GameDataCache for async callers (40k×
warm-path speedup vs cold). 2×2 client matrix
(sync/async × dict/typed) code-generated from
src/swgoh_comlink/_codegen/endpoints.py — see ADR-0005.
Phase v3.2 — Bimorphic StatCalc + cached game_data.
StatCalc.calc_player_stats accepts either dict or
msgspec.Struct; conversion happens once at the boundary.
get_statcalc_game_data(client, cache=cache) caches the
StatCalc-normalized game_data alongside the raw /data payload
— cold-start drops from 25.7 ms to 3.6 ms (+85.9 %). See
ADR-0006 for the full 8-candidate evaluation.
Phase v3.3 — Pure-Python restructure + typed-fastpath. Table-
driven _calculate_mod_stats (165-line cascade → 5-line dispatch
via _mod_stat_rules); lightweight _table_get; eliminated 10
per-call lambdas in _format_stats. Combined with the typed-
fastpath that reads msgspec.Struct.__slots__ directly (skipping
msgspec.to_builtins), the hot path is +16.3 % faster on
player_large and bimorphic Struct overhead drops from
+22.9 % → +10.1 %. Cython / mypyc / Rust prototypes
researched but not shipped (per ADR-0007 — distribution
complexity outweighed the +6-9 pp additional speed).
Breaking changes vs v2
The v2 → v3 migration is documented at
docs/v3/migration.md. Headlines:
- Typed-by-default surface lives at a new import path:
# v2 (still works — dict-typed, byte-compatible) from swgoh_comlink import SwgohComlink # v3 typed (new — msgspec.Struct returns) from swgoh_comlink.typed import SwgohComlink
clickmoved behind[migrate]optional extra. Only matters if
you import fromswgoh_comlink.migrate.- Python ≥ 3.11 required (was 3.10).
If your code uses from swgoh_comlink import SwgohComlink and
expects dict returns, nothing changes. The dict-default client
is preserved byte-for-byte from v2.
Known limitations
- Pure-Python only. Cython, mypyc, and Rust/PyO3 kernel
prototypes exist on throwaway research branches but do NOT
ship in this alpha — the 15-wheel-per-release distribution
cost was judged not worth the +6-9 pp speedup. See ADR-0007
for the analysis. - StatCalc parallelism deferred.
ProcessPoolExecutorfan-out
was prototyped in v3.2 (Candidate D) but regressed on large
rosters (IPC break-even exceeds per-unit work). Wait for either
Cython inner loops or sub-interpreters / free-threaded Python
before re-attempting. See ADR-0006. - Async StatCalc not implemented beyond a thin sync-inherited
shell.StatCalcAsync.create()is an async factory for game-data
fetch only; per-unit calc methods remain sync. - Bimorphic Struct overhead is +10.1 %, not ≤ 5 %. The
typed-fastpath got it to +10.1 %; getting below 5 % requires a
larger refactor (Struct-aware internal dispatch). For per-tick
hot loops,client.get_player(..., raw=True)is still the
zero-overhead path.
Reproducing the benchmarks
Cassettes live in parity/ and benchmarks/v3/fixtures/. The
benchmark harness is at benchmarks/v3/bench_statcalc.py:
uv sync --all-extras --dev
uv run python -m benchmarks.v3.bench_statcalcWrites benchmarks/v3/results/phase-v3_3-baseline.json. Compare
against phase-v3_3-integration.json (the shipped result) and
the per-phase reports under docs/v3/phase-*-report.md.
Reporting bugs
Open issues at https://github.com/MarTrepodi/comlink-python/issues.
The bug-report template will auto-apply the v3 label when you
select v3 in the Version dropdown. Please include:
- Python version + OS
swgoh_comlink.version(should print3.0.0a1)- The comlink URL profile (
comlink.local,localhost:3200, etc.)- comlink version if you know it
- A minimal repro — for StatCalc bugs, the cassette JSON if you
can share it
Governance
This alpha ships under ADR-0008.
The ADR explicitly forbids PyPI publication and final
(non-pre-release) tags from this repo until reintegration with
upstream is decided. The sunset clause requires re-evaluation
by 2027-05-19 if reintegration has not completed.
For the historical context on why this is a standalone research
repo at all, see ADR-0001.