Skip to content

Releases

v3.0.0a1

v3.0.0a1 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 12 Jul 14:33

swgoh-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.whl

Or from a git ref:

pip install git+https://github.com/MarTrepodi/comlink-python.git@v3.0.0a1

Recommended: 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
  • click moved behind [migrate] optional extra. Only matters if
    you import from swgoh_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. ProcessPoolExecutor fan-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_statcalc

Writes 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 print 3.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.