backcaster 0.4.1__tar.gz → 0.4.2__tar.gz

{backcaster-0.4.1 → backcaster-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backcaster
-Version: 0.4.1
+Version: 0.4.2
 Summary: Marcel-style MLB projection CLI using local Lahman CSV data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
@@ -18,7 +18,7 @@ Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: pandas>=2.0
+Requires-Dist: pandas>=2.2.2
 Requires-Dist: numpy>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -27,6 +27,9 @@ Requires-Dist: ruff>=0.11.0; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: pandas-stubs>=2.2; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
 # Backcaster
@@ -56,10 +59,10 @@ Upgrade to the latest release available on PyPI:
 python -m pip install --upgrade backcaster
 ```
 
-To install a specific release, such as 0.4.1:
+To install a specific release, such as 0.4.2:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.1
+python -m pip install --upgrade backcaster==0.4.2
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -73,7 +76,7 @@ python -m pip show backcaster
 
 ```bash
 # from repo root
-uv sync
+uv sync --locked
 ```
 
 This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
@@ -81,10 +84,10 @@ This installs runtime dependencies and the `backcaster` CLI entrypoint defined i
 ### Install in editable/dev mode
 
 ```bash
-uv sync --extra dev
+uv sync --locked --extra dev
 ```
 
-This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`, `setuptools`, `wheel`, `twine`).
 
 ### Build/install as a package
 
@@ -102,7 +105,7 @@ The `player`, `team`, and `batch` commands also require `--kind batting|pitching
 The `hitters` and `pitchers` commands choose their kind automatically.
 
 Subcommand-specific required options:
-- `player` requires `--name`
+- `player` requires exactly one of `--name` or `--player-id`
 - `team` requires `--team`
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
@@ -133,7 +136,9 @@ Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
 For HTML, use `--format html --out hitters_2026.html` (or a pitcher output filename).
-File formats require `--out`; the CLI format prints to the terminal.
+File formats require `--out`; the CLI format prints to the terminal and rejects
+`--out`. Invalid output options fail before data is loaded. Unwritable output
+paths report an error on stderr and exit with status 2.
 
 Players qualify for selection by meeting the existing PA/IP threshold in at least
 one of those three seasons. This is a historical eligibility list, not an active
@@ -195,7 +200,15 @@ 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.
+ambiguous name lookups report the matching IDs. Select one with `--player-id`
+instead of `--name`, for example:
+
+```bash
+backcaster player --player-id bettsmo01 --year 2026 --kind batting
+```
+
+IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+rules as name lookups.
 
 Batter league regression and rebaselining use all non-pitcher player-seasons;
 qualification selects the displayed players. Pitching retains its qualified-only
@@ -226,7 +239,7 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv
 backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
-> `--out` is required for `csv` and `html` formats.
+> `--out` is required for `csv` and `html` formats and cannot be used with `cli`.
 
 ---
 
@@ -250,6 +263,8 @@ Terminal, CSV, and HTML outputs use the same display rules:
   up. Age and year are displayed as whole numbers too.
 - BA, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
   BA is the canonical batter output label (previously AVG).
+  Rates with zero denominators remain undefined (NaN) and display blank;
+  OPS is undefined when OBP or SLG is undefined.
 - ERA shows two decimals; WHIP shows three. W-L% shows a three-decimal
   fraction, such as `0.524`. H9, HR9, BB9, and SO9 show one decimal; SO/W shows two.
   W-L% without any decisions and SO/W without walks are undefined and display blank.
@@ -260,7 +275,7 @@ Terminal, CSV, and HTML outputs use the same display rules:
 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.
+exactly. Reliability shows six decimal places in CLI, CSV, and HTML output.
 
 **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,
@@ -326,6 +341,13 @@ Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
+### Python data-loading errors
+
+Local data-loading and validation failures raise
+`backcaster.data.DataLoadError` (renamed from `DataFetchError`). Player lookup
+failures continue to raise `PlayerLookupError`. The CLI reports these failures
+and filesystem errors on stderr with exit status 2.
+
 ## Dependency notes
 
 Runtime dependencies are intentionally minimal:
@@ -339,7 +361,12 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
+installs the locked tools with `--no-install-project`, then installs Backcaster
+with `--no-build-isolation` to keep build dependencies pinned. CI builds
+without build isolation using the locked build tools; wheel smoke tests install
+hash-checked runtime dependencies exported from the same lockfile.
 
 Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
 
@@ -347,7 +374,8 @@ Release/source ZIP archives may not include `uv.lock`. If it is missing in your
 uv lock
 ```
 
-Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+Do not hand-edit `uv.lock`; run `uv lock` and commit the updated lockfile when
+dependencies change. To deliberately refresh all pins, run `uv lock --upgrade`.
 
 ---
 

backcaster-0.4.1/src/backcaster.egg-info/PKG-INFO → backcaster-0.4.2/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: backcaster
-Version: 0.4.1
-Summary: Marcel-style MLB projection CLI using local Lahman CSV data
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/jeffreywevans/backcaster
-Project-URL: Repository, https://github.com/jeffreywevans/backcaster
-Project-URL: Issues, https://github.com/jeffreywevans/backcaster/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Operating System :: OS Independent
-Classifier: Environment :: Console
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering :: Information Analysis
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: pandas>=2.0
-Requires-Dist: numpy>=2.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-cov>=5.0; extra == "dev"
-Requires-Dist: ruff>=0.11.0; extra == "dev"
-Requires-Dist: mypy>=1.10; extra == "dev"
-Requires-Dist: pandas-stubs>=2.2; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
-Dynamic: license-file
-
 # Backcaster
 
 Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using local Lahman CSV files and `pandas`.
@@ -56,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.4.1:
+To install a specific release, such as 0.4.2:
 
 ```powershell
-python -m pip install --upgrade backcaster==0.4.1
+python -m pip install --upgrade backcaster==0.4.2
 ```
 
 Run the command using the same Python environment where you run Backcaster.
@@ -73,7 +42,7 @@ python -m pip show backcaster
 
 ```bash
 # from repo root
-uv sync
+uv sync --locked
 ```
 
 This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
@@ -81,10 +50,10 @@ This installs runtime dependencies and the `backcaster` CLI entrypoint defined i
 ### Install in editable/dev mode
 
 ```bash
-uv sync --extra dev
+uv sync --locked --extra dev
 ```
 
-This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`, `setuptools`, `wheel`, `twine`).
 
 ### Build/install as a package
 
@@ -102,7 +71,7 @@ The `player`, `team`, and `batch` commands also require `--kind batting|pitching
 The `hitters` and `pitchers` commands choose their kind automatically.
 
 Subcommand-specific required options:
-- `player` requires `--name`
+- `player` requires exactly one of `--name` or `--player-id`
 - `team` requires `--team`
 - `batch`, `hitters`, and `pitchers` require no player or team option
 
@@ -133,7 +102,9 @@ Both commands support `--data-dir`, `--format cli|csv|html`, and `--out`.
 They are shortcuts for `batch --kind batting` and `batch --kind pitching`.
 For a different data directory, add `--data-dir "C:\Baseball\lahman"`.
 For HTML, use `--format html --out hitters_2026.html` (or a pitcher output filename).
-File formats require `--out`; the CLI format prints to the terminal.
+File formats require `--out`; the CLI format prints to the terminal and rejects
+`--out`. Invalid output options fail before data is loaded. Unwritable output
+paths report an error on stderr and exit with status 2.
 
 Players qualify for selection by meeting the existing PA/IP threshold in at least
 one of those three seasons. This is a historical eligibility list, not an active
@@ -195,7 +166,15 @@ 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.
+ambiguous name lookups report the matching IDs. Select one with `--player-id`
+instead of `--name`, for example:
+
+```bash
+backcaster player --player-id bettsmo01 --year 2026 --kind batting
+```
+
+IDs match Lahman `People.csv.playerID` exactly and retain the same qualification
+rules as name lookups.
 
 Batter league regression and rebaselining use all non-pitcher player-seasons;
 qualification selects the displayed players. Pitching retains its qualified-only
@@ -226,7 +205,7 @@ backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv
 backcaster team --team LAN --year 2026 --kind pitching --format html --out ./out/lan_pitching_2026.html
 ```
 
-> `--out` is required for `csv` and `html` formats.
+> `--out` is required for `csv` and `html` formats and cannot be used with `cli`.
 
 ---
 
@@ -250,6 +229,8 @@ Terminal, CSV, and HTML outputs use the same display rules:
   up. Age and year are displayed as whole numbers too.
 - BA, OBP, SLG, and OPS always show three decimal places, including `1.048` OPS.
   BA is the canonical batter output label (previously AVG).
+  Rates with zero denominators remain undefined (NaN) and display blank;
+  OPS is undefined when OBP or SLG is undefined.
 - ERA shows two decimals; WHIP shows three. W-L% shows a three-decimal
   fraction, such as `0.524`. H9, HR9, BB9, and SO9 show one decimal; SO/W shows two.
   W-L% without any decisions and SO/W without walks are undefined and display blank.
@@ -260,7 +241,7 @@ Terminal, CSV, and HTML outputs use the same display rules:
 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.
+exactly. Reliability shows six decimal places in CLI, CSV, and HTML output.
 
 **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,
@@ -326,6 +307,13 @@ Lahman distribution from the same edition. Existing online caches are ignored.
 
 ---
 
+### Python data-loading errors
+
+Local data-loading and validation failures raise
+`backcaster.data.DataLoadError` (renamed from `DataFetchError`). Player lookup
+failures continue to raise `PlayerLookupError`. The CLI reports these failures
+and filesystem errors on stderr with exit status 2.
+
 ## Dependency notes
 
 Runtime dependencies are intentionally minimal:
@@ -339,7 +327,12 @@ Development dependencies (`--extra dev`) include:
 
 ### Lockfile policy (`uv.lock`)
 
-`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+`uv.lock` is committed and pins runtime, development, and build dependencies. CI uses
+`uv sync --locked --extra dev` and fails if the lockfile is out of date. CI first
+installs the locked tools with `--no-install-project`, then installs Backcaster
+with `--no-build-isolation` to keep build dependencies pinned. CI builds
+without build isolation using the locked build tools; wheel smoke tests install
+hash-checked runtime dependencies exported from the same lockfile.
 
 Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
 
@@ -347,7 +340,8 @@ Release/source ZIP archives may not include `uv.lock`. If it is missing in your
 uv lock
 ```
 
-Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+Do not hand-edit `uv.lock`; run `uv lock` and commit the updated lockfile when
+dependencies change. To deliberately refresh all pins, run `uv lock --upgrade`.
 
 ---
 

{backcaster-0.4.1 → backcaster-0.4.2}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
 ]
 requires-python = ">=3.13"
 dependencies = [
-  "pandas>=2.0",
+  "pandas>=2.2.2",
   "numpy>=2.0",
 ]
 
@@ -38,6 +38,9 @@ dev = [
   "mypy>=1.10",
   "pandas-stubs>=2.2",
   "build>=1.2",
+  "setuptools>=77",
+  "wheel",
+  "twine",
 ]
 
 [project.scripts]

{backcaster-0.4.1 → backcaster-0.4.2}/src/backcaster/__init__.py

@@ -1,4 +1,4 @@
 """backcaster package."""
 
 __all__ = ["__version__"]
-__version__ = "0.4.1"
+__version__ = "0.4.2"

{backcaster-0.4.1 → backcaster-0.4.2}/src/backcaster/batters.py

@@ -144,7 +144,7 @@ def _summarize(projected: pd.DataFrame, pa: pd.Series) -> pd.DataFrame:
     ).replace(0, np.nan)
     out["SLG"] = out["TB"] / out["AB"].replace(0, np.nan)
     out["OPS"] = out["OBP"] + out["SLG"]
-    return out.fillna(0)
+    return out
 
 
 def project_batters(seasons: pd.DataFrame, year: int) -> pd.DataFrame:

{backcaster-0.4.1 → backcaster-0.4.2}/src/backcaster/cli.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 import pandas as pd
 
-from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.data import DataLoadError, PlayerLookupError
 from backcaster.lahman import LahmanSource
 from backcaster.marcel import ProjectionError
 from backcaster.outputs import to_cli_table, to_csv, to_html
@@ -25,12 +25,19 @@ def _default_data_dir() -> str:
     return os.environ.get("LAHMAN_DATA_DIR", default)
 
 
+def _validate_output_options(output_format: str, out: str | None) -> None:
+    if output_format == "cli" and out is not None:
+        raise ValueError("--out cannot be used with --format cli; choose --format csv or html")
+    if output_format in _FILE_RENDERERS and not out:
+        raise ValueError(f"--out is required for {output_format} output")
+
+
 def _render(df: pd.DataFrame, output_format: str, out: str | None) -> None:
+    _validate_output_options(output_format, out)
     if output_format == "cli":
         print(to_cli_table(df))
     elif output_format in _FILE_RENDERERS:
-        if not out:
-            raise ValueError(f"--out is required for {output_format} output")
+        assert out is not None
         _FILE_RENDERERS[output_format](df, out)
     else:
         raise ValueError(f"Unsupported format: {output_format}")
@@ -47,7 +54,7 @@ def build_parser() -> argparse.ArgumentParser:
         else:
             sp.set_defaults(kind=kind)
         sp.add_argument("--format", choices=_OUTPUT_FORMAT_CHOICES, default="cli")
-        sp.add_argument("--out")
+        sp.add_argument("--out", help="Output path (required for csv/html; invalid with cli)")
         sp.add_argument(
             "--data-dir",
             default=_default_data_dir(),
@@ -56,7 +63,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     pp = sub.add_parser("player")
     add_common(pp)
-    pp.add_argument("--name", required=True)
+    player_selector = pp.add_mutually_exclusive_group(required=True)
+    player_selector.add_argument("--name", help="Player name (must identify one qualified player)")
+    player_selector.add_argument(
+        "--player-id", help="Exact Lahman player ID (for example, bettsmo01)"
+    )
 
     tp = sub.add_parser("team")
     add_common(tp)
@@ -75,16 +86,18 @@ def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
     try:
+        _validate_output_options(args.format, args.out)
         result = LahmanSource(args.data_dir).project(
             args.command,
             args.year,
             args.kind,
             name=getattr(args, "name", None),
             team=getattr(args, "team", None),
+            player_id=getattr(args, "player_id", None),
         )
         _render(result, args.format, args.out)
         return 0
-    except (DataFetchError, PlayerLookupError, ProjectionError, ValueError) as exc:
+    except (DataLoadError, PlayerLookupError, ProjectionError, ValueError, OSError) as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 2
 

{backcaster-0.4.1 → backcaster-0.4.2}/src/backcaster/data.py

@@ -1,8 +1,8 @@
 """Errors reported when local source data cannot be loaded or resolved."""
 
 
-class DataFetchError(RuntimeError):
-    pass
+class DataLoadError(RuntimeError):
+    """Local source files are missing, unreadable, or invalid."""
 
 
 class PlayerLookupError(RuntimeError):

{backcaster-0.4.1 → backcaster-0.4.2}/src/backcaster/lahman.py

@@ -7,7 +7,7 @@ from pathlib import Path
 import pandas as pd
 
 from backcaster.batters import project_batters
-from backcaster.data import DataFetchError, PlayerLookupError
+from backcaster.data import DataLoadError, PlayerLookupError
 from backcaster.marcel import ProjectionError, project_player, project_team
 
 
@@ -15,32 +15,41 @@ class LahmanSource:
     def __init__(self, directory: str) -> None:
         self.directory = Path(directory)
         self.tables: dict[str, pd.DataFrame] = {}
+        self._requested_columns: dict[str, set[str]] = {}
+        self._people: pd.DataFrame | None = None
 
     def read(self, name: str, required: set[str]) -> pd.DataFrame:
-        if name not in self.tables:
+        optional = {"Batting": {"HBP", "SF", "SH"}, "People": {"birthYear"}}.get(name, set())
+        columns = required | optional
+        if name not in self.tables or columns - self._requested_columns[name]:
+            columns |= self._requested_columns.get(name, set())
             paths = [
                 p for p in self.directory.glob("*") if p.name.casefold() == f"{name}.csv".casefold()
             ]
             if len(paths) != 1:
-                raise DataFetchError(
+                raise DataLoadError(
                     f"Expected {name}.csv in Lahman directory '{self.directory}'. "
                     "Extract the Lahman CSVs there or select their directory with --data-dir."
                 )
             try:
-                self.tables[name] = pd.read_csv(paths[0], encoding="utf-8-sig", low_memory=False)
+                self.tables[name] = pd.read_csv(
+                    paths[0],
+                    encoding="utf-8-sig",
+                    low_memory=False,
+                    usecols=lambda column: column in columns,
+                )
+                self._requested_columns[name] = columns
             except (OSError, ValueError) as exc:
-                raise DataFetchError(f"Unable to read Lahman {name}.csv: {exc}") from exc
+                raise DataLoadError(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))}."
-            )
+            raise DataLoadError(f"Lahman {name}.csv missing columns: {', '.join(sorted(missing))}.")
         return frame
 
     def season(self, year: int, kind: str, *, qualified: bool = True) -> pd.DataFrame:
         if kind not in {"batting", "pitching"}:
-            raise DataFetchError(f"Invalid kind {kind!r}.")
+            raise DataLoadError(f"Invalid kind {kind!r}.")
         name = "Batting" if kind == "batting" else "Pitching"
         components = (
             ["AB", "H", "2B", "3B", "HR", "BB", "SO", "R", "RBI", "SB", "CS", "IBB", "GIDP"]
@@ -66,7 +75,7 @@ class LahmanSource:
         stats = self.read(name, {"playerID", "yearID", "stint", "teamID", *components})
         stats = stats[stats["yearID"] == year].copy()
         if stats.empty:
-            raise DataFetchError(
+            raise DataLoadError(
                 f"Lahman {name}.csv has no data for {year}; choose a covered year or update the dataset."
             )
         games = self._season_games(year)
@@ -79,7 +88,7 @@ class LahmanSource:
             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(
+            raise DataLoadError(
                 f"Invalid numeric data in Lahman {name}.csv for {year}: {exc}"
             ) from exc
         totals = stats.groupby("playerID", sort=False)[components].sum()
@@ -100,7 +109,7 @@ class LahmanSource:
         if qualified:
             totals = totals[totals["Qualified"]]
         if totals.empty:
-            raise DataFetchError(f"No qualified {kind} players in Lahman for {year}.")
+            raise DataLoadError(f"No qualified {kind} players in Lahman for {year}.")
         totals = totals.rename(columns={"GIDP": "GDP"})
         totals = self._attach_names(totals)
         totals["PlayerID"] = totals["playerID"]
@@ -111,32 +120,39 @@ class LahmanSource:
         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}.")
+            raise DataLoadError(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", *(["birthYear"] if "birthYear" in people else [])]],
-                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 self._people is None:
+            people = self.read("People", {"playerID", "nameFirst", "nameLast"})
+            if people["playerID"].duplicated().any():
+                raise DataLoadError("Duplicate player IDs in Lahman People.csv.")
+            names = (
+                people["nameFirst"].fillna("") + " " + people["nameLast"].fillna("")
+            ).str.strip()
+            self._people = people.assign(Name=names).set_index("playerID")
+            self._people = self._people[["Name", *(["birthYear"] if "birthYear" in people else [])]]
+        totals = totals.reset_index()
+        for column in self._people:
+            totals[column] = totals["playerID"].map(self._people[column])
         if totals["Name"].isna().any():
-            raise DataFetchError(
+            raise DataLoadError(
                 "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
+        self,
+        command: str,
+        year: int,
+        kind: str,
+        name: str | None = None,
+        team: str | None = None,
+        player_id: str | None = None,
     ) -> pd.DataFrame:
+        if name is not None and player_id is not None:
+            raise ValueError("Specify either name or player_id, not both.")
         batting = pd.DataFrame()
         if kind == "batting":
             seasons, batting = self._batting_population(year)
@@ -148,7 +164,7 @@ class LahmanSource:
             )
         eligible = seasons[seasons["Qualified"]]
         if command == "player":
-            candidates = self._player_seasons(eligible, name)
+            candidates = self._player_seasons(eligible, name, player_id)
             matches = seasons[seasons["PlayerID"] == candidates["PlayerID"].iloc[0]]
             if kind == "batting":
                 return batting[batting["PlayerID"] == matches["PlayerID"].iloc[0]].reset_index(
@@ -182,15 +198,15 @@ class LahmanSource:
                 pd.to_numeric, errors="raise"
             )
         except (ValueError, TypeError) as exc:
-            raise DataFetchError("Invalid game counts in Lahman Appearances.csv.") from exc
+            raise DataLoadError("Invalid game counts in Lahman Appearances.csv.") from exc
         counts = appearances[["G_all", "G_p"]]
         invalid = counts.replace([float("inf"), -float("inf")], float("nan")).isna() | (counts < 0)
         if invalid.any().any() or (appearances["G_p"] > appearances["G_all"]).any():
-            raise DataFetchError("Invalid game counts in Lahman Appearances.csv.")
+            raise DataLoadError("Invalid game counts in Lahman Appearances.csv.")
         games = appearances.groupby(["playerID", "yearID"])[["G_all", "G_p"]].sum(min_count=1)
         seasons = seasons.merge(games, left_on=["PlayerID", "Season"], right_index=True, how="left")
         if seasons[["G_all", "G_p"]].isna().any().any():
-            raise DataFetchError(
+            raise DataLoadError(
                 "Appearances.csv must cover every batting player-season with game counts."
             )
         # A primary pitcher appears as pitcher in more than half of their games.
@@ -202,7 +218,17 @@ class LahmanSource:
             raise ProjectionError("No qualified non-pitcher batters in the prior three seasons.")
         return seasons, projected
 
-    def _player_seasons(self, seasons: pd.DataFrame, name: str | None) -> pd.DataFrame:
+    def _player_seasons(
+        self, seasons: pd.DataFrame, name: str | None, player_id: str | None = None
+    ) -> pd.DataFrame:
+        if player_id is not None:
+            matches = seasons[seasons["PlayerID"] == player_id]
+            if matches.empty:
+                raise PlayerLookupError(
+                    f"No qualified Lahman player found for player ID '{player_id}' "
+                    "in the prior three seasons."
+                )
+            return matches
         normalized = " ".join((name or "").casefold().split())
         matches = seasons[
             seasons["Name"].map(lambda value: " ".join(value.casefold().split())) == normalized
@@ -214,6 +240,7 @@ class LahmanSource:
             )
         if len(ids) > 1:
             raise PlayerLookupError(
-                f"Ambiguous Lahman name '{name}'; matching player IDs: {', '.join(ids)}."
+                f"Ambiguous Lahman name '{name}'; matching player IDs: {', '.join(ids)}. "
+                "Select one with --player-id instead of --name."
             )
         return matches