matamata 0.0.1__tar.gz

matamata-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q

matamata-0.0.1/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Generated diagrams: ignore stray renders, but keep the curated docs images
+# (used by the README), the versioned test goldens, and the example crest assets.
+*.svg
+*.png
+!docs/*.png
+!tests/golden/*.svg
+!examples/crests/*.svg
+!examples/crests/*.png
+
+# MkDocs build output (`mkdocs serve` / `mkdocs build`)
+/site/
+
+# Local, unversioned scratch space (personal notes, drafts — never committed)
+/.local/
+
+# Agent guidance and settings: machine- and workflow-specific, kept local only
+/CLAUDE.md
+/.claude/

matamata-0.0.1/.pylintrc

@@ -0,0 +1,15 @@
+[MASTER]
+
+disable=
+    C0114,
+    C0115,
+    C0116,
+    C0415,
+    W0718,
+    W0511,
+    R0903,
+    R0801,
+    R0913,
+    R0914,
+    R0917,
+

matamata-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aníbal Pacheco
+
+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.

matamata-0.0.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: matamata
+Version: 0.0.1
+Summary: Model tournament knockout stages in JSON format and render the schedule in SVG or html table format
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: jsonschema; extra == 'dev'
+Requires-Dist: mkdocs; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: black; extra == 'lint'
+Requires-Dist: isort; extra == 'lint'
+Requires-Dist: mypy; extra == 'lint'
+Requires-Dist: pylint; extra == 'lint'
+Requires-Dist: types-jsonschema; extra == 'lint'
+Description-Content-Type: text/markdown
+
+# matamata
+
+[![CI](https://github.com/anibalpacheco/matamata/actions/workflows/ci.yml/badge.svg)](https://github.com/anibalpacheco/matamata/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Model a **tournament knockout stage** in a small **JSON "language"** and render
+the schedule in **SVG** or **HTML table** format.
+
+**matamata** also lets a host system map documents representing championship
+knockout stages onto its own business objects (e.g. a Championship or Cup entity) and persist
+them apart from any presentation concern — updating results means editing a document,
+never the code.
+
+Example rendered from
+[`examples/libertadores-2026.json`](examples/libertadores-2026.json):
+
+![Copa Libertadores 2026 knockout stage](docs/libertadores-2026.png)
+
+## Quickstart
+
+Requires Python ≥ 3.10. No runtime dependencies.
+
+```bash
+git clone https://github.com/anibalpacheco/matamata.git
+cd matamata
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Render a self-contained example to an SVG file:
+
+```bash
+# via the installed command
+matamata examples/knockout-8.json -o knockout.svg
+
+# or via the module, writing to stdout
+python -m matamata examples/knockout-8.json > knockout.svg
+
+# or as an HTML table, the layout for small screens
+matamata examples/knockout-8.json -o knockout.html
+```
+
+Open the resulting file in a browser to view the schedule. To render your own cup,
+point the command at any JSON file that follows [`docs/format.md`](docs/format.md).
+
+Use it from Python:
+
+```python
+from matamata import load_stage, render_svg
+
+svg = render_svg(load_stage("examples/knockout-8.json"))
+```
+
+To use it in your own project instead, install straight from GitHub:
+
+```bash
+pip install git+https://github.com/anibalpacheco/matamata.git
+```
+
+## Examples
+
+Both examples are rendered from the JSON files in [`examples/`](examples/).
+
+The Copa Libertadores example above shows two-legged ties — each leg's goals are
+shown, shootouts appear in parentheses, and the winner of each tie is emphasized. The
+first quarterfinal is **host-resolved**: its legs carry only a `ref`, so its teams and
+scores come from `get_match` (see
+[`examples/libertadores_host.py`](examples/libertadores_host.py)) rather than from the
+document. Played ties take their team names from the legs; the final is a single match —
+one leg, so just one goal figure per side — with its `winnerof` links wiring the
+advancement tree.
+
+Single matches ([`knockout-8.json`](examples/knockout-8.json)) — one goal figure per
+side, with shootouts in parentheses. Sides that have not been resolved yet fall back to
+placeholders such as "Winner SF2":
+
+![World Cup knockout stage](docs/knockout-8.png)
+
+## The format
+
+The document is plain JSON, so any system can store and exchange it natively, and the
+language is designed so a match can evolve from a **placeholder** (e.g. "winner
+of QF1") into a **reference to a real match entity** — each leg can carry a `ref` to
+the real game, resolved dynamically by the host — without changing the language. The
+advancement tree is laid out **deterministically**: coordinates are
+computed directly and the SVG is emitted as a string, with no layout engine and no
+heavy dependencies.
+
+See [`docs/format.md`](docs/format.md) for the full specification and
+[`docs/schema.json`](docs/schema.json) for the JSON Schema. Worked examples live in
+[`examples/`](examples/).
+
+Minimal example:
+
+```json
+{
+  "tournament": "Copa Libertadores",
+  "season": "2026",
+  "rounds": [
+    {
+      "name": "Final",
+      "matches": [
+        {
+          "id": "final",
+          "legs": [
+            { "team1": "Flamengo", "goals1": 1, "team2": "Nacional", "goals2": 2 }
+          ],
+          "winner": 2
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Documentation
+
+[docs/index.md](docs/index.md) is the manual: rendering from the CLI and from Python
+(e.g. a Django view), feeding live data from your own database through
+`KnockoutStage`, updating the stored document with `apply_results` — including a
+before/after walkthrough of one call — and running the test suite.
+
+## Status
+
+Working: the language spec, JSON Schema, Python renderer, CLI and tests are in place,
+and the package is installable from GitHub.

matamata-0.0.1/README.md

@@ -0,0 +1,126 @@
+# matamata
+
+[![CI](https://github.com/anibalpacheco/matamata/actions/workflows/ci.yml/badge.svg)](https://github.com/anibalpacheco/matamata/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Model a **tournament knockout stage** in a small **JSON "language"** and render
+the schedule in **SVG** or **HTML table** format.
+
+**matamata** also lets a host system map documents representing championship
+knockout stages onto its own business objects (e.g. a Championship or Cup entity) and persist
+them apart from any presentation concern — updating results means editing a document,
+never the code.
+
+Example rendered from
+[`examples/libertadores-2026.json`](examples/libertadores-2026.json):
+
+![Copa Libertadores 2026 knockout stage](docs/libertadores-2026.png)
+
+## Quickstart
+
+Requires Python ≥ 3.10. No runtime dependencies.
+
+```bash
+git clone https://github.com/anibalpacheco/matamata.git
+cd matamata
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Render a self-contained example to an SVG file:
+
+```bash
+# via the installed command
+matamata examples/knockout-8.json -o knockout.svg
+
+# or via the module, writing to stdout
+python -m matamata examples/knockout-8.json > knockout.svg
+
+# or as an HTML table, the layout for small screens
+matamata examples/knockout-8.json -o knockout.html
+```
+
+Open the resulting file in a browser to view the schedule. To render your own cup,
+point the command at any JSON file that follows [`docs/format.md`](docs/format.md).
+
+Use it from Python:
+
+```python
+from matamata import load_stage, render_svg
+
+svg = render_svg(load_stage("examples/knockout-8.json"))
+```
+
+To use it in your own project instead, install straight from GitHub:
+
+```bash
+pip install git+https://github.com/anibalpacheco/matamata.git
+```
+
+## Examples
+
+Both examples are rendered from the JSON files in [`examples/`](examples/).
+
+The Copa Libertadores example above shows two-legged ties — each leg's goals are
+shown, shootouts appear in parentheses, and the winner of each tie is emphasized. The
+first quarterfinal is **host-resolved**: its legs carry only a `ref`, so its teams and
+scores come from `get_match` (see
+[`examples/libertadores_host.py`](examples/libertadores_host.py)) rather than from the
+document. Played ties take their team names from the legs; the final is a single match —
+one leg, so just one goal figure per side — with its `winnerof` links wiring the
+advancement tree.
+
+Single matches ([`knockout-8.json`](examples/knockout-8.json)) — one goal figure per
+side, with shootouts in parentheses. Sides that have not been resolved yet fall back to
+placeholders such as "Winner SF2":
+
+![World Cup knockout stage](docs/knockout-8.png)
+
+## The format
+
+The document is plain JSON, so any system can store and exchange it natively, and the
+language is designed so a match can evolve from a **placeholder** (e.g. "winner
+of QF1") into a **reference to a real match entity** — each leg can carry a `ref` to
+the real game, resolved dynamically by the host — without changing the language. The
+advancement tree is laid out **deterministically**: coordinates are
+computed directly and the SVG is emitted as a string, with no layout engine and no
+heavy dependencies.
+
+See [`docs/format.md`](docs/format.md) for the full specification and
+[`docs/schema.json`](docs/schema.json) for the JSON Schema. Worked examples live in
+[`examples/`](examples/).
+
+Minimal example:
+
+```json
+{
+  "tournament": "Copa Libertadores",
+  "season": "2026",
+  "rounds": [
+    {
+      "name": "Final",
+      "matches": [
+        {
+          "id": "final",
+          "legs": [
+            { "team1": "Flamengo", "goals1": 1, "team2": "Nacional", "goals2": 2 }
+          ],
+          "winner": 2
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Documentation
+
+[docs/index.md](docs/index.md) is the manual: rendering from the CLI and from Python
+(e.g. a Django view), feeding live data from your own database through
+`KnockoutStage`, updating the stored document with `apply_results` — including a
+before/after walkthrough of one call — and running the test suite.
+
+## Status
+
+Working: the language spec, JSON Schema, Python renderer, CLI and tests are in place,
+and the package is installable from GitHub.

matamata-0.0.1/docs/apply-after.json

@@ -0,0 +1,57 @@
+{
+  "tournament": "Champions League",
+  "season": "2025/26",
+  "rounds": [
+    {
+      "name": "Semifinals",
+      "matches": [
+        {
+          "id": "sf1",
+          "team1": "Real Madrid",
+          "team2": "Barcelona",
+          "legs": [
+            {
+              "goals1": 1,
+              "goals2": 0
+            },
+            {
+              "goals1": 0,
+              "goals2": 1,
+              "pen1": 4,
+              "pen2": 2
+            }
+          ],
+          "winner": 1
+        },
+        {
+          "id": "sf2",
+          "team1": "Bayern München",
+          "team2": "Manchester City",
+          "winner": 2,
+          "legs": [
+            {
+              "goals1": 0,
+              "goals2": 2
+            },
+            {
+              "goals1": 1,
+              "goals2": 1
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "Final",
+      "matches": [
+        {
+          "id": "f",
+          "winnerof1": "sf1",
+          "winnerof2": "sf2",
+          "team2": "Manchester City",
+          "team1": "Real Madrid"
+        }
+      ]
+    }
+  ]
+}

matamata-0.0.1/docs/apply-before.json

@@ -0,0 +1,41 @@
+{
+  "tournament": "Champions League",
+  "season": "2025/26",
+  "rounds": [
+    {
+      "name": "Semifinals",
+      "matches": [
+        {
+          "id": "sf1",
+          "team1": "Real Madrid",
+          "team2": "Barcelona",
+          "legs": [
+            { "goals1": 1, "goals2": 0 },
+            {}
+          ]
+        },
+        {
+          "id": "sf2",
+          "team1": "Bayern München",
+          "team2": "Manchester City",
+          "winner": 2,
+          "legs": [
+            { "goals1": 0, "goals2": 2 },
+            { "goals1": 1, "goals2": 1 }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "Final",
+      "matches": [
+        {
+          "id": "f",
+          "winnerof1": "sf1",
+          "winnerof2": "sf2",
+          "team2": "Manchester City"
+        }
+      ]
+    }
+  ]
+}