backcaster 0.3.6__tar.gz → 0.4.0__tar.gz

{backcaster-0.3.6/src/backcaster.egg-info → backcaster-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.6
+Version: 0.4.0
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -56,10 +56,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.6:
+To install a specific release, such as 0.4.0:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.6
+python -m pip install --upgrade backcaster==0.4.0
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -234,19 +234,63 @@ backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out
 
 ### CLI table output (`--format cli`, default)
 
-Example shape (columns vary by batting vs pitching):
+Selected columns from a 2025 Mookie Betts projection (actual output includes
+additional counting statistics, reliability, and age):
 
 ```text
-   PA    AB     H   2B   3B    HR    BB    SO   HBP    SF    AVG    OBP    SLG    OPS  Reliability          Name  Year
-610.2 545.1 162.4 34.1  2.8  32.6  67.9 119.3   5.6   4.7  0.298  0.384  0.531  0.915        0.89  Mookie Betts  2026
+ PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
+bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869
 ```
 
+### Number formatting and baseball innings
+
+Terminal, CSV, and HTML outputs use the same display rules:
+
+- Counting statistics are rounded to the nearest whole number, with halves rounded
+  up. Age and year are displayed as whole numbers too.
+- AVG, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
+- ERA and WHIP always show two decimal places, such as `3.46` and `1.23`.
+- IP is rounded to the nearest out and displayed in baseball notation:
+  `161.0` is 161 innings, `161.1` is 161 innings plus one out, and `161.2` is
+  161 innings plus two outs. Three outs carry into the next whole inning.
+
+Calculations and Python projection DataFrames retain full precision. Rates are
+computed from unrounded totals, then formatted; they are not recalculated from
+rounded displayed counts. Independently rounded totals may therefore not add up
+exactly. Reliability formatting is unchanged.
+
+**CSV IP uses baseball notation too.** Convert `161.1` to `161 + 1/3` before doing
+arithmetic; treating it as 161.1 decimal innings gives incorrect results. Internally,
+Backcaster uses decimal innings (`IPouts / 3`), so ERA and WHIP calculations use
+true innings rather than the displayed notation.
+
 ### CSV output (`--format csv`)
 A single-row CSV for `player`; multi-row CSV for `team`, `batch`, `hitters`, and `pitchers`.
 Both populations include `PlayerID` for matching records across files.
 
 ### HTML output (`--format html`)
-A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
+A standalone report with embedded CSS and JavaScript, ready to open in a browser
+or share as one file. No server, CDN, fonts, or internet connection are required.
+
+```powershell
+backcaster hitters --year 2025 --format html --out hitters_2025.html
+backcaster pitchers --year 2025 --format html --out pitchers_2025.html
+```
+
+The first four columns are **Name, Year, Player ID, Age**, followed by counting
+statistics and batting/pitching rates in a consistent order. The report includes:
+
+- A player-count, projection-year, and projection-type summary.
+- Search across player names, IDs, and statistics.
+- Sortable column headings, with numeric sorting for statistics.
+- A sticky name column/header and horizontal scrolling on narrow screens.
+- A reset control and print layout for browser printing or saving as PDF.
+
+Your display precision rules apply, including baseball innings notation. Rates
+retain their trailing decimal places and OPS values above 1.000 display normally.
+Search filters the visible rows; printing respects that current view. Without
+JavaScript, the complete table is still readable. See
+[HTML report customization](docs/HTML_REPORTS.md) for theme and column constants.
 
 ---
 

{backcaster-0.3.6 → backcaster-0.4.0}/README.md

@@ -25,10 +25,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.6:
+To install a specific release, such as 0.4.0:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.6
+python -m pip install --upgrade backcaster==0.4.0
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -203,19 +203,63 @@ backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out
 
 ### CLI table output (`--format cli`, default)
 
-Example shape (columns vary by batting vs pitching):
+Selected columns from a 2025 Mookie Betts projection (actual output includes
+additional counting statistics, reliability, and age):
 
 ```text
-   PA    AB     H   2B   3B    HR    BB    SO   HBP    SF    AVG    OBP    SLG    OPS  Reliability          Name  Year
-610.2 545.1 162.4 34.1  2.8  32.6  67.9 119.3   5.6   4.7  0.298  0.384  0.531  0.915        0.89  Mookie Betts  2026
+ PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
+bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869
 ```
 
+### Number formatting and baseball innings
+
+Terminal, CSV, and HTML outputs use the same display rules:
+
+- Counting statistics are rounded to the nearest whole number, with halves rounded
+  up. Age and year are displayed as whole numbers too.
+- AVG, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
+- ERA and WHIP always show two decimal places, such as `3.46` and `1.23`.
+- IP is rounded to the nearest out and displayed in baseball notation:
+  `161.0` is 161 innings, `161.1` is 161 innings plus one out, and `161.2` is
+  161 innings plus two outs. Three outs carry into the next whole inning.
+
+Calculations and Python projection DataFrames retain full precision. Rates are
+computed from unrounded totals, then formatted; they are not recalculated from
+rounded displayed counts. Independently rounded totals may therefore not add up
+exactly. Reliability formatting is unchanged.
+
+**CSV IP uses baseball notation too.** Convert `161.1` to `161 + 1/3` before doing
+arithmetic; treating it as 161.1 decimal innings gives incorrect results. Internally,
+Backcaster uses decimal innings (`IPouts / 3`), so ERA and WHIP calculations use
+true innings rather than the displayed notation.
+
 ### CSV output (`--format csv`)
 A single-row CSV for `player`; multi-row CSV for `team`, `batch`, `hitters`, and `pitchers`.
 Both populations include `PlayerID` for matching records across files.
 
 ### HTML output (`--format html`)
-A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
+A standalone report with embedded CSS and JavaScript, ready to open in a browser
+or share as one file. No server, CDN, fonts, or internet connection are required.
+
+```powershell
+backcaster hitters --year 2025 --format html --out hitters_2025.html
+backcaster pitchers --year 2025 --format html --out pitchers_2025.html
+```
+
+The first four columns are **Name, Year, Player ID, Age**, followed by counting
+statistics and batting/pitching rates in a consistent order. The report includes:
+
+- A player-count, projection-year, and projection-type summary.
+- Search across player names, IDs, and statistics.
+- Sortable column headings, with numeric sorting for statistics.
+- A sticky name column/header and horizontal scrolling on narrow screens.
+- A reset control and print layout for browser printing or saving as PDF.
+
+Your display precision rules apply, including baseball innings notation. Rates
+retain their trailing decimal places and OPS values above 1.000 display normally.
+Search filters the visible rows; printing respects that current view. Without
+JavaScript, the complete table is still readable. See
+[HTML report customization](docs/HTML_REPORTS.md) for theme and column constants.
 
 ---
 

{backcaster-0.3.6 → backcaster-0.4.0}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.3.6"
+__version__ = "0.4.0"

backcaster-0.4.0/src/backcaster/html_report.py

@@ -0,0 +1,205 @@
+"""Self-contained HTML projection reports, with no network assets."""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+import pandas as pd
+
+IDENTITY_COLUMNS = ("Name", "Year", "PlayerID", "Age")
+BATTING_COLUMNS = (
+    "PA",
+    "AB",
+    "H",
+    "2B",
+    "3B",
+    "HR",
+    "R",
+    "RBI",
+    "BB",
+    "SO",
+    "HBP",
+    "SF",
+    "SH",
+    "SB",
+    "CS",
+    "AVG",
+    "OBP",
+    "SLG",
+    "OPS",
+    "Reliability",
+)
+PITCHING_COLUMNS = ("IP", "ER", "H", "HR", "BB", "SO", "BF", "ERA", "WHIP", "Reliability")
+COLUMN_LABELS = {"PlayerID": "Player ID"}
+COLUMN_HELP = {
+    "IP": "Innings in baseball notation: .1 = one out, .2 = two outs",
+    "Reliability": "Observed-evidence weight; not a probability of prediction accuracy",
+    "Age": "Projection year minus birth year",
+}
+
+REPORT_CSS = r"""
+:root { --brand:#153e3b; --brand-dark:#102e2c; --accent:#78bd82; --canvas:#f3f6f5; --surface:#fff; --ink:#183634; --muted:#617571; --line:#dce5e2; --stripe:#f8faf9; --radius:12px; }
+* { box-sizing:border-box; }
+body { margin:0; background:var(--canvas); color:var(--ink); font:14px/1.5 'Segoe UI',system-ui,sans-serif; }
+.topbar { background:var(--brand-dark); color:white; padding:18px 32px; display:flex; align-items:center; justify-content:space-between; gap:20px; }
+.brand { font-size:19px; font-weight:700; letter-spacing:-.4px; }
+.brand-mark { display:inline-block; width:12px; height:12px; background:var(--accent); border-radius:3px; transform:rotate(-15deg); margin-right:11px; }
+.topbar small { color:#bcd4cb; letter-spacing:.08em; font-size:11px; }
+main { max-width:1720px; margin:auto; padding:32px; }
+.eyebrow { color:var(--muted); font-weight:700; letter-spacing:.13em; text-transform:uppercase; font-size:11px; margin:0 0 7px; }
+h1 { font-size:30px; line-height:1.2; margin:0 0 10px; font-weight:650; letter-spacing:-.8px; }
+.subtitle { color:var(--muted); margin:0; }
+.intro { margin-bottom:24px; }
+.cards { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:16px; margin-bottom:26px; }
+.card { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:18px 22px; border-top:3px solid var(--accent); }
+.card-label { color:var(--muted); font-size:12px; margin-bottom:4px; }
+.card-value { font-size:25px; font-weight:650; letter-spacing:-.5px; overflow-wrap:anywhere; }
+.card-note { color:var(--muted); font-size:11px; margin-top:3px; }
+.panel { border:1px solid var(--line); border-radius:var(--radius); background:white; overflow:hidden; box-shadow:0 3px 14px #18363405; }
+.toolbar { display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:14px; padding:20px; border-bottom:1px solid var(--line); }
+h2 { margin:0; font-size:16px; font-weight:650; }
+.table-hint { margin:3px 0 0; color:var(--muted); font-size:12px; }
+.controls { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
+label { font-size:12px; font-weight:600; }
+input { border:1px solid #baccc6; border-radius:7px; padding:9px 11px; font:inherit; width:245px; background:#fff; }
+button { cursor:pointer; font:inherit; }
+.action { border:1px solid #baccc6; border-radius:7px; padding:9px 13px; background:white; color:var(--brand); font-weight:600; font-size:12px; }
+.action.primary { background:var(--brand); border-color:var(--brand); color:white; }
+button:hover { filter:brightness(.95); }
+input:focus,button:focus-visible,.table-scroll:focus-visible { outline:3px solid #78bd82; outline-offset:2px; }
+.table-scroll { overflow:auto; max-height:70vh; }
+table { border-collapse:separate; border-spacing:0; min-width:100%; width:max-content; font-size:12px; font-variant-numeric:tabular-nums; }
+caption { text-align:left; padding:0; }
+.sr-only { position:absolute; width:1px; height:1px; padding:0; margin:-1px; overflow:hidden; clip:rect(0,0,0,0); white-space:nowrap; border:0; }
+th,td { padding:11px 13px; white-space:nowrap; text-align:right; border-bottom:1px solid #eaf0ed; }
+th { position:sticky; top:0; background:#eaf0ed; color:#49605b; z-index:2; font-size:11px; letter-spacing:.02em; }
+th button { background:none; color:inherit; border:0; padding:0; font-weight:700; white-space:nowrap; }
+th button::after { content:' ↕'; opacity:.4; font-weight:400; }
+th[aria-sort=ascending] button::after { content:' ↑'; opacity:1; }
+th[aria-sort=descending] button::after { content:' ↓'; opacity:1; }
+td:first-child,th:first-child { text-align:left; position:sticky; left:0; }
+td:first-child { background:inherit; font-weight:600; z-index:1; min-width:175px; }
+th:first-child { z-index:3; }
+td:nth-child(3),th:nth-child(3) { text-align:left; }
+td:nth-child(3) { font-family:ui-monospace,Consolas,monospace; font-size:11px; color:var(--muted); }
+tbody tr { background:white; }
+tbody tr:nth-child(even) { background:var(--stripe); }
+tbody tr:hover { background:#eaf5ed; }
+.rate { color:var(--brand); font-weight:650; background-color:#78bd8209; }
+.table-footer { padding:12px 20px; font-size:12px; color:var(--muted); display:flex; justify-content:space-between; gap:16px; border-top:1px solid var(--line); }
+.report-notes { display:grid; grid-template-columns:1fr 1fr; gap:20px; margin-top:22px; color:var(--muted); font-size:12px; }
+.report-notes strong { display:block; color:var(--ink); margin-bottom:4px; font-weight:600; }
+footer { display:flex; justify-content:space-between; flex-wrap:wrap; gap:8px; margin-top:28px; padding-top:16px; border-top:1px solid var(--line); font-size:11px; color:var(--muted); }
+.empty { text-align:center; padding:28px; color:var(--muted); }
+[hidden] { display:none!important; }
+@media(max-width:700px) { main { padding:20px 12px; } .topbar { padding:16px; } .cards { grid-template-columns:1fr; gap:10px; } .card { padding:12px 16px; } .card-value { font-size:21px; } h1 { font-size:25px; } .report-notes { grid-template-columns:1fr; } input { width:190px; } }
+@page { size:landscape; margin:12mm; }
+@media print { body { background:white; font-size:10px; } .topbar { background:white; color:var(--ink); padding:0 0 12px; border-bottom:2px solid var(--brand); } .topbar small { color:var(--muted); } main { padding:18px 0; max-width:none; } .controls,.table-hint { display:none; } .cards { gap:10px; margin-bottom:14px; } .card { padding:10px; } .panel { box-shadow:none; overflow:visible; } .table-scroll { overflow:visible; max-height:none; } table { width:100%; min-width:0; font-size:8px; } th,td { padding:5px 4px; position:static!important; } td:first-child { min-width:0; } thead { display:table-header-group; } tr { break-inside:avoid; } .report-notes { font-size:9px; } }
+"""
+
+REPORT_JS = r"""
+(() => {
+ const table=document.getElementById('projections');
+ const body=table.tBodies[0];
+ const rows=Array.from(body.querySelectorAll('tr[data-player]'));
+ const search=document.getElementById('search');
+ const status=document.getElementById('visible-count');
+ const empty=document.getElementById('no-matches');
+ let active=-1, ascending=true;
+ function filter() {
+   const query=search.value.trim().toLocaleLowerCase();
+   let visible=0;
+   rows.forEach(row=>{row.hidden=!row.textContent.toLocaleLowerCase().includes(query); if(!row.hidden)visible++;});
+   status.textContent=`Showing ${visible} of ${rows.length} players`;
+   empty.hidden=visible!==0;
+ }
+ table.querySelectorAll('thead button').forEach((button,index)=>{
+   button.addEventListener('click',()=>{
+     ascending=active===index?!ascending:true; active=index;
+     const sorted=[...rows].sort((a,b)=>{
+       const x=a.cells[index].textContent.trim(), y=b.cells[index].textContent.trim();
+       const numeric=x!==''&&y!==''&&Number.isFinite(Number(x))&&Number.isFinite(Number(y));
+       return (numeric?Number(x)-Number(y):x.localeCompare(y,undefined,{numeric:true}))*(ascending?1:-1);
+     });
+     table.querySelectorAll('th').forEach(th=>th.setAttribute('aria-sort','none'));
+     button.parentElement.setAttribute('aria-sort',ascending?'ascending':'descending');
+     sorted.forEach(row=>body.appendChild(row)); filter();
+   });
+ });
+ search.addEventListener('input',filter);
+ document.getElementById('reset').addEventListener('click',()=>{
+   search.value='';active=-1;ascending=true;rows.forEach(row=>body.appendChild(row));
+   table.querySelectorAll('th').forEach(th=>th.setAttribute('aria-sort','none'));filter();
+ });
+ document.getElementById('print').addEventListener('click',()=>window.print());
+ filter();
+})();
+"""
+
+
+def _cell(value: Any) -> str:
+    if pd.isna(value):
+        return ""
+    if isinstance(value, float):
+        return f"{value:.6f}"
+    return str(value)
+
+
+def _table(frame: pd.DataFrame, columns: list[str]) -> str:
+    headers = []
+    for column in columns:
+        label = escape(COLUMN_LABELS.get(column, column))
+        title = escape(
+            COLUMN_HELP.get(column, f"Sort by {COLUMN_LABELS.get(column, column)}"), quote=True
+        )
+        headers.append(
+            f'<th scope="col" aria-sort="none"><button type="button" title="{title}">{label}</button></th>'
+        )
+    rows = []
+    for row in frame.itertuples(index=False, name=None):
+        cells = []
+        for column, value in zip(columns, row):
+            style = ' class="rate"' if column in {"AVG", "OBP", "SLG", "OPS", "ERA", "WHIP"} else ""
+            cells.append(f"<td{style}>{escape(_cell(value))}</td>")
+        rows.append('<tr data-player="true">' + "".join(cells) + "</tr>")
+    return (
+        '<table id="projections"><caption class="sr-only">Player projection statistics</caption><thead><tr>'
+        + "".join(headers)
+        + "</tr></thead><tbody>"
+        + "".join(rows)
+        + "</tbody></table>"
+    )
+
+
+def render_report(display: pd.DataFrame) -> str:
+    pitching = "IP" in display.columns
+    kind = "Pitching" if pitching else "Batting"
+    stat_order = PITCHING_COLUMNS if pitching else BATTING_COLUMNS
+    columns = [*IDENTITY_COLUMNS, *[c for c in stat_order if c in display]]
+    columns += [c for c in display.columns if c not in columns]
+    frame = display.reindex(columns=columns, fill_value="")
+    years = ", ".join(sorted({_cell(v) for v in frame["Year"] if _cell(v)})) or "—"
+    title = f"{kind} projections"
+    count = len(frame)
+    notes = (
+        "IP uses baseball notation: .1 is one out; .2 is two outs. ERA and WHIP use true innings before rounding."
+        if pitching
+        else "AVG, OBP, SLG, and OPS use three decimal places. Counting statistics are rounded to whole numbers."
+    )
+    return f'''<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Backcaster · {title} · {escape(years)}</title><style>{REPORT_CSS}</style></head>
+<body><header class="topbar"><div class="brand"><span class="brand-mark" aria-hidden="true"></span>Backcaster</div><small>PLAYER PROJECTION REPORT</small></header>
+<main><section class="intro"><p class="eyebrow">Season outlook</p><h1>{title}</h1><p class="subtitle">A clear view of projected player performance.</p></section>
+<section class="cards" aria-label="Report summary"><div class="card"><div class="card-label">Players in report</div><div class="card-value">{count:,}</div><div class="card-note">One row per projected player</div></div>
+<div class="card"><div class="card-label">Projection year</div><div class="card-value">{escape(years)}</div><div class="card-note">The season being projected</div></div>
+<div class="card"><div class="card-label">Projection type</div><div class="card-value">{kind}</div><div class="card-note">Marcel-style statistical baseline</div></div></section>
+<section class="panel" aria-label="Player projections"><div class="toolbar"><div><h2>Player projections</h2><p class="table-hint">Select a column heading to sort.</p></div>
+<div class="controls"><label for="search">Find players</label><input id="search" type="search" placeholder="Search name, ID, or statistic…" autocomplete="off"><button type="button" class="action" id="reset">Reset</button><button type="button" class="action primary" id="print">Print report</button></div></div>
+<div class="table-scroll" tabindex="0" aria-label="Scrollable projection statistics">{_table(frame, columns)}</div>
+<p class="empty" id="no-matches"{"" if count == 0 else " hidden"}>No players to display.</p>
+<div class="table-footer"><span id="visible-count" role="status" aria-live="polite">Showing {count} of {count} players</span><span>Rounded for presentation</span></div></section>
+<section class="report-notes" aria-label="Reading this report"><div><strong>Reading the numbers</strong>{notes}</div><div><strong>Interpreting projections</strong>Reliability is an observed-evidence weight, not an accuracy probability. Historical eligibility does not represent a current roster.</div></section>
+<footer><span>Backcaster · Marcel-style projections</span><span>Methodology: Tom Tango · Reference inspiration: Ben Dilday’s marcelR</span></footer></main>
+<script>{REPORT_JS}</script></body></html>'''

backcaster-0.4.0/src/backcaster/outputs.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from backcaster.html_report import render_report
+
+COUNT_COLUMNS = {
+    "PA",
+    "AB",
+    "H",
+    "2B",
+    "3B",
+    "HR",
+    "BB",
+    "SO",
+    "HBP",
+    "SF",
+    "SH",
+    "ER",
+    "BF",
+    "R",
+    "RBI",
+    "SB",
+    "CS",
+    "IBB",
+    "GDP",
+    "GIDP",
+    "W",
+    "L",
+    "SV",
+    "G",
+    "GS",
+    "CG",
+    "SHO",
+    "WP",
+    "BK",
+    "Age",
+    "Year",
+}
+RATE_PLACES = {"AVG": 3, "OBP": 3, "SLG": 3, "OPS": 3, "ERA": 2, "WHIP": 2}
+
+
+def _format_number(value: Any, places: int) -> str:
+    if pd.isna(value):
+        return ""
+    number = Decimal(str(value)).quantize(Decimal(1).scaleb(-places), rounding=ROUND_HALF_UP)
+    return f"{number:.{places}f}"
+
+
+def _format_innings(value: Any) -> str:
+    if pd.isna(value):
+        return ""
+    innings = Decimal(str(value))
+    if not innings.is_finite() or innings < 0:
+        raise ValueError("IP must be a finite, nonnegative number of decimal innings.")
+    outs = int((innings * 3).to_integral_value(rounding=ROUND_HALF_UP))
+    whole, remainder = divmod(outs, 3)
+    return f"{whole}.{remainder}"
+
+
+def _display_frame(df: pd.DataFrame) -> pd.DataFrame:
+    """Format a copy at the output boundary; preserve full-precision calculations."""
+    display = df.copy()
+    for column in display.columns:
+        if column == "IP":
+            display[column] = display[column].map(_format_innings)
+        elif column in COUNT_COLUMNS or column in RATE_PLACES:
+            places = RATE_PLACES.get(column, 0)
+            display[column] = display[column].map(lambda value: _format_number(value, places))
+    return display
+
+
+def to_cli_table(df: pd.DataFrame) -> str:
+    return _display_frame(df).to_string(index=False)
+
+
+def to_csv(df: pd.DataFrame, out_path: str | Path) -> Path:
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    _display_frame(df).to_csv(out, index=False)
+    return out
+
+
+def to_html(df: pd.DataFrame, out_path: str | Path) -> Path:
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    html = render_report(_display_frame(df))
+    out.write_text(html, encoding="utf-8")
+    return out

{backcaster-0.3.6 → backcaster-0.4.0/src/backcaster.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.6
+Version: 0.4.0
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -56,10 +56,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.3.6:
+To install a specific release, such as 0.4.0:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.3.6
+python -m pip install --upgrade backcaster==0.4.0
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -234,19 +234,63 @@ backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out
 
 ### CLI table output (`--format cli`, default)
 
-Example shape (columns vary by batting vs pitching):
+Selected columns from a 2025 Mookie Betts projection (actual output includes
+additional counting statistics, reliability, and age):
 
 ```text
-   PA    AB     H   2B   3B    HR    BB    SO   HBP    SF    AVG    OBP    SLG    OPS  Reliability          Name  Year
-610.2 545.1 162.4 34.1  2.8  32.6  67.9 119.3   5.6   4.7  0.298  0.384  0.531  0.915        0.89  Mookie Betts  2026
+ PlayerID  PA  AB   H HR   AVG   OBP   SLG   OPS
+bettsmo01 527 461 128 24 0.278 0.362 0.507 0.869
 ```
 
+### Number formatting and baseball innings
+
+Terminal, CSV, and HTML outputs use the same display rules:
+
+- Counting statistics are rounded to the nearest whole number, with halves rounded
+  up. Age and year are displayed as whole numbers too.
+- AVG, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
+- ERA and WHIP always show two decimal places, such as `3.46` and `1.23`.
+- IP is rounded to the nearest out and displayed in baseball notation:
+  `161.0` is 161 innings, `161.1` is 161 innings plus one out, and `161.2` is
+  161 innings plus two outs. Three outs carry into the next whole inning.
+
+Calculations and Python projection DataFrames retain full precision. Rates are
+computed from unrounded totals, then formatted; they are not recalculated from
+rounded displayed counts. Independently rounded totals may therefore not add up
+exactly. Reliability formatting is unchanged.
+
+**CSV IP uses baseball notation too.** Convert `161.1` to `161 + 1/3` before doing
+arithmetic; treating it as 161.1 decimal innings gives incorrect results. Internally,
+Backcaster uses decimal innings (`IPouts / 3`), so ERA and WHIP calculations use
+true innings rather than the displayed notation.
+
 ### CSV output (`--format csv`)
 A single-row CSV for `player`; multi-row CSV for `team`, `batch`, `hitters`, and `pitchers`.
 Both populations include `PlayerID` for matching records across files.
 
 ### HTML output (`--format html`)
-A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
+A standalone report with embedded CSS and JavaScript, ready to open in a browser
+or share as one file. No server, CDN, fonts, or internet connection are required.
+
+```powershell
+backcaster hitters --year 2025 --format html --out hitters_2025.html
+backcaster pitchers --year 2025 --format html --out pitchers_2025.html
+```
+
+The first four columns are **Name, Year, Player ID, Age**, followed by counting
+statistics and batting/pitching rates in a consistent order. The report includes:
+
+- A player-count, projection-year, and projection-type summary.
+- Search across player names, IDs, and statistics.
+- Sortable column headings, with numeric sorting for statistics.
+- A sticky name column/header and horizontal scrolling on narrow screens.
+- A reset control and print layout for browser printing or saving as PDF.
+
+Your display precision rules apply, including baseball innings notation. Rates
+retain their trailing decimal places and OPS values above 1.000 display normally.
+Search filters the visible rows; printing respects that current view. Without
+JavaScript, the complete table is still readable. See
+[HTML report customization](docs/HTML_REPORTS.md) for theme and column constants.
 
 ---
 

{backcaster-0.3.6 → backcaster-0.4.0}/src/backcaster.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/backcaster/__init__.py
 src/backcaster/batters.py
 src/backcaster/cli.py
 src/backcaster/data.py
+src/backcaster/html_report.py
 src/backcaster/lahman.py
 src/backcaster/marcel.py
 src/backcaster/normalize.py
@@ -19,6 +20,7 @@ src/backcaster.egg-info/requires.txt
 src/backcaster.egg-info/top_level.txt
 tests/test_batters.py
 tests/test_cli.py
+tests/test_html_report.py
 tests/test_lahman.py
 tests/test_marcel_math.py
 tests/test_normalize.py

backcaster-0.4.0/tests/test_html_report.py

@@ -0,0 +1,160 @@
+from html.parser import HTMLParser
+from pathlib import Path
+
+import pandas as pd
+
+from backcaster.outputs import to_html
+
+
+class TableParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.headers = []
+        self.cells = []
+        self.tags = []
+        self.header = False
+        self.cell = False
+
+    def handle_starttag(self, tag, attrs):
+        self.tags.append(tag)
+        if tag == "th":
+            self.header = True
+            self.headers.append("")
+        if tag == "td":
+            self.cell = True
+            self.cells.append("")
+
+    def handle_endtag(self, tag):
+        if tag == "th":
+            self.header = False
+        if tag == "td":
+            self.cell = False
+
+    def handle_data(self, data):
+        if self.header:
+            self.headers[-1] += data
+        if self.cell:
+            self.cells[-1] += data
+
+
+def test_identity_first_and_batting_order(tmp_path: Path) -> None:
+    frame = pd.DataFrame(
+        [
+            dict(
+                HR=45.6,
+                OPS=1.048,
+                Age=33,
+                PA=598.2,
+                PlayerID="judgeaa01",
+                Year=2025,
+                Name="Aaron Judge",
+                AVG=0.293,
+                Reliability=0.86,
+            )
+        ]
+    )
+    original = frame.copy(deep=True)
+    text = to_html(frame, tmp_path / "hitters.html").read_text()
+    parser = TableParser()
+    parser.feed(text)
+    assert parser.headers == [
+        "Name",
+        "Year",
+        "Player ID",
+        "Age",
+        "PA",
+        "HR",
+        "AVG",
+        "OPS",
+        "Reliability",
+    ]
+    assert parser.cells == [
+        "Aaron Judge",
+        "2025",
+        "judgeaa01",
+        "33",
+        "598",
+        "46",
+        "0.293",
+        "1.048",
+        "0.860000",
+    ]
+    assert "<!doctype html>" in text
+    assert "<style>" in text
+    assert "Batting projections" in text
+    assert "Showing 1 of 1 players" in text
+    assert "https://" not in text
+    pd.testing.assert_frame_equal(frame, original)
+
+
+def test_pitching_order_precision_and_notes(tmp_path: Path) -> None:
+    frame = pd.DataFrame(
+        [
+            dict(
+                WHIP=1.234,
+                ERA=3.456,
+                Name="Example",
+                Age=30,
+                Year=2025,
+                PlayerID="test01",
+                BF=700.4,
+                SO=200.5,
+                BB=50.3,
+                HR=20.3,
+                H=130.2,
+                ER=60.7,
+                IP=161 + 1 / 3,
+            )
+        ]
+    )
+    text = to_html(frame, tmp_path / "pitchers.html").read_text()
+    parser = TableParser()
+    parser.feed(text)
+    assert parser.headers == [
+        "Name",
+        "Year",
+        "Player ID",
+        "Age",
+        "IP",
+        "ER",
+        "H",
+        "HR",
+        "BB",
+        "SO",
+        "BF",
+        "ERA",
+        "WHIP",
+    ]
+    assert parser.cells[4:] == ["161.1", "61", "130", "20", "50", "201", "700", "3.46", "1.23"]
+    assert "Pitching projections" in text
+    assert ".1 is one out" in text
+
+
+def test_missing_metadata_unknown_columns_and_empty_report(tmp_path: Path) -> None:
+    frame = pd.DataFrame([{"Name": None, "PA": 100, "Other": 1.23456789}])
+    parser = TableParser()
+    parser.feed(to_html(frame, tmp_path / "partial.html").read_text())
+    assert parser.headers[:4] == ["Name", "Year", "Player ID", "Age"]
+    assert parser.cells[:4] == ["", "", "", ""]
+    assert parser.cells[-1] == "1.234568"
+    text = to_html(pd.DataFrame(), tmp_path / "empty.html").read_text()
+    assert "No players to display." in text
+    assert "Showing 0 of 0 players" in text
+
+
+def test_html_escapes_values_and_column_names(tmp_path: Path) -> None:
+    name = '<script>alert("bad")</script>'
+    column = '<img src=x onerror="bad()">'
+    frame = pd.DataFrame([{"Name": name, "Year": "<b>2025</b>", column: "<svg/onload=bad()>"}])
+    # Year is numeric in projections; use a valid year and inject through a generic column.
+    frame["Year"] = 2025
+    text = to_html(frame, tmp_path / "escaped.html").read_text()
+    parser = TableParser()
+    parser.feed(text)
+    assert parser.cells[0] == name
+    assert parser.headers[-1] == column
+    assert parser.cells[-1] == "<svg/onload=bad()>"
+    assert "img" not in parser.tags
+    assert "svg" not in parser.tags
+    assert parser.tags.count("script") == 1  # Only the trusted report script.
+    assert "<script>alert(" not in text

backcaster-0.4.0/tests/test_outputs.py

@@ -0,0 +1,142 @@
+import re
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+from backcaster.outputs import _display_frame, _format_innings, to_cli_table, to_csv, to_html
+
+
+def test_csv_output_creation(tmp_path: Path) -> None:
+    df = pd.DataFrame([{"Name": "A", "PA": 100}])
+    out = tmp_path / "out.csv"
+    to_csv(df, out)
+    assert out.exists()
+    content = out.read_text(encoding="utf-8")
+    assert "Name,PA" in content
+
+
+def test_html_output_creation(tmp_path: Path) -> None:
+    df = pd.DataFrame([{"Name": "A", "PA": 100}])
+    out = tmp_path / "out.html"
+    to_html(df, out)
+    assert out.exists()
+    content = out.read_text(encoding="utf-8")
+    assert "<table" in content
+    assert "A" in content
+
+
+def test_cli_table_output() -> None:
+    df = pd.DataFrame([{"Name": "A", "PA": 100}])
+    assert to_cli_table(df) == df.to_string(index=False)
+
+
+@pytest.mark.parametrize(
+    "innings, expected",
+    [
+        (161, "161.0"),
+        (161 + 1 / 3, "161.1"),
+        (161 + 2 / 3, "161.2"),
+        (161.999999, "162.0"),
+        (161.5, "161.2"),
+        (0, "0.0"),
+        (1 / 3, "0.1"),
+        (float("nan"), ""),
+    ],
+)
+def test_baseball_innings_notation(innings: float, expected: str) -> None:
+    assert _format_innings(innings) == expected
+
+
+@pytest.mark.parametrize("innings", [-1, float("inf")])
+def test_invalid_display_innings(innings: float) -> None:
+    with pytest.raises(ValueError, match="finite, nonnegative"):
+        _format_innings(innings)
+
+
+def test_display_precision_and_no_mutation() -> None:
+    frame = pd.DataFrame(
+        [
+            dict(
+                Name="Judge",
+                PlayerID="judgeaa01",
+                PA=598.5,
+                HR=45.6,
+                H=143.2,
+                AVG=0.293,
+                OBP=0.415,
+                SLG=0.633,
+                OPS=1.048,
+                ER=60.5,
+                BB=51.1,
+                SO=199.8,
+                BF=700.4,
+                IP=161 + 1 / 3,
+                ERA=3.456,
+                WHIP=1.234,
+                Age=33.0,
+                Year=2025,
+                Other=1.234567,
+            )
+        ]
+    )
+    original = frame.copy(deep=True)
+    result = _display_frame(frame).iloc[0]
+    for column, expected in {
+        "PA": "599",
+        "HR": "46",
+        "H": "143",
+        "AVG": "0.293",
+        "OBP": "0.415",
+        "SLG": "0.633",
+        "OPS": "1.048",
+        "ER": "61",
+        "BB": "51",
+        "SO": "200",
+        "BF": "700",
+        "IP": "161.1",
+        "ERA": "3.46",
+        "WHIP": "1.23",
+        "Age": "33",
+        "Year": "2025",
+    }.items():
+        assert result[column] == expected
+    assert result.Other == 1.234567
+    pd.testing.assert_frame_equal(frame, original)
+
+
+def test_missing_numbers_and_fixed_trailing_zeros() -> None:
+    result = _display_frame(
+        pd.DataFrame(
+            [{"PA": float("nan"), "AVG": 0.3, "OBP": 0.0, "OPS": 1.0, "ERA": 4.0, "WHIP": 1.1}]
+        )
+    ).iloc[0]
+    assert result.PA == ""
+    assert result.AVG == "0.300"
+    assert result.OBP == "0.000"
+    assert result.OPS == "1.000"
+    assert result.ERA == "4.00"
+    assert result.WHIP == "1.10"
+
+
+@pytest.mark.parametrize("output", ["cli", "csv", "html"])
+def test_all_outputs_share_display_format(tmp_path: Path, output: str) -> None:
+    frame = pd.DataFrame(
+        [dict(Name="Example", HR=24.6, OPS=1.048, IP=161 + 2 / 3, ERA=3.456, WHIP=1.234)]
+    )
+    if output == "cli":
+        text = to_cli_table(frame)
+        for value in ["25", "1.048", "161.2", "3.46", "1.23"]:
+            assert value in text
+    elif output == "csv":
+        path = to_csv(frame, tmp_path / "out.csv")
+        row = pd.read_csv(path, dtype=str).iloc[0]
+        assert row.HR == "25"
+        assert row.OPS == "1.048"
+        assert row.IP == "161.2"
+        assert row.ERA == "3.46"
+        assert row.WHIP == "1.23"
+    else:
+        text = to_html(frame, tmp_path / "out.html").read_text()
+        for value in ["25", "1.048", "161.2", "3.46", "1.23"]:
+            assert re.search(r"<td(?: [^>]*)?>" + re.escape(value) + r"</td>", text)

backcaster-0.3.6/src/backcaster/outputs.py

@@ -1,24 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import pandas as pd
-
-
-def to_cli_table(df: pd.DataFrame) -> str:
-    return df.to_string(index=False)
-
-
-def to_csv(df: pd.DataFrame, out_path: str | Path) -> Path:
-    out = Path(out_path)
-    out.parent.mkdir(parents=True, exist_ok=True)
-    df.to_csv(out, index=False)
-    return out
-
-
-def to_html(df: pd.DataFrame, out_path: str | Path) -> Path:
-    out = Path(out_path)
-    out.parent.mkdir(parents=True, exist_ok=True)
-    html = df.to_html(index=False, border=0)
-    out.write_text(html, encoding="utf-8")
-    return out

backcaster-0.3.6/tests/test_outputs.py

@@ -1,29 +0,0 @@
-from pathlib import Path
-
-import pandas as pd
-
-from backcaster.outputs import to_cli_table, to_csv, to_html
-
-
-def test_csv_output_creation(tmp_path: Path) -> None:
-    df = pd.DataFrame([{"Name": "A", "PA": 100}])
-    out = tmp_path / "out.csv"
-    to_csv(df, out)
-    assert out.exists()
-    content = out.read_text(encoding="utf-8")
-    assert "Name,PA" in content
-
-
-def test_html_output_creation(tmp_path: Path) -> None:
-    df = pd.DataFrame([{"Name": "A", "PA": 100}])
-    out = tmp_path / "out.html"
-    to_html(df, out)
-    assert out.exists()
-    content = out.read_text(encoding="utf-8")
-    assert "<table" in content
-    assert "A" in content
-
-
-def test_cli_table_output() -> None:
-    df = pd.DataFrame([{"Name": "A", "PA": 100}])
-    assert to_cli_table(df) == df.to_string(index=False)