backcaster 0.3.0__tar.gz → 0.3.2__tar.gz

{backcaster-0.3.0/src/backcaster.egg-info → backcaster-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.0
+Version: 0.3.2
 Summary: Marcel-style MLB projection CLI built on pybaseball
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -46,6 +46,27 @@ It supports:
 - Python **3.13+**
 - Internet access for first-time stat fetches (data is cached locally afterward)
 
+### Update an installed package
+
+Upgrade to the latest release available on PyPI:
+
+```powershell
+python -m pip install --upgrade backcaster
+```
+
+To install a specific release, such as 0.3.2:
+
+```powershell
+python -m pip install --upgrade backcaster==0.3.2
+```
+
+Run the command using the same Python environment where you run Backcaster.
+If you use a virtual environment, activate it first. Check the installed version with:
+
+```powershell
+python -m pip show backcaster
+```
+
 ### Install from source (recommended for contributors)
 
 ```bash
@@ -93,6 +114,51 @@ backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <battin
 backcaster player --name "Mookie Betts" --year 2026 --kind batting
 ```
 
+### Offline projections with Lahman CSVs
+
+Extract your Lahman CSV distribution into a local directory. Pass `--data-dir`
+to use it without any network requests, player-register downloads, or FanGraphs
+cache reads. The directory must contain `People.csv`, `Teams.csv`, and
+`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+without regard to case. The database is not bundled with Backcaster.
+
+See [Lahman database notes](docs/LAHMAN.md) for the supplied 1871–2025 edition's
+coverage, attribution, license, and historical-data caveats, with its original README.
+
+```powershell
+backcaster player --name "Mookie Betts" --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster team --team LAN --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --format csv --out pitchers.csv
+```
+
+Use Lahman's `teamID` values, such as `LAN` for the Dodgers (rather than the
+FanGraphs abbreviation `LAD`). A projection year needs the preceding three seasons:
+2022 requires 2019–2021. Missing seasons produce an error explaining which year
+is unavailable. Without `--data-dir`, the existing pybaseball source is used;
+FanGraphs may reject its automated requests with HTTP 403.
+
+Offline qualification uses a consistent modern rule across historical seasons:
+at least **3.1 PA per game** for hitters and **one inning per game** for pitchers.
+The season's game count is the maximum `G` in that year's `Teams.csv` records,
+so shortened seasons have lower thresholds. The PA threshold is rounded to the
+nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a
+reconstruction of historical award eligibility or batting-title exceptions.
+Relievers generally do not qualify under this pitching rule.
+
+Player stints are summed before qualification. Plate appearances are calculated
+as `AB + BB + HBP + SF + SH`; missing/blank HBP, SF, and SH values count as zero.
+Blank numeric counting-stat cells are also treated as zero; use a dataset with
+complete records for the seasons you intend to project.
+Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
+batters faced. Lahman player IDs keep different players with the same name separate;
+ambiguous name lookups report the matching IDs.
+
+Only qualified player-seasons enter projections and league regression baselines.
+Single-player projections require qualification in all three preceding seasons.
+Team and batch projections use each player's available qualified seasons within
+that window. For team selection, a traded player's full-season totals are assigned
+to the team in their latest stint for that season; this is not a current-roster forecast.
+
 ### 2) Team projection
 
 ```bash

{backcaster-0.3.0 → backcaster-0.3.2}/README.md

@@ -16,6 +16,27 @@ It supports:
 - Python **3.13+**
 - Internet access for first-time stat fetches (data is cached locally afterward)
 
+### Update an installed package
+
+Upgrade to the latest release available on PyPI:
+
+```powershell
+python -m pip install --upgrade backcaster
+```
+
+To install a specific release, such as 0.3.2:
+
+```powershell
+python -m pip install --upgrade backcaster==0.3.2
+```
+
+Run the command using the same Python environment where you run Backcaster.
+If you use a virtual environment, activate it first. Check the installed version with:
+
+```powershell
+python -m pip show backcaster
+```
+
 ### Install from source (recommended for contributors)
 
 ```bash
@@ -63,6 +84,51 @@ backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <battin
 backcaster player --name "Mookie Betts" --year 2026 --kind batting
 ```
 
+### Offline projections with Lahman CSVs
+
+Extract your Lahman CSV distribution into a local directory. Pass `--data-dir`
+to use it without any network requests, player-register downloads, or FanGraphs
+cache reads. The directory must contain `People.csv`, `Teams.csv`, and
+`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+without regard to case. The database is not bundled with Backcaster.
+
+See [Lahman database notes](docs/LAHMAN.md) for the supplied 1871–2025 edition's
+coverage, attribution, license, and historical-data caveats, with its original README.
+
+```powershell
+backcaster player --name "Mookie Betts" --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster team --team LAN --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --format csv --out pitchers.csv
+```
+
+Use Lahman's `teamID` values, such as `LAN` for the Dodgers (rather than the
+FanGraphs abbreviation `LAD`). A projection year needs the preceding three seasons:
+2022 requires 2019–2021. Missing seasons produce an error explaining which year
+is unavailable. Without `--data-dir`, the existing pybaseball source is used;
+FanGraphs may reject its automated requests with HTTP 403.
+
+Offline qualification uses a consistent modern rule across historical seasons:
+at least **3.1 PA per game** for hitters and **one inning per game** for pitchers.
+The season's game count is the maximum `G` in that year's `Teams.csv` records,
+so shortened seasons have lower thresholds. The PA threshold is rounded to the
+nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a
+reconstruction of historical award eligibility or batting-title exceptions.
+Relievers generally do not qualify under this pitching rule.
+
+Player stints are summed before qualification. Plate appearances are calculated
+as `AB + BB + HBP + SF + SH`; missing/blank HBP, SF, and SH values count as zero.
+Blank numeric counting-stat cells are also treated as zero; use a dataset with
+complete records for the seasons you intend to project.
+Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
+batters faced. Lahman player IDs keep different players with the same name separate;
+ambiguous name lookups report the matching IDs.
+
+Only qualified player-seasons enter projections and league regression baselines.
+Single-player projections require qualification in all three preceding seasons.
+Team and batch projections use each player's available qualified seasons within
+that window. For team selection, a traded player's full-season totals are assigned
+to the team in their latest stint for that season; this is not a current-roster forecast.
+
 ### 2) Team projection
 
 ```bash

{backcaster-0.3.0 → backcaster-0.3.2}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{backcaster-0.3.0 → backcaster-0.3.2}/src/backcaster/cli.py

@@ -12,6 +12,7 @@ from backcaster.data import (
     lookup_player_ids,
     resolve_player_lookup,
 )
+from backcaster.lahman import LahmanSource
 from backcaster.marcel import ProjectionError, project_player, project_team
 from backcaster.outputs import to_cli_table, to_csv, to_html
 
@@ -130,6 +131,10 @@ def build_parser() -> argparse.ArgumentParser:
         sp.add_argument("--kind", choices=["batting", "pitching"], required=True)
         sp.add_argument("--format", choices=_OUTPUT_FORMAT_CHOICES, default="cli")
         sp.add_argument("--out")
+        sp.add_argument(
+            "--data-dir",
+            help="Directory containing extracted Lahman CSVs (offline, qualified players only)",
+        )
 
     pp = sub.add_parser("player")
     add_common(pp)
@@ -151,6 +156,16 @@ def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
     try:
+        if args.data_dir:
+            result = LahmanSource(args.data_dir).project(
+                args.command,
+                args.year,
+                args.kind,
+                name=getattr(args, "name", None),
+                team=getattr(args, "team", None),
+            )
+            _render(result, args.format, args.out)
+            return 0
         return args.func(args)
     except (DataFetchError, PlayerLookupError, ProjectionError, ValueError) as exc:
         print(f"Error: {exc}", file=sys.stderr)

backcaster-0.3.2/src/backcaster/lahman.py

@@ -0,0 +1,143 @@
+"""Offline projections from extracted Lahman CSV files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.marcel import ProjectionError, project_player, project_team
+
+
+class LahmanSource:
+    def __init__(self, directory: str) -> None:
+        self.directory = Path(directory)
+        self.tables: dict[str, pd.DataFrame] = {}
+
+    def read(self, name: str, required: set[str]) -> pd.DataFrame:
+        if name not in self.tables:
+            paths = [
+                p for p in self.directory.glob("*") if p.name.casefold() == f"{name}.csv".casefold()
+            ]
+            if len(paths) != 1:
+                raise DataFetchError(f"Expected {name}.csv in Lahman directory '{self.directory}'.")
+            try:
+                self.tables[name] = pd.read_csv(paths[0], encoding="utf-8-sig", low_memory=False)
+            except (OSError, ValueError) as exc:
+                raise DataFetchError(f"Unable to read Lahman {name}.csv: {exc}") from exc
+        frame = self.tables[name]
+        missing = required - set(frame.columns)
+        if missing:
+            raise DataFetchError(
+                f"Lahman {name}.csv missing columns: {', '.join(sorted(missing))}."
+            )
+        return frame
+
+    def season(self, year: int, kind: str) -> pd.DataFrame:
+        if kind not in {"batting", "pitching"}:
+            raise DataFetchError(f"Invalid kind {kind!r}.")
+        name = "Batting" if kind == "batting" else "Pitching"
+        components = (
+            ["AB", "H", "2B", "3B", "HR", "BB", "SO"]
+            if kind == "batting"
+            else ["IPouts", "ER", "H", "HR", "BB", "SO", "BFP"]
+        )
+        stats = self.read(name, {"playerID", "yearID", "stint", "teamID", *components})
+        stats = stats[stats["yearID"] == year].copy()
+        if stats.empty:
+            raise DataFetchError(
+                f"Lahman {name}.csv has no data for {year}; choose a covered year or update the dataset."
+            )
+        games = self._season_games(year)
+        if kind == "batting":
+            for column in ["HBP", "SF", "SH"]:
+                if column not in stats:
+                    stats[column] = 0
+            components += ["HBP", "SF", "SH"]
+        try:
+            stats[components] = stats[components].apply(pd.to_numeric, errors="raise").fillna(0)
+            stats["stint"] = pd.to_numeric(stats["stint"], errors="raise")
+        except (ValueError, TypeError) as exc:
+            raise DataFetchError(
+                f"Invalid numeric data in Lahman {name}.csv for {year}: {exc}"
+            ) from exc
+        totals = stats.groupby("playerID", sort=False)[components].sum()
+        latest = (
+            stats.sort_values("stint", kind="stable")
+            .drop_duplicates("playerID", keep="last")
+            .set_index("playerID")
+        )
+        totals["Team"] = latest["teamID"]
+        if kind == "batting":
+            totals["PA"] = totals[["AB", "BB", "HBP", "SF", "SH"]].sum(axis=1)
+            minimum_pa = int(3.1 * games + 0.5)
+            totals = totals[totals["PA"] >= minimum_pa]
+        else:
+            totals["IP"] = totals["IPouts"] / 3
+            totals["BF"] = totals["BFP"]
+            totals = totals[totals["IPouts"] >= 3 * games]
+        if totals.empty:
+            raise DataFetchError(f"No qualified {kind} players in Lahman for {year}.")
+        totals = self._attach_names(totals)
+        totals["PlayerID"] = totals["playerID"]
+        totals["Season"] = year
+        return totals
+
+    def _season_games(self, year: int) -> float:
+        teams = self.read("Teams", {"yearID", "teamID", "G"})
+        games = pd.to_numeric(teams.loc[teams["yearID"] == year, "G"], errors="coerce").max()
+        if pd.isna(games) or games <= 0:
+            raise DataFetchError(f"Lahman Teams.csv has no valid game counts for {year}.")
+        return float(games)
+
+    def _attach_names(self, totals: pd.DataFrame) -> pd.DataFrame:
+        people = self.read("People", {"playerID", "nameFirst", "nameLast"}).copy()
+        people["Name"] = (
+            people["nameFirst"].fillna("") + " " + people["nameLast"].fillna("")
+        ).str.strip()
+        try:
+            totals = totals.reset_index().merge(
+                people[["playerID", "Name"]], on="playerID", how="left", validate="many_to_one"
+            )
+        except pd.errors.MergeError as exc:
+            raise DataFetchError("Duplicate player IDs in Lahman People.csv.") from exc
+        if totals["Name"].isna().any():
+            raise DataFetchError(
+                "Lahman People.csv is missing players present in season statistics."
+            )
+        return totals
+
+    def project(
+        self, command: str, year: int, kind: str, name: str | None = None, team: str | None = None
+    ) -> pd.DataFrame:
+        seasons = pd.concat(
+            [self.season(y, kind) for y in (year - 1, year - 2, year - 3)], ignore_index=True
+        )
+        if command == "player":
+            normalized = " ".join((name or "").casefold().split())
+            matches = seasons[
+                seasons["Name"].map(lambda value: " ".join(value.casefold().split())) == normalized
+            ]
+            ids = matches["PlayerID"].unique()
+            if len(ids) == 0:
+                raise PlayerLookupError(
+                    f"No qualified Lahman player found for '{name}' in the prior three seasons."
+                )
+            if len(ids) > 1:
+                raise PlayerLookupError(
+                    f"Ambiguous Lahman name '{name}'; matching player IDs: {', '.join(ids)}."
+                )
+            if matches["Season"].nunique() != 3:
+                raise ProjectionError(f"Player '{name}' must qualify in all three prior seasons.")
+            return project_player(
+                str(matches["Name"].iloc[0]), matches, kind, year, league_df=seasons
+            )
+        selected = seasons
+        if command == "team":
+            selected = seasons[seasons["Team"].str.casefold() == (team or "").casefold()]
+            if selected.empty:
+                raise ProjectionError(
+                    f"No qualified players for Lahman team ID '{team}' in the prior three seasons."
+                )
+        return project_team(selected, kind, year, baseline_df=seasons)

{backcaster-0.3.0 → backcaster-0.3.2}/src/backcaster/marcel.py

@@ -179,7 +179,10 @@ def project_team(
         comps = PITCHING_COMPONENTS
     baseline_source = baseline_df if baseline_df is not None else team_df
     _, baseline_rates = _compute_baseline_rates(baseline_source, comps)
-    group_column = team_df["IDfg"].fillna(team_df["Name"]) if "IDfg" in team_df.columns else "Name"
+    identity = "PlayerID" if "PlayerID" in team_df.columns else "IDfg"
+    group_column = (
+        team_df[identity].fillna(team_df["Name"]) if identity in team_df.columns else "Name"
+    )
     grouped = team_df.groupby(group_column, dropna=False, sort=False)
     projections: list[pd.DataFrame] = []
     for _, grp in grouped:

{backcaster-0.3.0 → backcaster-0.3.2/src/backcaster.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.3.0
+Version: 0.3.2
 Summary: Marcel-style MLB projection CLI built on pybaseball
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -46,6 +46,27 @@ It supports:
 - Python **3.13+**
 - Internet access for first-time stat fetches (data is cached locally afterward)
 
+### Update an installed package
+
+Upgrade to the latest release available on PyPI:
+
+```powershell
+python -m pip install --upgrade backcaster
+```
+
+To install a specific release, such as 0.3.2:
+
+```powershell
+python -m pip install --upgrade backcaster==0.3.2
+```
+
+Run the command using the same Python environment where you run Backcaster.
+If you use a virtual environment, activate it first. Check the installed version with:
+
+```powershell
+python -m pip show backcaster
+```
+
 ### Install from source (recommended for contributors)
 
 ```bash
@@ -93,6 +114,51 @@ backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <battin
 backcaster player --name "Mookie Betts" --year 2026 --kind batting
 ```
 
+### Offline projections with Lahman CSVs
+
+Extract your Lahman CSV distribution into a local directory. Pass `--data-dir`
+to use it without any network requests, player-register downloads, or FanGraphs
+cache reads. The directory must contain `People.csv`, `Teams.csv`, and
+`Batting.csv` or `Pitching.csv` for the selected kind. Filenames are matched
+without regard to case. The database is not bundled with Backcaster.
+
+See [Lahman database notes](docs/LAHMAN.md) for the supplied 1871–2025 edition's
+coverage, attribution, license, and historical-data caveats, with its original README.
+
+```powershell
+backcaster player --name "Mookie Betts" --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster team --team LAN --year 2022 --kind batting --data-dir "C:\Baseball\lahman"
+backcaster batch --year 2022 --kind pitching --data-dir "C:\Baseball\lahman" --format csv --out pitchers.csv
+```
+
+Use Lahman's `teamID` values, such as `LAN` for the Dodgers (rather than the
+FanGraphs abbreviation `LAD`). A projection year needs the preceding three seasons:
+2022 requires 2019–2021. Missing seasons produce an error explaining which year
+is unavailable. Without `--data-dir`, the existing pybaseball source is used;
+FanGraphs may reject its automated requests with HTTP 403.
+
+Offline qualification uses a consistent modern rule across historical seasons:
+at least **3.1 PA per game** for hitters and **one inning per game** for pitchers.
+The season's game count is the maximum `G` in that year's `Teams.csv` records,
+so shortened seasons have lower thresholds. The PA threshold is rounded to the
+nearest integer (502 PA for 162 games, 186 PA for 60 games). This is an analytical filter, not a
+reconstruction of historical award eligibility or batting-title exceptions.
+Relievers generally do not qualify under this pitching rule.
+
+Player stints are summed before qualification. Plate appearances are calculated
+as `AB + BB + HBP + SF + SH`; missing/blank HBP, SF, and SH values count as zero.
+Blank numeric counting-stat cells are also treated as zero; use a dataset with
+complete records for the seasons you intend to project.
+Pitching `IPouts` is divided by three for decimal innings, and `BFP` supplies
+batters faced. Lahman player IDs keep different players with the same name separate;
+ambiguous name lookups report the matching IDs.
+
+Only qualified player-seasons enter projections and league regression baselines.
+Single-player projections require qualification in all three preceding seasons.
+Team and batch projections use each player's available qualified seasons within
+that window. For team selection, a traded player's full-season totals are assigned
+to the team in their latest stint for that season; this is not a current-roster forecast.
+
 ### 2) Team projection
 
 ```bash

{backcaster-0.3.0 → backcaster-0.3.2}/src/backcaster.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/backcaster/__init__.py
 src/backcaster/cli.py
 src/backcaster/data.py
+src/backcaster/lahman.py
 src/backcaster/marcel.py
 src/backcaster/normalize.py
 src/backcaster/outputs.py
@@ -17,6 +18,7 @@ src/backcaster.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_cli_player_lookup.py
 tests/test_data.py
+tests/test_lahman.py
 tests/test_marcel_math.py
 tests/test_normalize.py
 tests/test_outputs.py

backcaster-0.3.2/tests/test_lahman.py

@@ -0,0 +1,239 @@
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+from backcaster.cli import main
+from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.lahman import LahmanSource
+from backcaster.marcel import ProjectionError
+
+
+@pytest.fixture
+def lahman(tmp_path: Path) -> Path:
+    pd.DataFrame(
+        [
+            {"playerID": "star", "nameFirst": "Test", "nameLast": "Star"},
+            {"playerID": "other", "nameFirst": "Other", "nameLast": "Player"},
+            {"playerID": "minor", "nameFirst": "Brief", "nameLast": "Career"},
+        ]
+    ).to_csv(tmp_path / "People.csv", index=False)
+    batting, pitching, teams = [], [], []
+    for year, games in [(2019, 162), (2020, 60), (2021, 162)]:
+        teams.append({"yearID": year, "teamID": "BOS", "G": games})
+        for player, ab, bb in [("star", 500, 60), ("other", 450, 70), ("minor", 20, 0)]:
+            batting.append(
+                dict(
+                    playerID=player,
+                    yearID=year,
+                    stint=1,
+                    teamID="BOS",
+                    AB=ab,
+                    H=150,
+                    **{"2B": 30, "3B": 2},
+                    HR=20,
+                    BB=bb,
+                    SO=100,
+                    HBP=5,
+                    SF=5,
+                    SH=1,
+                )
+            )
+            pitching.append(
+                dict(
+                    playerID=player,
+                    yearID=year,
+                    stint=1,
+                    teamID="BOS",
+                    IPouts=487 if player != "minor" else 10,
+                    ER=60,
+                    H=150,
+                    HR=20,
+                    BB=50,
+                    SO=180,
+                    BFP=700,
+                )
+            )
+    pd.DataFrame(batting).to_csv(tmp_path / "Batting.csv", index=False)
+    pd.DataFrame(pitching).to_csv(tmp_path / "Pitching.csv", index=False)
+    pd.DataFrame(teams).to_csv(tmp_path / "Teams.csv", index=False)
+    return tmp_path
+
+
+def test_season_qualification_and_components(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    batting = source.season(2021, "batting").set_index("PlayerID")
+    assert set(batting.index) == {"star", "other"}
+    assert batting.loc["star", "PA"] == 571
+    pitching = source.season(2021, "pitching").set_index("PlayerID")
+    assert pitching.loc["star", "IP"] == pytest.approx(162 + 1 / 3)
+    assert pitching.loc["star", "BF"] == 700
+
+
+def test_traded_player_combined_before_qualification(lahman: Path) -> None:
+    path = lahman / "Batting.csv"
+    frame = pd.read_csv(path)
+    row = frame[(frame.playerID == "star") & (frame.yearID == 2021)].copy()
+    frame = frame.drop(row.index)
+    for column in ["AB", "H", "2B", "3B", "HR", "BB", "SO", "HBP", "SF", "SH"]:
+        row[column] = row[column] / 2
+    second = row.assign(stint=2, teamID="LAN")
+    pd.concat([frame, row, second]).to_csv(path, index=False)
+    season = LahmanSource(str(lahman)).season(2021, "batting")
+    star = season[season.PlayerID == "star"]
+    assert len(star) == 1
+    assert star.iloc[0]["PA"] == 571
+    assert star.iloc[0]["Team"] == "LAN"
+
+
+def test_short_season_threshold(lahman: Path) -> None:
+    path = lahman / "Batting.csv"
+    frame = pd.read_csv(path)
+    frame.loc[frame.playerID == "star", ["AB", "BB", "HBP", "SF", "SH"]] = [190, 0, 0, 0, 0]
+    frame.to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    assert "star" in set(source.season(2020, "batting").PlayerID)
+    assert "star" not in set(source.season(2021, "batting").PlayerID)
+    with pytest.raises(ProjectionError, match="all three"):
+        source.project("player", 2022, "batting", name="Test Star")
+
+
+@pytest.mark.parametrize("command", ["player", "team", "batch"])
+@pytest.mark.parametrize("kind", ["batting", "pitching"])
+def test_offline_cli(
+    lahman: Path, monkeypatch: pytest.MonkeyPatch, command: str, kind: str
+) -> None:
+    def forbidden(*args, **kwargs):
+        raise AssertionError("offline mode attempted network access")
+
+    monkeypatch.setattr("backcaster.cli.lookup_player_ids", forbidden)
+    monkeypatch.setattr("backcaster.cli.fetch_season_stats", forbidden)
+    out = lahman / "projection.csv"
+    args = [
+        command,
+        "--year",
+        "2022",
+        "--kind",
+        kind,
+        "--data-dir",
+        str(lahman),
+        "--format",
+        "csv",
+        "--out",
+        str(out),
+    ]
+    if command == "player":
+        args += ["--name", "test star"]
+    if command == "team":
+        args += ["--team", "BOS"]
+    assert main(args) == 0
+    result = pd.read_csv(out)
+    assert len(result) == (1 if command == "player" else 2)
+    assert set(result.Year) == {2022}
+    assert result.Reliability.gt(0).all()
+
+
+def test_missing_season_and_files(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match="no data for 2025"):
+        source.season(2025, "batting")
+    missing = LahmanSource(str(lahman / "missing"))
+    with pytest.raises(DataFetchError, match="Expected Batting.csv"):
+        missing.season(2021, "batting")
+
+
+def test_no_match_and_team(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    with pytest.raises(PlayerLookupError, match="No qualified"):
+        source.project("player", 2022, "batting", name="Nobody Here")
+    with pytest.raises(ProjectionError, match="team ID"):
+        source.project("team", 2022, "batting", team="INVALID")
+
+
+def test_duplicate_names_are_not_merged(lahman: Path) -> None:
+    path = lahman / "People.csv"
+    people = pd.read_csv(path)
+    people.loc[people.playerID == "other", ["nameFirst", "nameLast"]] = ["Test", "Star"]
+    people.to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    assert len(source.project("batch", 2022, "batting")) == 2
+    with pytest.raises(PlayerLookupError, match="Ambiguous"):
+        source.project("player", 2022, "batting", name="Test Star")
+
+
+@pytest.mark.parametrize(
+    "case, message",
+    [
+        ("columns", "missing columns"),
+        ("numeric", "Invalid numeric"),
+        ("games", "no valid game counts"),
+        ("empty", "No qualified"),
+        ("duplicate", "Duplicate player IDs"),
+        ("people", "missing players"),
+    ],
+)
+def test_invalid_data_reports_actionable_errors(lahman: Path, case: str, message: str) -> None:
+    if case in {"columns", "numeric", "empty"}:
+        path = lahman / "Batting.csv"
+        frame = pd.read_csv(path)
+        if case == "columns":
+            frame = frame.drop(columns="AB")
+        elif case == "numeric":
+            frame["AB"] = "invalid"
+        else:
+            frame[["AB", "BB", "HBP", "SF", "SH"]] = 0
+    elif case == "games":
+        path = lahman / "Teams.csv"
+        frame = pd.read_csv(path)
+        frame["G"] = 0
+    else:
+        path = lahman / "People.csv"
+        frame = pd.read_csv(path)
+        frame = pd.concat([frame, frame.iloc[[0]]]) if case == "duplicate" else frame.iloc[0:0]
+    frame.to_csv(path, index=False)
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match=message):
+        source.season(2021, "batting")
+
+
+def test_unreadable_csv(lahman: Path) -> None:
+    (lahman / "Batting.csv").write_text("", encoding="utf-8")
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match="Unable to read"):
+        source.season(2021, "batting")
+
+
+def test_optional_columns_and_case_insensitive_filenames(lahman: Path) -> None:
+    path = lahman / "Batting.csv"
+    pd.read_csv(path).drop(columns=["HBP", "SF", "SH"]).to_csv(lahman / "batting.csv", index=False)
+    path.unlink()
+    season = LahmanSource(str(lahman)).season(2021, "batting")
+    assert (season[["HBP", "SF", "SH"]] == 0).all().all()
+
+
+def test_invalid_kind(lahman: Path) -> None:
+    source = LahmanSource(str(lahman))
+    with pytest.raises(DataFetchError, match="Invalid kind"):
+        source.season(2021, "fielding")
+
+
+def test_cli_missing_directory_returns_error(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert main(["batch", "--year", "2022", "--kind", "batting", "--data-dir", str(tmp_path)]) == 2
+    assert "Expected Batting.csv" in capsys.readouterr().err
+
+
+def test_qualification_boundary(lahman: Path) -> None:
+    path = lahman / "Batting.csv"
+    frame = pd.read_csv(path)
+    frame.loc[frame.playerID == "star", ["AB", "BB", "HBP", "SF", "SH"]] = [502, 0, 0, 0, 0]
+    frame.loc[frame.playerID == "other", ["AB", "BB", "HBP", "SF", "SH"]] = [501, 0, 0, 0, 0]
+    frame.to_csv(path, index=False)
+    assert set(LahmanSource(str(lahman)).season(2021, "batting").PlayerID) == {"star"}
+    path = lahman / "Pitching.csv"
+    frame = pd.read_csv(path)
+    frame.loc[frame.playerID == "star", "IPouts"] = 486
+    frame.loc[frame.playerID == "other", "IPouts"] = 485
+    frame.to_csv(path, index=False)
+    assert set(LahmanSource(str(lahman)).season(2021, "pitching").PlayerID) == {"star"}

{backcaster-0.3.0 → backcaster-0.3.2}/tests/test_marcel_math.py

@@ -186,7 +186,8 @@ def test_project_player_batting_with_missing_optional_columns() -> None:
     prior = _batting_prior().drop(columns=["HBP", "SF"])
     result = project_player("Test Hitter", prior, "batting", 2026)
     assert float(result.loc[0, "OBP"]) > 0
-    assert "HBP" in result.columns and "SF" in result.columns
+    assert "HBP" in result.columns
+    assert "SF" in result.columns
 
 
 def test_project_player_pitching() -> None: