korb 0.2.7__tar.gz → 0.2.9__tar.gz

{korb-0.2.7 → korb-0.2.9}/.gitignore

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

korb-0.2.9/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: korb
+Version: 0.2.9
+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
+Project-URL: Issues, https://github.com/malvavisc0/korb/issues
+Author-email: Malvavisc0 <207609879+malvavisc0@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: basketball,cli,dbb,german-basketball,sports-analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <strong>🏀 korb</strong><br>
+  <em>A CLI toolkit for DBB basketball league analysis</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/deps-zero-brightgreen" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+</p>
+
+---
+
+**korb** is a zero-dependency Python CLI that parses HTML from the
+[DBB](https://www.basketball-bund.net) (Deutscher Basketball Bund) legacy JSP
+platform and provides standings, results, schedules, predictions, and more.
+
+## Features
+
+- 📊 **Standings** — full league table with points, differentials, averages
+- 🏀 **Team** — game-by-game results, sparklines, quality metrics
+- 📋 **Ergebnisse** — all completed game results with optional team filter
+- 📅 **Schedule** — with back-to-back detection, filtering, pending games
+- 🔮 **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
+
+## Installation
+
+```bash
+# With uv (recommended)
+git clone https://github.com/malvavisc0/korb && cd korb
+uv sync
+
+# With pip
+pip install .
+```
+
+After installation, the `korb` CLI is available inside the virtual environment.
+Use `uv run korb` to invoke it, or activate the venv first.
+
+## Quick Start
+
+```bash
+# Download league data
+uv run korb --ligaid 51187 download
+
+# View standings
+uv run korb --ligaid 51187 standings
+
+# Download fresh data + predict in one go
+uv run korb --ligaid 51187 --download predict
+```
+
+## Finding your Liga ID
+
+The `--ligaid` value comes from the `liga_id` parameter in the DBB league URL:
+
+```
+https://www.basketball-bund.net/index.jsp?Action=103&liga_id=51187
+                                                           ^^^^^
+                                                           this is your liga ID
+```
+
+## Commands
+
+### `download` — Fetch HTML data
+
+```bash
+uv run korb --ligaid 12345 download
+uv run korb download --all   # refresh all previously downloaded leagues
+```
+
+Saves `ergebnisse.html` and `spielplan.html` into `files/<ligaid>/`.
+
+### `standings` — League table
+
+```bash
+uv run korb --ligaid 12345 standings
+```
+
+### `ergebnisse` — Game results
+
+```bash
+uv run korb --ligaid 12345 ergebnisse
+uv run korb --ligaid 12345 ergebnisse --team "Hawks"
+```
+
+### `team` — Deep dive on a single team
+
+```bash
+uv run korb --ligaid 12345 team "Thunder"
+uv run korb --ligaid 12345 team "Thunder" --bars --last-k 5 --metrics
+```
+
+### `schedule` — Game calendar
+
+```bash
+uv run korb --ligaid 12345 schedule --pending
+uv run korb --ligaid 12345 schedule --team "Hawks" --pending --b2b
+```
+
+### `predict` — Forecast final standings
+
+```bash
+uv run korb --ligaid 12345 predict
+```
+
+### `top` — Quick leaderboard
+
+```bash
+uv run korb --ligaid 12345 top -n 5
+```
+
+### Global flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON instead of formatted tables |
+| `--download`, `-d` | Fetch fresh data before running the command |
+| `--ligaid`, `-l` | Liga ID (resolves file paths automatically) |
+| `--results`, `-r` | Explicit path to HTML results file |
+| `--schedule`, `-s` | Explicit path to HTML schedule file |
+| `--version`, `-V` | Show version |
+
+## How Predictions Work
+
+The `predict` command estimates final standings using a **multiplicative efficiency model**:
+
+| Factor | How it works |
+|---|---|
+| **Offensive rating** | Team's scored points vs. league average (>1.0 = above avg) |
+| **Defensive rating** | Points allowed vs. league average (>1.0 = worse defense) |
+| **Recency weighting** | 60-day half-life — recent games count more |
+| **Recent form** | Last 5 games blended at 30% weight into ratings |
+| **Home advantage** | 3% scoring boost applied symmetrically |
+| **B2B fatigue** | ≤36h between games → 5% offense/defense penalty |
+| **New teams** | <3 games → ratings blended toward league average |
+| **No draws** | Ties broken by home advantage (basketball has OT) |
+
+## Project Structure
+
+```
+korb/
+├── __init__.py      # Package marker & version
+├── __main__.py      # CLI entry point & download command
+├── core.py          # Shared models, HTML parsing, utilities
+├── ergebnisse.py    # Game results viewer & filter
+├── predict.py       # Multiplicative efficiency prediction model
+├── schedule.py      # HTML schedule parser & filters
+├── standings.py     # Standings calculator
+└── team.py          # Team results viewer & metrics
+```
+
+**Requirements:** Python 3.10+ · [uv](https://docs.astral.sh/uv/) · No runtime dependencies
+
+> **Note:** Downloaded HTML files and `--ligaid` paths resolve relative to your
+> current working directory (`files/<ligaid>/`). Run `korb` from the project root
+> or pass explicit `--results` / `--schedule` paths.
+
+## Development
+
+```bash
+# Install with dev tools
+uv sync --group dev
+
+# Lint & format
+uv run ruff check korb/ tests/
+uv run ruff format korb/ tests/
+
+# Run tests
+uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)

korb-0.2.9/README.md

@@ -0,0 +1,178 @@
+<p align="center">
+  <strong>🏀 korb</strong><br>
+  <em>A CLI toolkit for DBB basketball league analysis</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/deps-zero-brightgreen" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+</p>
+
+---
+
+**korb** is a zero-dependency Python CLI that parses HTML from the
+[DBB](https://www.basketball-bund.net) (Deutscher Basketball Bund) legacy JSP
+platform and provides standings, results, schedules, predictions, and more.
+
+## Features
+
+- 📊 **Standings** — full league table with points, differentials, averages
+- 🏀 **Team** — game-by-game results, sparklines, quality metrics
+- 📋 **Ergebnisse** — all completed game results with optional team filter
+- 📅 **Schedule** — with back-to-back detection, filtering, pending games
+- 🔮 **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
+
+## Installation
+
+```bash
+# With uv (recommended)
+git clone https://github.com/malvavisc0/korb && cd korb
+uv sync
+
+# With pip
+pip install .
+```
+
+After installation, the `korb` CLI is available inside the virtual environment.
+Use `uv run korb` to invoke it, or activate the venv first.
+
+## Quick Start
+
+```bash
+# Download league data
+uv run korb --ligaid 51187 download
+
+# View standings
+uv run korb --ligaid 51187 standings
+
+# Download fresh data + predict in one go
+uv run korb --ligaid 51187 --download predict
+```
+
+## Finding your Liga ID
+
+The `--ligaid` value comes from the `liga_id` parameter in the DBB league URL:
+
+```
+https://www.basketball-bund.net/index.jsp?Action=103&liga_id=51187
+                                                           ^^^^^
+                                                           this is your liga ID
+```
+
+## Commands
+
+### `download` — Fetch HTML data
+
+```bash
+uv run korb --ligaid 12345 download
+uv run korb download --all   # refresh all previously downloaded leagues
+```
+
+Saves `ergebnisse.html` and `spielplan.html` into `files/<ligaid>/`.
+
+### `standings` — League table
+
+```bash
+uv run korb --ligaid 12345 standings
+```
+
+### `ergebnisse` — Game results
+
+```bash
+uv run korb --ligaid 12345 ergebnisse
+uv run korb --ligaid 12345 ergebnisse --team "Hawks"
+```
+
+### `team` — Deep dive on a single team
+
+```bash
+uv run korb --ligaid 12345 team "Thunder"
+uv run korb --ligaid 12345 team "Thunder" --bars --last-k 5 --metrics
+```
+
+### `schedule` — Game calendar
+
+```bash
+uv run korb --ligaid 12345 schedule --pending
+uv run korb --ligaid 12345 schedule --team "Hawks" --pending --b2b
+```
+
+### `predict` — Forecast final standings
+
+```bash
+uv run korb --ligaid 12345 predict
+```
+
+### `top` — Quick leaderboard
+
+```bash
+uv run korb --ligaid 12345 top -n 5
+```
+
+### Global flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON instead of formatted tables |
+| `--download`, `-d` | Fetch fresh data before running the command |
+| `--ligaid`, `-l` | Liga ID (resolves file paths automatically) |
+| `--results`, `-r` | Explicit path to HTML results file |
+| `--schedule`, `-s` | Explicit path to HTML schedule file |
+| `--version`, `-V` | Show version |
+
+## How Predictions Work
+
+The `predict` command estimates final standings using a **multiplicative efficiency model**:
+
+| Factor | How it works |
+|---|---|
+| **Offensive rating** | Team's scored points vs. league average (>1.0 = above avg) |
+| **Defensive rating** | Points allowed vs. league average (>1.0 = worse defense) |
+| **Recency weighting** | 60-day half-life — recent games count more |
+| **Recent form** | Last 5 games blended at 30% weight into ratings |
+| **Home advantage** | 3% scoring boost applied symmetrically |
+| **B2B fatigue** | ≤36h between games → 5% offense/defense penalty |
+| **New teams** | <3 games → ratings blended toward league average |
+| **No draws** | Ties broken by home advantage (basketball has OT) |
+
+## Project Structure
+
+```
+korb/
+├── __init__.py      # Package marker & version
+├── __main__.py      # CLI entry point & download command
+├── core.py          # Shared models, HTML parsing, utilities
+├── ergebnisse.py    # Game results viewer & filter
+├── predict.py       # Multiplicative efficiency prediction model
+├── schedule.py      # HTML schedule parser & filters
+├── standings.py     # Standings calculator
+└── team.py          # Team results viewer & metrics
+```
+
+**Requirements:** Python 3.10+ · [uv](https://docs.astral.sh/uv/) · No runtime dependencies
+
+> **Note:** Downloaded HTML files and `--ligaid` paths resolve relative to your
+> current working directory (`files/<ligaid>/`). Run `korb` from the project root
+> or pass explicit `--results` / `--schedule` paths.
+
+## Development
+
+```bash
+# Install with dev tools
+uv sync --group dev
+
+# Lint & format
+uv run ruff check korb/ tests/
+uv run ruff format korb/ tests/
+
+# Run tests
+uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)

korb-0.2.9/korb/__init__.py

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

{korb-0.2.7 → korb-0.2.9}/korb/__main__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Basketball league CLI for DBB (Deutscher Basketball Bund) data.
 
-Target: DBB Version ≤11.50.0-623b018 (legacy JSP platform).
+Target: DBB Version ≤11.50.1-2f7f327 (legacy JSP platform).
 """
 
 import argparse
@@ -26,8 +26,7 @@ from .schedule import (
     parse_schedule,
     print_schedule,
 )
-from .skills import SKILL_MAP, get_skill_text
-from .standings import calculate_standings, print_table
+from .standings import Standing, calculate_standings, print_table
 from .team import get_team_results, print_bars, print_metrics, print_results
 
 
@@ -39,7 +38,7 @@ def _json_out(data: object) -> None:
 def _liga_meta(
     league_info: LeagueInfo,
     ligaid: int | None,
-) -> dict:
+) -> dict[str, object]:
     """Build liga metadata dict for JSON output.
 
     Args:
@@ -55,18 +54,41 @@ def _liga_meta(
     }
 
 
+def _resolve_path(
+    explicit: str | None, ligaid: int | None, filename: str, flag: str, label: str
+) -> str:
+    """Resolve an HTML path from an explicit flag value or --ligaid.
+
+    Exits with an error if neither is provided.
+    """
+    if explicit is not None:
+        return explicit
+    if ligaid is None:
+        print(
+            f"Error: pass {flag} PATH or --ligaid LIGAID for {label}.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return str(Path("files") / str(ligaid) / filename)
+
+
+def _resolve_results(args: argparse.Namespace, label: str) -> str:
+    """Resolve the results HTML path from --results or --ligaid."""
+    return _resolve_path(
+        args.results, args.ligaid, "ergebnisse.html", "--results", label
+    )
+
+
+def _resolve_schedule(args: argparse.Namespace, label: str) -> str:
+    """Resolve the schedule HTML path from --schedule or --ligaid."""
+    return _resolve_path(
+        args.schedule, args.ligaid, "spielplan.html", "--schedule", label
+    )
+
+
 def cmd_standings(args: argparse.Namespace) -> None:
     """Handle 'standings' subcommand."""
-    fp = args.results
-    if fp is None:
-        if args.ligaid is None:
-            print(
-                "Error: pass --results PATH or --ligaid LIGAID " "for standings.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        fp = str(Path("files") / str(args.ligaid) / "ergebnisse.html")
-
+    fp = _resolve_results(args, "standings")
     standings, league_info = calculate_standings(fp)
     if args.json:
         _json_out(
@@ -81,16 +103,7 @@ def cmd_standings(args: argparse.Namespace) -> None:
 
 def cmd_team(args: argparse.Namespace) -> None:
     """Handle 'team' subcommand."""
-    fp = args.results
-    if fp is None:
-        if args.ligaid is None:
-            print(
-                "Error: pass --results PATH or --ligaid LIGAID " "for team results.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        fp = str(Path("files") / str(args.ligaid) / "ergebnisse.html")
-
+    fp = _resolve_results(args, "team results")
     results, league_info = get_team_results(args.name, fp)
     if args.json:
         data = [r.to_dict() for r in results]
@@ -113,19 +126,9 @@ def cmd_team(args: argparse.Namespace) -> None:
 
 def cmd_ergebnisse(args: argparse.Namespace) -> None:
     """Handle 'ergebnisse' subcommand."""
-    fp = args.results
-    if fp is None:
-        if args.ligaid is None:
-            print(
-                "Error: pass --results PATH or --ligaid LIGAID " "for ergebnisse.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        fp = str(Path("files") / str(args.ligaid) / "ergebnisse.html")
-
+    fp = _resolve_results(args, "ergebnisse")
     games, league_info = read_games(fp)
     filtered = filter_ergebnisse(games, team=args.team)
-    # Sort chronologically (oldest first) for consistent output
     filtered.sort(key=lambda g: g.date)
     if args.json:
         _json_out(
@@ -149,16 +152,7 @@ def cmd_ergebnisse(args: argparse.Namespace) -> None:
 
 def cmd_schedule(args: argparse.Namespace) -> None:
     """Handle 'schedule' subcommand."""
-    html = args.schedule
-    if html is None:
-        if args.ligaid is None:
-            print(
-                "Error: pass --schedule PATH or --ligaid LIGAID for schedule.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        html = str(Path("files") / str(args.ligaid) / "spielplan.html")
-
+    html = _resolve_schedule(args, "schedule")
     games, league_info = parse_schedule(html)
     filtered = filter_schedule(
         games, show_all=args.all, pending=args.pending, team=args.team
@@ -191,7 +185,7 @@ def cmd_predict(args: argparse.Namespace) -> None:
         sp = sp or str(base / "spielplan.html")
 
     # Check if season is finalized
-    finalized, pending_count = is_season_finalized(sp)
+    finalized, _pending_count = is_season_finalized(sp)
     if finalized:
         print(
             "Error: Season is finalized (no pending games). "
@@ -229,32 +223,8 @@ def _blocks(value: int, scale: int) -> str:
     return "█" * max(0, value // scale)
 
 
-def cmd_top(args: argparse.Namespace) -> None:
-    """Handle 'top' subcommand."""
-
-    fp = args.results
-    if fp is None:
-        if args.ligaid is None:
-            print(
-                "Error: pass --results PATH or --ligaid LIGAID for top.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        fp = str(Path("files") / str(args.ligaid) / "ergebnisse.html")
-
-    standings, league_info = calculate_standings(fp)
-    top = standings[: args.n]
-
-    if args.json:
-        _json_out(
-            {
-                **_liga_meta(league_info, args.ligaid),
-                "top": [s.to_dict() for s in top],
-            }
-        )
-        return
-
-    tw = max(4, max(len(s.name) for s in top))
+def _print_top_table(top: list[Standing], tw: int) -> None:
+    """Print the ranked top-teams table."""
     print("\n" + "=" * 70)
     print("  Top Teams — current table")
     print("=" * 70)
@@ -264,11 +234,12 @@ def cmd_top(args: argparse.Namespace) -> None:
     print("-" * len(hdr))
     for i, s in enumerate(top, 1):
         st = s.stats
-        diff = st.diff
-        diff_str = f"+{diff}" if diff > 0 else str(diff)
+        diff_str = f"+{st.diff}" if st.diff > 0 else str(st.diff)
         print(f"{i:>2}  {s.name:<{tw}}  {st.gp:>2}  {st.pts:>3}  {diff_str:>5}")
 
-    # Points bar chart (ASCII)
+
+def _print_points_chart(top: list[Standing], tw: int) -> None:
+    """Print the ASCII points bar chart for the top teams."""
     pts_vals = [s.stats.pts for s in top]
     max_pts = max(pts_vals) if pts_vals else 0
     # Keep chart readable: 1 block per 1–2 points depending on scale.
@@ -276,12 +247,31 @@ def cmd_top(args: argparse.Namespace) -> None:
     print("\nStandings Points (scaled)")
     print("─────────────────────────")
     for s in top:
-        st = s.stats
-        pts = st.pts
+        pts = s.stats.pts
         print(f"{s.name:<{tw}}  {_blocks(pts, scale):<22}  {pts}")
     print(f"(scale: 1 block ≈ {scale} pts)")
 
 
+def cmd_top(args: argparse.Namespace) -> None:
+    """Handle 'top' subcommand."""
+    fp = _resolve_results(args, "top")
+    standings, league_info = calculate_standings(fp)
+    top = standings[: args.n]
+
+    if args.json:
+        _json_out(
+            {
+                **_liga_meta(league_info, args.ligaid),
+                "top": [s.to_dict() for s in top],
+            }
+        )
+        return
+
+    tw = max(4, max(len(s.name) for s in top))
+    _print_top_table(top, tw)
+    _print_points_chart(top, tw)
+
+
 _BASE = "https://www.basketball-bund.net/public"
 _RESULTS_URL = (
     f"{_BASE}/ergebnisse.jsp?print=1"
@@ -393,9 +383,8 @@ def _discover_league_ids() -> list[int]:
         return []
     ids: list[int] = []
     for entry in sorted(root.iterdir()):
-        if entry.is_dir() and entry.name.isdigit():
-            if any(entry.glob("*.html")):
-                ids.append(int(entry.name))
+        if entry.is_dir() and entry.name.isdigit() and any(entry.glob("*.html")):
+            ids.append(int(entry.name))
     return ids
 
 
@@ -423,22 +412,6 @@ def cmd_download(args: argparse.Namespace) -> None:
     _download(args.ligaid)
 
 
-def cmd_skill(args: argparse.Namespace) -> None:
-    """Handle 'skill' subcommand."""
-    if args.list_skills:
-        for name, filename in SKILL_MAP.items():
-            print(f"  {name:12s}  {filename}")
-        return
-    if args.name is None:
-        print("Error: pass a skill name or --list", file=sys.stderr)
-        sys.exit(1)
-    try:
-        print(get_skill_text(args.name))
-    except ValueError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
-
-
 def main() -> None:
     """Entry point for CLI."""
     parser = argparse.ArgumentParser(
@@ -582,28 +555,8 @@ def main() -> None:
     )
     p_dl.set_defaults(func=cmd_download)
 
-    p_sk = subs.add_parser(
-        "skill",
-        help="Print a skill prompt or list available skills",
-    )
-    p_sk.add_argument(
-        "name",
-        nargs="?",
-        default=None,
-        help="Skill name: analysis or prediction",
-    )
-    p_sk.add_argument(
-        "--list",
-        "-l",
-        action="store_true",
-        dest="list_skills",
-        help="List available skill names and descriptions",
-    )
-    p_sk.set_defaults(func=cmd_skill)
-
     args = parser.parse_args()
 
-    # Pre-command download hook
     if args.download and args.command != "download":
         if args.ligaid is None:
             print(