wh40kdc 0.5.0__tar.gz

wh40kdc-0.5.0/.gitignore

@@ -0,0 +1,45 @@
+node_modules/
+dist/
+.vite/
+.wrangler/
+_site/
+# HTML TypeDoc output for the Pages site — a CI build artifact assembled into
+# _site/api/. The markdown counterpart (tools/docs/api/) stays committed for
+# in-repo browsing; this HTML build is regenerated on every Pages deploy.
+tools/docs/api-html/
+/target/
+/rust_analyzer/
+tools/schemas/
+tools/src/data/bundle.generated.ts
+.DS_Store
+*.log
+rube-goldberg-output.txt
+
+# _audit/ is the DSL-authoring worklist (#21). Keep the human-readable summaries
+# (coverage.json, summary.md, proposed/*.md) but ignore the bulky, churn-prone
+# machine-generated proposal/input JSON — it regenerates from the author-* tools.
+/data/_audit/author-input/
+/data/_audit/proposed/*.json
+/data/_audit/worklist.json
+
+# Fuzz-mode regression repros from the cross-impl parity differ. The directory
+# itself is kept (via .gitkeep) so the differ has somewhere to write; the JSON
+# repros are ephemeral — promoting one to the permanent corpus is a deliberate
+# act and lands under conformance/.
+/tooling/parity/regressions/*.json
+
+# Python bytecode caches from running the differ locally.
+__pycache__/
+*.pyc
+
+# Python package dev artifacts (python/ is the wh40kdc PyPI package).
+/python/.venv/
+/python/dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# IP-sensitive working material (source PDFs of upstream rulebooks, extracted
+# prose, scratch notes) that must never be committed. Anything inside this
+# directory stays local.
+/_private/

wh40kdc-0.5.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: wh40kdc
+Version: 0.5.0
+Summary: Warhammer 40K dataset for the 40kdc-data schema layer: an embedded dataset behind a linked typed API, ListForge + NewRecruit roster importers and exporters, damage-projection cruncher, and a schema validator.
+Project-URL: Homepage, https://40kdc.alpacasoft.dev
+Project-URL: Repository, https://github.com/wn-mitch/40kdc-data
+Author: Alpaca Software
+License-Expression: MIT
+Keywords: 40k,dataset,schema,wargaming,warhammer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema<5,>=4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: datamodel-code-generator==0.60.0; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.15.16; extra == 'dev'
+Requires-Dist: types-jsonschema; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wh40kdc
+
+The 40kdc Warhammer 40K dataset behind a linked, typed API — find units, follow
+them to their weapons, abilities, phases, and factions. The Python counterpart
+to [`@alpaca-software/40kdc-data`](https://www.npmjs.com/package/@alpaca-software/40kdc-data)
+(npm) and [`wh40kdc`](https://crates.io/crates/wh40kdc) (crates.io), held in
+behavioral lockstep with both by the shared conformance corpus in the
+[40kdc-data repository](https://github.com/wn-mitch/40kdc-data).
+
+```bash
+pip install wh40kdc
+```
+
+```python
+from wh40kdc import Dataset
+
+ds = Dataset.embedded()
+unit = ds.units.find("Khârn the Betrayer")
+for weapon in unit.weapons:
+    print(weapon.name)
+```
+
+What ships:
+
+- **Linked dataset API** — `Dataset` with id/name lookups (diacritic- and
+  punctuation-insensitive), reverse indexes, and join queries across units,
+  weapons, abilities, phases, and factions.
+- **Importers** — ListForge, NewRecruit (JSON / WTC-compact / WTC-full /
+  simple), GW app export, and Rosterizer, all resolving to one `Roster` shape.
+- **Exporters** — the same roster formats back out, byte-identical to the
+  TypeScript and Rust implementations.
+- **Cruncher** — the damage-projection engine (attacks → hits → wounds →
+  unsaved → damage → after-FNP → models-killed) with buff resolution and
+  per-buff attribution.
+- **Scoring, terrain, translation** — secondary-mission scoring, terrain
+  layout resolution and keystone measurements, and the ability-DSL /
+  scoring-card describers.
+- **Validator** — `validate(target, value)` against the canonical JSON
+  Schemas, emitting the closed error-code enum shared by all implementations.
+
+The conformance runner (used by the cross-implementation parity differ) is
+invoked as `python -m wh40kdc.runner` — see `conformance/RUNNER_PROTOCOL.md`
+in the repository.
+
+## Development
+
+```bash
+cd python
+uv venv && uv pip install -e ".[dev]"
+pytest          # includes the conformance suite when run inside the repo
+ruff check .
+mypy src
+```
+
+Generated artifacts (`_bundle.json`, `_spec.py`, `_types.py`,
+`src/wh40kdc/schemas/`) are produced by the scripts in `codegen/` and checked
+for drift in CI — regenerate with:
+
+```bash
+python3 codegen/sync_bundle.py && python3 codegen/sync_spec.py && python3 codegen/gen_typeddicts.py
+```
+
+## License
+
+MIT. The schema content the dataset describes is CC0; enrichment data is
+CC BY 4.0 — see the repository's licensing table.

wh40kdc-0.5.0/README.md

@@ -0,0 +1,66 @@
+# wh40kdc
+
+The 40kdc Warhammer 40K dataset behind a linked, typed API — find units, follow
+them to their weapons, abilities, phases, and factions. The Python counterpart
+to [`@alpaca-software/40kdc-data`](https://www.npmjs.com/package/@alpaca-software/40kdc-data)
+(npm) and [`wh40kdc`](https://crates.io/crates/wh40kdc) (crates.io), held in
+behavioral lockstep with both by the shared conformance corpus in the
+[40kdc-data repository](https://github.com/wn-mitch/40kdc-data).
+
+```bash
+pip install wh40kdc
+```
+
+```python
+from wh40kdc import Dataset
+
+ds = Dataset.embedded()
+unit = ds.units.find("Khârn the Betrayer")
+for weapon in unit.weapons:
+    print(weapon.name)
+```
+
+What ships:
+
+- **Linked dataset API** — `Dataset` with id/name lookups (diacritic- and
+  punctuation-insensitive), reverse indexes, and join queries across units,
+  weapons, abilities, phases, and factions.
+- **Importers** — ListForge, NewRecruit (JSON / WTC-compact / WTC-full /
+  simple), GW app export, and Rosterizer, all resolving to one `Roster` shape.
+- **Exporters** — the same roster formats back out, byte-identical to the
+  TypeScript and Rust implementations.
+- **Cruncher** — the damage-projection engine (attacks → hits → wounds →
+  unsaved → damage → after-FNP → models-killed) with buff resolution and
+  per-buff attribution.
+- **Scoring, terrain, translation** — secondary-mission scoring, terrain
+  layout resolution and keystone measurements, and the ability-DSL /
+  scoring-card describers.
+- **Validator** — `validate(target, value)` against the canonical JSON
+  Schemas, emitting the closed error-code enum shared by all implementations.
+
+The conformance runner (used by the cross-implementation parity differ) is
+invoked as `python -m wh40kdc.runner` — see `conformance/RUNNER_PROTOCOL.md`
+in the repository.
+
+## Development
+
+```bash
+cd python
+uv venv && uv pip install -e ".[dev]"
+pytest          # includes the conformance suite when run inside the repo
+ruff check .
+mypy src
+```
+
+Generated artifacts (`_bundle.json`, `_spec.py`, `_types.py`,
+`src/wh40kdc/schemas/`) are produced by the scripts in `codegen/` and checked
+for drift in CI — regenerate with:
+
+```bash
+python3 codegen/sync_bundle.py && python3 codegen/sync_spec.py && python3 codegen/gen_typeddicts.py
+```
+
+## License
+
+MIT. The schema content the dataset describes is CC0; enrichment data is
+CC BY 4.0 — see the repository's licensing table.

wh40kdc-0.5.0/codegen/gen_typeddicts.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Generate TypedDict entity types from the bundled JSON Schema.
+
+Runs datamodel-code-generator against
+``crates/wh40kdc/schemas/bundled.schema.json`` (the same artifact Rust's
+typify codegen consumes, produced by ``npm run bundle:schemas`` in tools/).
+The output is a typing aid only — runtime values are plain dicts, mirroring
+the TypeScript reference implementation.
+
+``--no-use-closed-typed-dict`` keeps the output importable with the stdlib
+``typing`` module alone (PEP 728 ``closed=True`` would require
+typing_extensions at runtime); ``--disable-timestamp`` keeps regeneration
+byte-stable for the CI drift check.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SCHEMA = REPO_ROOT / "crates" / "wh40kdc" / "schemas" / "bundled.schema.json"
+OUT = REPO_ROOT / "python" / "src" / "wh40kdc" / "_types.py"
+
+
+def main() -> int:
+    if not SCHEMA.exists():
+        print(
+            f"missing {SCHEMA}; run `cd tools && npm run bundle:schemas` first",
+            file=sys.stderr,
+        )
+        return 1
+    cmd = [
+        sys.executable,
+        "-m",
+        "datamodel_code_generator",
+        "--input",
+        str(SCHEMA),
+        "--input-file-type",
+        "jsonschema",
+        "--output-model-type",
+        "typing.TypedDict",
+        "--output",
+        str(OUT),
+        "--target-python-version",
+        "3.11",
+        "--class-name",
+        "BundledSchemas",
+        "--no-use-closed-typed-dict",
+        "--disable-timestamp",
+        "--formatters",
+        "ruff-format",
+        "--custom-file-header",
+        "# Generated by codegen/gen_typeddicts.py — do not edit. CI fails on drift.",
+    ]
+    subprocess.run(cmd, check=True)
+    print(f"wrote {OUT}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wh40kdc-0.5.0/codegen/sync_bundle.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Sync the embedded data bundle and schema tree into the Python package.
+
+The bundle is a byte-for-byte copy of the Rust crate's
+``crates/wh40kdc/src/data/bundle.generated.json`` (itself regenerated by
+``cargo run -p xtask -- bundle-data``). Copying — rather than re-deriving from
+``data/`` — guarantees all three implementations share one bundler's file-walk
+iteration order, which the set-semantics linked-api conformance queries depend
+on (see CONFORMANCE.md).
+
+The schema tree is copied because published wheels don't ship the repo's
+``schemas/`` directory; the validator loads the packaged copy.
+
+CI regenerates both and fails on drift (``git diff --exit-code``).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUST_BUNDLE = REPO_ROOT / "crates" / "wh40kdc" / "src" / "data" / "bundle.generated.json"
+SCHEMAS_ROOT = REPO_ROOT / "schemas"
+PKG_ROOT = REPO_ROOT / "python" / "src" / "wh40kdc"
+PKG_BUNDLE = PKG_ROOT / "_bundle.json"
+PKG_SCHEMAS = PKG_ROOT / "schemas"
+
+
+def main() -> int:
+    if not RUST_BUNDLE.exists():
+        print(
+            f"missing {RUST_BUNDLE}; run `cargo run -p xtask -- bundle-data` first",
+            file=sys.stderr,
+        )
+        return 1
+
+    PKG_BUNDLE.write_bytes(RUST_BUNDLE.read_bytes())
+    print(f"wrote {PKG_BUNDLE} ({PKG_BUNDLE.stat().st_size} bytes)")
+
+    if PKG_SCHEMAS.exists():
+        shutil.rmtree(PKG_SCHEMAS)
+    count = 0
+    for src in sorted(SCHEMAS_ROOT.rglob("*.schema.json")):
+        rel = src.relative_to(SCHEMAS_ROOT)
+        dest = PKG_SCHEMAS / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(src.read_bytes())
+        count += 1
+    print(f"copied {count} schema files into {PKG_SCHEMAS}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wh40kdc-0.5.0/codegen/sync_spec.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""Embed conformance/SPEC_VERSION as a generated constant.
+
+The TS and Rust runners parent-walk to ``conformance/SPEC_VERSION`` at
+runtime; published Python wheels don't ship the repo, so the version is baked
+in at codegen time and drift-checked in CI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SPEC_FILE = REPO_ROOT / "conformance" / "SPEC_VERSION"
+OUT = REPO_ROOT / "python" / "src" / "wh40kdc" / "_spec.py"
+
+TEMPLATE = '''"""Generated by codegen/sync_spec.py — do not edit.
+
+Mirrors conformance/SPEC_VERSION; CI fails on drift.
+"""
+
+SPEC_VERSION = {version}
+'''
+
+
+def main() -> int:
+    version = int(SPEC_FILE.read_text().strip())
+    OUT.write_text(TEMPLATE.format(version=version))
+    print(f"wrote {OUT} (SPEC_VERSION = {version})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wh40kdc-0.5.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wh40kdc"
+# Version lives in src/wh40kdc/_version.py (single source), kept in lockstep
+# with tools/package.json and crates/wh40kdc/Cargo.toml — CI hard-fails on
+# mismatch (.github/workflows/validate.yml).
+dynamic = ["version"]
+description = "Warhammer 40K dataset for the 40kdc-data schema layer: an embedded dataset behind a linked typed API, ListForge + NewRecruit roster importers and exporters, damage-projection cruncher, and a schema validator."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Alpaca Software" }]
+keywords = ["warhammer", "40k", "wargaming", "schema", "dataset"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Games/Entertainment :: Board Games",
+  "Typing :: Typed",
+]
+# The only runtime dependency. Everything else (base64, zlib, re, unicodedata,
+# math, json) is stdlib — keep it that way; see CONFORMANCE.md for why the
+# implementations stay dependency-light.
+dependencies = ["jsonschema>=4,<5"]
+
+[project.urls]
+Homepage = "https://40kdc.alpacasoft.dev"
+Repository = "https://github.com/wn-mitch/40kdc-data"
+
+# NOTE: deliberately no [project.scripts] console script. The conformance
+# runner is invoked as `python -m wh40kdc.runner` — a `wh40kdc-runner` script
+# would collide with the Rust binary of the same name on PATH in CI's parity
+# job (see conformance/RUNNER_PROTOCOL.md).
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "mypy>=1.13",
+  "types-jsonschema",
+  # Pinned: gen_typeddicts.py output must be byte-stable for the CI drift
+  # check (generator or formatter version drift changes the emitted text;
+  # the generator shells out to ruff-format, so ruff pins too).
+  "ruff==0.15.16",
+  "datamodel-code-generator==0.60.0",
+  "build>=1.2",
+]
+
+[tool.hatch.version]
+path = "src/wh40kdc/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wh40kdc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/wh40kdc", "README.md", "codegen"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "RUF"]
+# The ambiguous-unicode rules (RUF001-003) fight this package's substance:
+# normalize_name's quote-variant regex and the test corpus are deliberately
+# full of curly quotes and diacritics.
+ignore = ["RUF001", "RUF002", "RUF003"]
+# Generated code is exempt from style rules (mirrors the TS/Rust generated
+# artifacts, which are also excluded from lint).
+exclude = ["src/wh40kdc/_types.py"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = false
+disallow_untyped_defs = true
+warn_unused_ignores = true
+no_implicit_optional = true
+exclude = ["_types\\.py$"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wh40kdc-0.5.0/src/wh40kdc/__init__.py

@@ -0,0 +1,76 @@
+"""wh40kdc — the 40kdc Warhammer 40K dataset behind a linked, typed API.
+
+Python counterpart to ``@alpaca-software/40kdc-data`` (npm) and the
+``wh40kdc`` crate (crates.io), held in behavioral lockstep by the shared
+conformance corpus. See the repository's CONFORMANCE.md.
+"""
+
+from wh40kdc._version import __version__
+from wh40kdc.abilities_resolver import resolve_eligible_abilities
+from wh40kdc.cruncher import (
+    attribute_stages,
+    buffs_from_keyword,
+    crunch,
+    effect_to_buffs,
+    resolve_buffs,
+)
+from wh40kdc.data import (
+    Collection,
+    Dataset,
+    clamp_weapon_count,
+    maximal_loadout,
+    normalize_name,
+    option_cap,
+    validate_loadout,
+    weapon_bounds,
+)
+from wh40kdc.export import EXPORT_FORMATS, export_roster
+from wh40kdc.imports import (
+    REGISTERED_ADAPTERS,
+    decode_listforge,
+    import_listforge,
+    import_newrecruit,
+    import_roster,
+    try_import_roster,
+)
+from wh40kdc.scoring import score_turn, wtc_result
+from wh40kdc.terrain import BOARD_INCHES, keystone_measurements, resolve_layout
+from wh40kdc.translate import describe_ability, describe_condition, describe_scoring_card
+from wh40kdc.validator import VALIDATOR_TARGETS, SchemaValidator, create_validator
+
+__all__ = [
+    "BOARD_INCHES",
+    "EXPORT_FORMATS",
+    "REGISTERED_ADAPTERS",
+    "VALIDATOR_TARGETS",
+    "Collection",
+    "Dataset",
+    "SchemaValidator",
+    "__version__",
+    "attribute_stages",
+    "buffs_from_keyword",
+    "clamp_weapon_count",
+    "create_validator",
+    "crunch",
+    "decode_listforge",
+    "describe_ability",
+    "describe_condition",
+    "describe_scoring_card",
+    "effect_to_buffs",
+    "export_roster",
+    "import_listforge",
+    "import_newrecruit",
+    "import_roster",
+    "keystone_measurements",
+    "maximal_loadout",
+    "normalize_name",
+    "option_cap",
+    "resolve_buffs",
+    "resolve_eligible_abilities",
+    "resolve_layout",
+    "score_turn",
+    "try_import_roster",
+    "validate_loadout",
+    "weapon_bounds",
+    "wtc_result",
+]