wows-replay-parser 0.1.1__tar.gz

wows_replay_parser-0.1.1/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,17 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Please read it before participating. By contributing you agree to uphold
+its standards.
+
+## Enforcement
+
+Report unacceptable behaviour to **tb@kleinundpartner.at**.
+
+All reports will be reviewed and investigated promptly and fairly. The
+project maintainer is obligated to respect the privacy and security of the
+reporter of any incident.
+
+Enforcement follows the Community Impact Guidelines described in the
+Contributor Covenant (correction → warning → temporary ban → permanent ban).

wows_replay_parser-0.1.1/.github/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for taking the time to contribute. This project is small enough that
+the process is informal, but a few conventions keep things tidy.
+
+## Development setup
+
+```bash
+git clone https://github.com/toalba/wows-replay-parser.git
+cd wows-replay-parser
+uv venv
+source .venv/bin/activate
+uv sync --all-extras
+```
+
+Tests and the canary workflow need a `.wowsreplay` fixture plus the gamedata
+tree. See [tests/fixtures/README.md](https://github.com/toalba/wows-replay-parser/blob/main/tests/fixtures/README.md)
+for details. Without fixtures, integration tests skip cleanly — you can
+still work on unit-test coverage.
+
+## Running checks locally
+
+```bash
+uv run ruff check src/ tests/     # style + lint
+uv run mypy src/                  # type-check (advisory)
+uv run pytest                     # tests
+```
+
+CI mirrors these on every push and pull request.
+
+## Style
+
+- Line length: **120** characters.
+- `from __future__ import annotations` at the top of every module.
+- Type hints on every public function and dataclass field.
+- Docstrings on public API surface (`ParsedReplay`, events, state models).
+- Prefer `@cached_property` for expensive derived data over eager computation.
+
+Ruff enforces most of this. If a rule gets in the way of readability, open
+a PR that disables it in `pyproject.toml` with a short rationale — don't
+work around it with `# noqa`.
+
+## Commits
+
+Short imperative subject line. Body for the *why* when the change isn't
+self-evident.
+
+```
+Fix RIBBON_NAMES inversion
+
+The lookup was keyed on names instead of wire ids, so every
+derive_ribbons() call fell through to "Unknown". ...
+```
+
+## Pull requests
+
+- Branch from `main`.
+- Keep PRs focused — one logical change per PR.
+- Tests passing (CI will verify).
+- Reasonable commit history — squash trivial fix-ups before requesting review.
+- Update `CHANGELOG.md` if the change is user-facing.
+
+## Parser-specific guidance
+
+- The `.def` files and `alias.xml` in the gamedata repo are the single source
+  of truth for entity definitions. If your change depends on a structural
+  assumption, verify it against those files first.
+- Never work around a parser bug inside the renderer. If decoded data is
+  wrong, fix the decode.
+- See [CLAUDE.md](https://github.com/toalba/wows-replay-parser/blob/main/CLAUDE.md) for deeper architectural notes.

wows_replay_parser-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,72 @@
+name: Bug report
+description: Something the parser does wrong with a specific replay or gamedata version.
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: Minimal code or CLI invocation that triggers the bug.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual behaviour
+
+  - type: input
+    id: parser-version
+    attributes:
+      label: Parser version / commit
+      placeholder: "v0.1.0 or abc123"
+    validations:
+      required: true
+
+  - type: input
+    id: game-version
+    attributes:
+      label: WoWs game version
+      description: From the replay's JSON header (`clientVersionFromXml`), e.g. "15,3,0,12267945".
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12.3"
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / stack trace
+      render: shell
+
+  - type: markdown
+    attributes:
+      value: |
+        **About replay files:** please do NOT attach private-match replays.
+        If a replay is needed to reproduce, describe the scenario in words
+        or share a sanitized version (player names replaced). Never share
+        account IDs or clan tags belonging to others without permission.

wows_replay_parser-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

wows_replay_parser-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Propose a new event type, API, or capability.
+title: "[Feat] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: What are you trying to accomplish? A concrete example helps.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed API or behaviour
+      description: What should the parser expose, and what would consumers write?
+      render: python
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you evaluated and why you didn't pick them.
+
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: Links to relevant `.def` fields, game-data paths, or decompiled
+        client code that confirm the data is actually present in the replay.

wows_replay_parser-0.1.1/.github/ISSUE_TEMPLATE/regression.yml

@@ -0,0 +1,42 @@
+name: Regression (patch break)
+description: A new WoWs game patch broke parsing. Often auto-filed by the canary workflow.
+title: "[Regression] "
+labels: ["patch-regression"]
+body:
+  - type: input
+    id: last-working
+    attributes:
+      label: Last known-working parser version / commit
+    validations:
+      required: true
+
+  - type: input
+    id: first-broken
+    attributes:
+      label: First broken commit / run URL
+      description: Ideally a link to the canary workflow run that caught it.
+    validations:
+      required: true
+
+  - type: input
+    id: patch-version
+    attributes:
+      label: WoWs patch version where the break appeared
+      description: e.g. "15.4.0.12400000" from the replay JSON header.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A one-liner or short script that fails now but used to work.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: suspected-cause
+    attributes:
+      label: Suspected cause
+      description: E.g. a renamed property, a reordered method, a new packet type.

wows_replay_parser-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+<!--
+Short imperative subject. Body should answer *why* the change is being
+made — the diff already shows *what*.
+-->
+
+## Summary
+
+
+
+## Type
+
+<!-- Check one -->
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Refactor / cleanup
+- [ ] Docs
+- [ ] CI / tooling
+
+## Test plan
+
+<!-- How did you verify this works? Delete rows that don't apply. -->
+- [ ] `uv run pytest` green
+- [ ] `uv run ruff check src/ tests/` clean
+- [ ] Added / updated unit tests covering the change
+- [ ] Exercised against a real replay fixture locally
+
+## Checklist
+
+- [ ] CHANGELOG updated if this is a user-visible change
+- [ ] Docstrings updated for public API touched by this change
+- [ ] If fixing a parser bug, verified it against the `.def` / `alias.xml`
+      source of truth
+
+## Related issues
+
+<!-- Fixes #123 / Closes #456 -->

wows_replay_parser-0.1.1/.github/SECRETS.md

@@ -0,0 +1,24 @@
+# Repository secrets
+
+Secrets consumed by workflows in `.github/workflows/`. Add them under
+**Settings → Secrets and variables → Actions → New repository secret**.
+
+| Secret | Used by | Purpose |
+|---|---|---|
+| `GAMEDATA_PAT` | `canary.yml` | Clone the private `toalba/wows-gamedata` repo over HTTPS. |
+
+PyPI publishing (`publish.yml`) uses **Trusted Publishing** and does **not**
+require any secret — it authenticates via OIDC against PyPI directly.
+
+## Generating `GAMEDATA_PAT`
+
+1. Go to <https://github.com/settings/personal-access-tokens/new> (fine-grained token).
+2. **Resource owner:** `toalba` (or whichever account owns `wows-gamedata`).
+3. **Repository access:** *Only select repositories* → pick `wows-gamedata`.
+4. **Repository permissions:** `Contents: Read-only`, `Metadata: Read-only`.
+5. **Expiration:** 1 year (set a calendar reminder to rotate).
+6. Copy the token, then in this repo: *Settings → Secrets and variables →
+   Actions → New repository secret* → name `GAMEDATA_PAT`, paste value, save.
+
+The canary skips cleanly with a workflow warning if the secret is missing, so
+rotation lag will not cause spurious failure issues.

wows_replay_parser-0.1.1/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    target-branch: "main"
+    labels:
+      - "dependencies"
+      - "automated"
+    commit-message:
+      prefix: "deps"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    target-branch: "main"
+    labels:
+      - "dependencies"
+      - "automated"
+    commit-message:
+      prefix: "deps"
+    groups:
+      actions:
+        patterns:
+          - "*"

wows_replay_parser-0.1.1/.github/workflows/canary.yml

@@ -0,0 +1,145 @@
+name: Canary (patch regression)
+# Nightly: run tests against latest wows-gamedata tag; open patch-regression
+# issue on failure, close it on recovery.
+
+on:
+  schedule:
+    - cron: "0 3 * * *"  # Daily at 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  canary-test:
+    runs-on: ubuntu-latest
+    outputs:
+      gamedata_tag: ${{ steps.checkout-gamedata.outputs.tag }}
+      skipped: ${{ steps.secret-check.outputs.skipped }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check GAMEDATA_PAT secret
+        id: secret-check
+        env:
+          GAMEDATA_PAT: ${{ secrets.GAMEDATA_PAT }}
+        run: |
+          if [ -z "$GAMEDATA_PAT" ]; then
+            echo "::warning::GAMEDATA_PAT secret not configured — skipping canary. See .github/SECRETS.md."
+            echo "skipped=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skipped=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install uv
+        if: steps.secret-check.outputs.skipped != 'true'
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        if: steps.secret-check.outputs.skipped != 'true'
+        run: uv python install 3.12
+
+      - name: Install project
+        if: steps.secret-check.outputs.skipped != 'true'
+        run: uv sync --all-extras
+
+      - name: Clone wows-gamedata at latest tag
+        id: checkout-gamedata
+        if: steps.secret-check.outputs.skipped != 'true'
+        env:
+          GAMEDATA_PAT: ${{ secrets.GAMEDATA_PAT }}
+        run: |
+          set -euo pipefail
+          git clone --filter=blob:none --no-checkout \
+            "https://x-access-token:${GAMEDATA_PAT}@github.com/toalba/wows-gamedata.git" \
+            wows-gamedata
+          cd wows-gamedata
+          # Pick the latest tag by commit date (tags look like v15.2.0.12267945).
+          LATEST_TAG=$(git for-each-ref --sort=-creatordate --format='%(refname:short)' refs/tags | head -n1)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "::error::No tags found in wows-gamedata"
+            exit 1
+          fi
+          git checkout "$LATEST_TAG"
+          echo "Checked out gamedata tag: $LATEST_TAG"
+          echo "tag=$LATEST_TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Run pytest
+        id: pytest
+        if: steps.secret-check.outputs.skipped != 'true'
+        env:
+          GAMEDATA_PATH: ${{ github.workspace }}/wows-gamedata/data
+        run: |
+          set -o pipefail
+          uv run pytest tests/ -v --tb=short 2>&1 | tee pytest-output.txt
+
+      - name: Upload pytest output
+        if: always() && steps.secret-check.outputs.skipped != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: pytest-output
+          path: pytest-output.txt
+          if-no-files-found: ignore
+
+  report-failure:
+    needs: canary-test
+    if: failure() && needs.canary-test.outputs.skipped != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pytest-output
+          path: .
+        continue-on-error: true
+
+      - name: Open or update patch-regression issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.canary-test.outputs.gamedata_tag }}
+          RUN_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          {
+            echo "Canary failed against gamedata tag **${TAG}**."
+            echo ""
+            echo "Run: ${RUN_URL}"
+            echo ""
+            echo '<details><summary>pytest output (tail)</summary>'
+            echo '```'
+            [ -f pytest-output.txt ] && tail -c 60000 pytest-output.txt || echo "(no artifact)"
+            echo '```'
+            echo '</details>'
+          } > body.md
+          EXISTING=$(gh issue list --label patch-regression --state open --json number --jq '.[0].number' || true)
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --body-file body.md
+          else
+            gh issue create --title "Patch regression: ${TAG}" \
+              --label patch-regression --label automated --body-file body.md
+          fi
+
+  close-on-recovery:
+    needs: canary-test
+    if: success() && needs.canary-test.outputs.skipped != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Close open patch-regression issue (if any)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.canary-test.outputs.gamedata_tag }}
+        run: |
+          set -euo pipefail
+          EXISTING=$(gh issue list --label patch-regression --state open --json number --jq '.[0].number' || true)
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --body "Canary green on tag ${TAG} — closing."
+            gh issue close "$EXISTING"
+          fi

wows_replay_parser-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install project
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Type-check
+        run: uv run mypy src/
+        continue-on-error: true  # mypy is aspirational for now — don't block PRs
+
+      - name: Run tests
+        run: uv run pytest -v

wows_replay_parser-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/CONTRIBUTING.md"
+      - "SECURITY.md"
+      - "CHANGELOG.md"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # mkdocs uses git for last-modified timestamps
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install project + docs deps
+        run: uv sync --extra docs
+
+      - name: Build mkdocs site
+        run: uv run mkdocs build --strict
+
+      - name: Deploy to gh-pages
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        run: uv run mkdocs gh-deploy --force --no-history

wows_replay_parser-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: "Publish to TestPyPI instead of PyPI"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && !inputs.test_pypi)
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/wows-replay-parser/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.test_pypi
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/wows-replay-parser/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

wows_replay_parser-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.pyo
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+.claude/
+wows-gamedata/
+*.wowsreplay
+
+# Test fixtures — see tests/fixtures/README.md
+tests/fixtures/replays/*.wowsreplay
+tests/fixtures/gamedata/
+
+# mkdocs build output
+/site/