korb 0.2.8__tar.gz → 0.3.0__tar.gz

{korb-0.2.8 → korb-0.3.0}/.github/workflows/release.yml

@@ -29,6 +29,26 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: uv run ruff check korb/ tests/
+
+      - name: Format check
+        if: matrix.python-version == '3.12'
+        run: uv run ruff format --check korb/ tests/
+
+      - name: Type check
+        if: matrix.python-version == '3.12'
+        run: uv run basedpyright korb
+
+      - name: Complexity budget
+        if: matrix.python-version == '3.12'
+        run: |
+          if uvx radon cc korb -s --show-closures | grep -E '\-\s(C|D|E|F)\s'; then
+            echo "::error::Complexity C or worse found"
+            exit 1
+          fi
+
       - name: Run tests
         run: uv run pytest -v --tb=short
 

{korb-0.2.8 → korb-0.3.0}/.github/workflows/test.yml

@@ -26,5 +26,25 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: uv run ruff check korb/ tests/
+
+      - name: Format check
+        if: matrix.python-version == '3.12'
+        run: uv run ruff format --check korb/ tests/
+
+      - name: Type check
+        if: matrix.python-version == '3.12'
+        run: uv run basedpyright korb
+
+      - name: Complexity budget
+        if: matrix.python-version == '3.12'
+        run: |
+          if uvx radon cc korb -s --show-closures | grep -E '\-\s(C|D|E|F)\s'; then
+            echo "::error::Complexity C or worse found"
+            exit 1
+          fi
+
       - name: Run tests
         run: uv run pytest -v --tb=short

{korb-0.2.8 → korb-0.3.0}/.gitignore

@@ -6,6 +6,11 @@ __pycache__/
 dist/
 build/
 
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
 # Lock file
 uv.lock
 

korb-0.3.0/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.3.0] — 2026-10-25
+
+### Added
+
+- `korb/download.py` module with a configurable request timeout and
+  shared rate-limit helper.
+- Coverage for cancelled games marked with `title="Spiel abgesagt"`.
+- CLI-level tests for `top`, parser dispatch, download failures, and
+  team metrics/bar output.
+- Lint, format, type-check, and complexity gates in CI.
+
+### Changed
+
+- Consolidated team-stat updates into `standings.record_game()` and
+  standings table rendering into `standings.print_standings_rows()`.
+- `predict` now resolves paths through the shared path helpers and
+  parses the results file once.
+- `__main__.py` HTTP/download code moved out; CLI parser construction
+  separated from dispatch.
+- `__main__.py` is now included in coverage.
+- JSON key documentation now covers the `ergebnisse` response and
+  clarifies that `download` emits no JSON.
+- `print_metrics()` no longer takes a league name (breaking API change).
+- Type annotations added to parser state attributes; ruff targets the
+  Python 3.10 floor.
+- Updated the supported DBB target to `12.01.1-f733da5`.
+- Configured basedpyright for CLI-boundary `Any` values and style
+  diagnostics so the type-check gate exits cleanly.
+
+### Removed
+
+- Unreachable draw branches, the unused `print_metrics(league_name)`
+  parameter, and the broken Hatch `features = ["dev"]` environment.
+
+### Fixed
+
+- Completed the missing changelog entries for 0.2.4–0.2.9.
+- `download --all` now refreshes leagues in numeric order.
+- Downloads reject empty responses instead of overwriting cached HTML.
+- `schedule --b2b` detects back-to-back games from the full schedule,
+  including completed games before a pending fixture, and keeps the
+  marker column aligned.
+- Result rows with nested tables inside cells now parse correctly.
+- Malformed rows with a missing `</tr>` no longer discard later rows.
+- `predict` matches completed fixtures by game number, so rescheduled
+  games are not counted twice, and treats past-dated unplayed games as
+  pending.
+- Parsed names collapse repeated whitespace; team filters normalize
+  whitespace and reject empty names.
+- Standings follow DBB placement rules: fewer games, then head-to-head
+  points and differential before overall differential.
+- 20:0 and 0:20 results are treated as DBB forfeits and deduct one
+  point from the losing team; JSON includes the `penalty` field.
+- Cancelled result rows marked with `title="Spiel abgesagt"` are now
+  skipped, matching the schedule parser.
+- `top -n` and `team --last-k` reject non-positive values instead of
+  producing misleading output.
+
+---
+
+## [0.2.9] — 2026-07-26
+
+### Changed
+
+- Fixed result ordering, improved code quality, and added test coverage.
+- Stopped tracking `.coverage`.
+
+---
+
+## [0.2.8] — 2026-05-11
+
+### Removed
+
+- `skill` subcommand and `korb/skills/` package.
+
+### Changed
+
+- Replaced black/isort/flake8 with ruff.
+- Rewrote `README.md` for public release and cleaned up inline comments
+  and `noqa` annotations.
+
+---
+
+## [0.2.7] — 2026-05-06
+
+### Added
+
+- `download --all` / `-a` refreshes all previously downloaded leagues.
+- `discover_league_ids()` scans `files/` for downloaded league IDs.
+
+---
+
+## [0.2.6] — 2026-04-23
+
+### Added
+
+- `ergebnisse` subcommand for viewing completed game results.
+
+---
+
+## [0.2.5] — 2026-04-20
+
+### Added
+
+- Game dates in per-team results and JSON output.
+
+---
+
+## [0.2.4] — 2026-04-15
+
+### Changed
+
+- Schedule output sorted by date.
+- Dead-code and formatting cleanup.
+
+---
+
+## [0.2.3] — 2026-04-10
+
+### Added
+
+- `skill` subcommand — prints built-in AI skill prompts to stdout.
+- `skill --list` / `-l` flag — lists available skill names and filenames.
+- `korb/skills/` package with `SKILL_MAP` and `get_skill_text()` using `importlib.resources`.
+- Two bundled skills: `analysis` (team deep-dive) and `prediction` (league top-N forecast).
+- Skill markdown files now shipped inside the `korb` package (included in pip distributions).
+
+### Changed
+
+- Migrated `skills/` from project root into `korb/skills/` for proper wheel inclusion.
+
+---
+
+## [0.2.2] — 2026-04-09
+
+### Added
+
+- `LeagueInfo` dataclass in `core.py` — bundles league name and Liganr. extracted from HTML.
+- All `--json` outputs now include `liga_name`, `liga_number`, and `ligaid` metadata at the top level.
+- New `extract_league_info()` function parses both league name and `Liganr.: <number>` from DBB HTML.
+
+### Changed
+
+- `standings`, `team`, `schedule`, `predict`, and `top` JSON responses are now wrapped objects instead of flat lists, with league metadata and a named data key (`standings`, `results`, `schedule`, `predictions`, `top`).
+- `read_games()`, `calculate_standings()`, `parse_schedule()`, `get_team_results()`, and `predict_standings()` return `LeagueInfo` instead of a bare `str` league name.
+
+---
+
+## [0.2.1] — 2026-04-08
+
+### Changed
+
+- Download requests now use browser-spoofing headers (Chrome 131 fingerprint) instead of the plain `korb/<version>` User-Agent to avoid basic bot detection.
+- Added `gzip`/`deflate` response decompression to match the advertised `Accept-Encoding`.
+- Added a random 0.5–1.5 s delay between consecutive HTTP requests to avoid rate-limit triggers.
+
+---
+
+## [0.2.0] — 2026-04-08
+
+### Changed
+
+- `--liganr` renamed to `--ligaid` / `-l` and promoted to global flag.
+- `--schedule` / `-s` global flag replaces subcommand-local `--html` on `schedule` and `predict`.
+- `download` subcommand now uses global `--ligaid` instead of a positional argument.
+- Download logic extracted into reusable `_download()` helper.
+
+### Added
+
+- `--download` / `-d` global flag — downloads fresh data before running any command.
+
+---
+
+## [0.1.0] — 2026-04-08
+
+### Added
+
+- `standings` command — full league table with points, differentials, averages.
+- `team` command — game-by-game results, sparklines, bar chart, quality metrics.
+- `schedule` command — schedule viewer with back-to-back detection, pending/team filters.
+- `predict` command — multiplicative efficiency model for final standings forecast.
+- `top` command — quick leaderboard with ASCII bar chart.
+- `download` command — fetch HTML data from basketball-bund.net.
+- `--json` flag for machine-readable output on all commands.
+- `--version` flag.

{korb-0.2.8 → korb-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: korb
-Version: 0.2.8
+Version: 0.3.0
 Summary: A CLI toolkit for DBB basketball league analysis
 Project-URL: Homepage, https://github.com/malvavisc0/korb
 Project-URL: Repository, https://github.com/malvavisc0/korb
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -49,7 +50,7 @@ platform and provides standings, results, schedules, predictions, and more.
 - 🔮 **Predict** — efficiency-model-based final standings forecast
 - 🥇 **Top** — quick leaderboard with ASCII bar chart
 - 📥 **Download** — fetch fresh HTML data directly from basketball-bund.net
-- 🔧 **`--json`** — machine-readable output for all commands
+- 🔧 **`--json`** — machine-readable output for data commands (not `download`)
 
 ## Installation
 
@@ -58,7 +59,7 @@ platform and provides standings, results, schedules, predictions, and more.
 git clone https://github.com/malvavisc0/korb && cd korb
 uv sync
 
-# With pip
+# With pip (end-user install)
 pip install .
 ```
 
@@ -169,8 +170,9 @@ The `predict` command estimates final standings using a **multiplicative efficie
 ```
 korb/
 ├── __init__.py      # Package marker & version
-├── __main__.py      # CLI entry point & download command
+├── __main__.py      # CLI entry point & command handlers
 ├── core.py          # Shared models, HTML parsing, utilities
+├── download.py      # HTTP downloader, headers, rate limiting
 ├── ergebnisse.py    # Game results viewer & filter
 ├── predict.py       # Multiplicative efficiency prediction model
 ├── schedule.py      # HTML schedule parser & filters
@@ -190,14 +192,18 @@ korb/
 # Install with dev tools
 uv sync --group dev
 
-# Lint & format
+# Lint, format & type-check
 uv run ruff check korb/ tests/
 uv run ruff format korb/ tests/
+uv run basedpyright korb
 
 # Run tests
 uv run pytest
 ```
 
+Project conventions are documented in
+[`docs/coding-standard.md`](docs/coding-standard.md).
+
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

{korb-0.2.8 → korb-0.3.0}/README.md

@@ -24,7 +24,7 @@ platform and provides standings, results, schedules, predictions, and more.
 - 🔮 **Predict** — efficiency-model-based final standings forecast
 - 🥇 **Top** — quick leaderboard with ASCII bar chart
 - 📥 **Download** — fetch fresh HTML data directly from basketball-bund.net
-- 🔧 **`--json`** — machine-readable output for all commands
+- 🔧 **`--json`** — machine-readable output for data commands (not `download`)
 
 ## Installation
 
@@ -33,7 +33,7 @@ platform and provides standings, results, schedules, predictions, and more.
 git clone https://github.com/malvavisc0/korb && cd korb
 uv sync
 
-# With pip
+# With pip (end-user install)
 pip install .
 ```
 
@@ -144,8 +144,9 @@ The `predict` command estimates final standings using a **multiplicative efficie
 ```
 korb/
 ├── __init__.py      # Package marker & version
-├── __main__.py      # CLI entry point & download command
+├── __main__.py      # CLI entry point & command handlers
 ├── core.py          # Shared models, HTML parsing, utilities
+├── download.py      # HTTP downloader, headers, rate limiting
 ├── ergebnisse.py    # Game results viewer & filter
 ├── predict.py       # Multiplicative efficiency prediction model
 ├── schedule.py      # HTML schedule parser & filters
@@ -165,14 +166,18 @@ korb/
 # Install with dev tools
 uv sync --group dev
 
-# Lint & format
+# Lint, format & type-check
 uv run ruff check korb/ tests/
 uv run ruff format korb/ tests/
+uv run basedpyright korb
 
 # Run tests
 uv run pytest
 ```
 
+Project conventions are documented in
+[`docs/coding-standard.md`](docs/coding-standard.md).
+
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

korb-0.3.0/docs/coding-standard.md

@@ -0,0 +1,152 @@
+# Python Developer AI Agent
+
+## Communication
+You are talking to seniors. Be terse — no preamble, no recap, no
+hand-holding, no "here's what I did" summaries. State results, not
+intentions. Skip explanations unless explicitly asked. Never narrate
+tool use. Answer the question; move on.
+
+## Project
+korb — a zero-runtime-dependency Python CLI for DBB (Deutscher
+Basketball Bund) basketball league analysis. It parses HTML from the
+legacy JSP platform at basketball-bund.net (target: DBB Version
+≤12.01.1-f733da5) and exposes standings, results, schedules,
+predictions, and team metrics. An argparse CLI (`korb/__main__.py`)
+dispatches subcommands; `korb/download.py` fetches fresh league HTML
+into `files/<ligaid>/`.
+
+## Stack
+- Python 3.10+ (CI covers 3.10–3.14), uv, pyproject.toml (hatchling,
+  flat `korb/` package layout)
+- Zero runtime dependencies: standard library only (`argparse`,
+  `html.parser`, `urllib`, `dataclasses`, `zoneinfo`)
+- Dev dependencies: pytest, pytest-cov, ruff, basedpyright
+- CLI: argparse subcommands in `korb/__main__.py`, entry point
+  `korb = "korb.__main__:main"`
+- Type checker: **basedpyright** (configured in pyproject; CLI-boundary
+  `Any` and style diagnostics disabled)
+- Lint/format: **ruff** (line-length 88, target py310 — the minimum
+  supported Python)
+- Complexity: **radon** (ad hoc via `uvx`)
+- Dead code: **vulture** (advisory; no config yet)
+- Packaging: hatchling; version lives in `korb/__init__.py`
+
+## Commands
+```bash
+uv sync --group dev
+uv run korb --help
+uv run korb --ligaid 12345 download
+uv run ruff check --fix korb/ tests/
+uv run ruff format korb/ tests/
+uv run basedpyright korb
+uvx radon cc korb -s --show-closures
+uvx vulture korb tests --min-confidence 60
+uv run pytest
+```
+Run `ruff check`, `ruff format --check`, `basedpyright`, and `pytest`
+after every change. `basedpyright` must report zero errors; do not add
+new warnings. CI runs the same gates plus the radon complexity check.
+
+## Complexity budget
+`radon cc` must report **no block ranked C or worse** — every
+function/method stays at rank A or B (complexity ≤ 10). This applies to
+the whole codebase: a pre-existing C+ block is still a defect and must
+be fixed in the same pass (early returns, extract helpers, dispatch
+tables). Verify with:
+```bash
+uvx radon cc korb -s --show-closures | grep -E '\-\s(C|D|E|F)\s'   # must be empty
+```
+
+## Dead code
+No dead code. Vulture is not configured here, and its hits on
+`HTMLParser.handle_*` callbacks, pytest fixtures, and `unittest.mock`
+attributes are false positives — never delete those. Treat every other
+hit as a suspect: check for a registration site before deleting. Real
+dead code (never-read fields, zero-call-site functions) goes out in the
+same pass. If vulture becomes a gate, add `[tool.vulture]` to
+pyproject.toml and make the default run clean.
+
+## PII
+Never use or commit PII — not in code, tests, docs, plans, fixtures,
+examples, commit messages, or changelog entries. PII is any real
+person's data: names, contact details, message bodies, transcripts,
+trace/session ids tied to a person. Rules:
+
+- Tests, docstrings, and examples use fictional identities only.
+  Fixtures use synthetic leagues, teams, and scores ("Test
+  Bezirksliga", "Team Alpha", `Liganr.: 99999`), never a real league
+  export.
+- Downloaded HTML contains real league data; it stays in the ignored
+  `files/<ligaid>/` tree and never enters git.
+- Before committing anything derived from a real export, grep the diff
+  for names you saw in it: `git diff | rg -i "<name>"`. If it came from
+  an export, it does not go in the repo.
+
+## Priority
+Clean, simple, maintainable code. Nothing else.
+
+## Commits
+One-line messages only. No body, no trailers.
+
+## Rules
+- DRY, KISS
+- Zero runtime dependencies — stdlib first, no new dependency without
+  an explicit decision
+- No unnecessary complexity
+- No defensive fallbacks / over-engineering
+- Explicit > implicit
+- Type hints for all `korb/` code (the hatch-parsed `__version__`
+  constant is the exception). Tests follow pytest conventions and need
+  not be fully annotated
+- Python ≥3.10 syntax and stdlib only (CI runs 3.10 through 3.14)
+- PEP 8 (ruff enforces, line-length 88)
+- Meaningful names, small functions
+- Fail fast and clearly: user-facing errors go to stderr and exit 1.
+  Malformed HTML table rows are the one intentional exception: parsers
+  skip them so one bad row does not discard an entire league
+- No clever tricks
+- Docstrings for public APIs
+- No unnecessary inline comments
+- Use uv for development and CI (never pip / system python). README may
+  document pip for end users
+- No mutable module-level state. Read-only constants (`HEADERS`, URL
+  templates, point values) are fine; never mutate them at runtime
+- Module-local helpers take a leading underscore; anything imported by
+  production code is public. Tests may import private helpers for
+  focused unit tests. `core.py` is the shared-helper home
+- No dead code
+- No Python file over 600 lines in `korb/` or `tests/`
+
+## Style
+Write the simplest correct solution. Delete anything that isn't needed.
+
+## Conventions
+- Commands live in `korb/__main__.py`: a `cmd_<name>(args)` handler
+  plus an argparse subparser in `main()` wired with
+  `set_defaults(func=cmd_<name>)`. Global flags are `--results`,
+  `--schedule`, `--json`, `--ligaid`, `--download`.
+- Feature modules sit next to the CLI (`standings.py`, `team.py`,
+  `schedule.py`, `predict.py`, `ergebnisse.py`, `download.py`); shared
+  models, HTML parsing, date/score helpers, and output headers live in
+  `core.py`.
+- HTML parsing extends the shared public `DBBRowParser`
+  (`<td>`/`<tr>`/`<strike>` state machine). Parser changes need a
+  fixture in `tests/fixtures/` and a test; cover cancelled rows
+  (`<strike>`, `title="Spiel abgesagt"`) and finalized schedules.
+- Parsers return `(data, LeagueInfo)`. Every data command's `--json`
+  response is a wrapped object built with `_liga_meta(...)` plus a
+  named data key: `standings`, `results` (team), `ergebnisse`,
+  `schedule`, `predictions`, and `top`. `download` is a side-effect
+  command and emits no JSON.
+- Data paths resolve as `files/<ligaid>/ergebnisse.html` and
+  `files/<ligaid>/spielplan.html`; explicit `--results` / `--schedule`
+  win. Use `_resolve_results` / `_resolve_schedule`, not ad hoc paths.
+- Downloads live in `korb/download.py` and must keep the
+  browser-spoofing headers, gzip/deflate handling, a request timeout,
+  and the 1–3 s delay between requests; the legacy host rate-limits.
+  Reference: https://www.basketball-bund.net
+- Bump `__version__` in `korb/__init__.py` and update `CHANGELOG.md`
+  for user-visible changes. Release tags (`v*`) must match the version.
+- Tests: one file per module (`tests/test_<module>.py`), pytest with
+  coverage enabled by default in `pyproject.toml`. New CLI commands
+  need command-level tests, not only module-level unit tests.

korb-0.3.0/korb/__init__.py

@@ -0,0 +1,6 @@
+"""Basketball league analysis package for DBB (Deutscher Basketball Bund).
+
+Target: DBB Version ≤12.01.1-f733da5 (legacy JSP platform).
+"""
+
+__version__ = "0.3.0"