backcaster 0.3.0__tar.gz

backcaster-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backcaster contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backcaster-0.3.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: backcaster
+Version: 0.3.0
+Summary: Marcel-style MLB projection CLI built on pybaseball
+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
+Requires-Dist: pandas>=2.0
+Requires-Dist: pybaseball>=2.2
+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 [`pybaseball`](https://github.com/jldbc/pybaseball) and `pandas`.
+
+It supports:
+- **Single player projections** (`player`)
+- **Single team projections** (`team`)
+- **League-wide batch projections** (`batch`)
+- Output as terminal table, CSV, or HTML
+
+---
+
+## Installation
+
+### Requirements
+- Python **3.13+**
+- Internet access for first-time stat fetches (data is cached locally afterward)
+
+### Install from source (recommended for contributors)
+
+```bash
+# from repo root
+uv sync
+```
+
+This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
+
+### Install in editable/dev mode
+
+```bash
+uv sync --extra dev
+```
+
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+
+### Build/install as a package
+
+```bash
+python -m build
+pip install dist/backcaster-*.whl
+```
+
+---
+
+## Quickstart CLI usage
+
+All commands require:
+- `--year` target projection year
+- `--kind` one of `batting` or `pitching`
+
+Subcommand-specific required options:
+- `player` requires `--name`
+- `team` requires `--team`
+- `batch` requires no additional required option
+
+```bash
+backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
+```
+
+### 1) Player projection
+
+```bash
+backcaster player --name "Mookie Betts" --year 2026 --kind batting
+```
+
+### 2) Team projection
+
+```bash
+backcaster team --team LAD --year 2026 --kind pitching
+```
+
+### 3) Batch projection (all players returned by source data)
+
+```bash
+backcaster batch --year 2026 --kind batting
+```
+
+### File outputs
+
+```bash
+backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv --out ./out/mookie_2026.csv
+backcaster team --team LAD --year 2026 --kind pitching --format html --out ./out/lad_pitching_2026.html
+```
+
+> `--out` is required for `csv` and `html` formats.
+
+---
+
+## Output examples
+
+### CLI table output (`--format cli`, default)
+
+Example shape (columns vary by batting vs pitching):
+
+```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
+```
+
+### CSV output (`--format csv`)
+A single-row CSV for `player`; multi-row CSV for `team` and `batch`.
+
+### HTML output (`--format html`)
+A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
+
+---
+
+## Cache behavior
+
+Backcaster caches season stat pulls under:
+
+```text
+~/.cache/backcaster/
+```
+
+Cache details:
+- Key pattern: `<kind>_<year>.parquet` (preferred) or `<kind>_<year>.csv` (fallback)
+- Read order: Parquet first, then CSV
+- Write behavior: atomic temp-file write + rename to reduce corruption risk
+- Parquet write failures automatically fall back to CSV
+
+Practical implications:
+- First run for a season may be slower (network fetch).
+- Re-runs are typically faster (local cache hit).
+- If upstream data changes and you need a refresh, delete the relevant cache file(s) and rerun.
+
+---
+
+## Dependency notes
+
+Runtime dependencies are intentionally minimal:
+- `pandas` for tabular data processing and projection output
+- `pybaseball` for MLB player/team seasonal stat retrieval and player ID lookup
+
+Development dependencies (`--extra dev`) include:
+- `pytest`, `pytest-cov`
+- `ruff`
+- `mypy`, `pandas-stubs`
+
+### Lockfile policy (`uv.lock`)
+
+`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+
+Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
+
+```bash
+uv lock
+```
+
+Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+
+---
+
+## What this projection does and does not claim
+
+### What it does
+- Implements a **Marcel-style** weighted/regressed projection over prior seasons.
+- Uses configurable reliability/regression/playing-time assumptions in code defaults.
+- Produces transparent, table-based outputs for downstream analysis.
+
+### What it does **not** claim
+- It is **not** an official MLB/club forecasting system.
+- It does **not** model injuries, role changes, park effects, coaching strategy, or transaction context in a comprehensive way.
+- It does **not** guarantee predictive superiority versus commercial/public projection systems.
+- It should be treated as a **baseline projection tool**, not a betting or financial decision engine.
+
+---
+
+## Development and quality checks
+
+For release preparation and PyPI Trusted Publishing, see [RELEASING.md](RELEASING.md).
+Changes for the next release are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Coverage + JUnit reports
+
+```bash
+pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml
+```
+
+### Lint and types
+
+```bash
+ruff check .
+mypy
+```
+
+### SonarScanner
+
+```bash
+sonar-scanner -Dsonar.projectVersion=$(PYTHONPATH=src python -c "from backcaster import __version__; print(__version__)")
+```
+
+Sonar consumes:
+- `coverage.xml`
+- `pytest.xml`
+
+---
+
+## Security and responsible use
+
+Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

backcaster-0.3.0/README.md

@@ -0,0 +1,207 @@
+# Backcaster
+
+Backcaster is a Python CLI that produces **Marcel-style MLB projections** from the prior three seasons of data using [`pybaseball`](https://github.com/jldbc/pybaseball) and `pandas`.
+
+It supports:
+- **Single player projections** (`player`)
+- **Single team projections** (`team`)
+- **League-wide batch projections** (`batch`)
+- Output as terminal table, CSV, or HTML
+
+---
+
+## Installation
+
+### Requirements
+- Python **3.13+**
+- Internet access for first-time stat fetches (data is cached locally afterward)
+
+### Install from source (recommended for contributors)
+
+```bash
+# from repo root
+uv sync
+```
+
+This installs runtime dependencies and the `backcaster` CLI entrypoint defined in `pyproject.toml`.
+
+### Install in editable/dev mode
+
+```bash
+uv sync --extra dev
+```
+
+This adds test/lint/type-check/build tooling (`pytest`, `pytest-cov`, `ruff`, `mypy`, `pandas-stubs`, `build`).
+
+### Build/install as a package
+
+```bash
+python -m build
+pip install dist/backcaster-*.whl
+```
+
+---
+
+## Quickstart CLI usage
+
+All commands require:
+- `--year` target projection year
+- `--kind` one of `batting` or `pitching`
+
+Subcommand-specific required options:
+- `player` requires `--name`
+- `team` requires `--team`
+- `batch` requires no additional required option
+
+```bash
+backcaster <player|team|batch> [subcommand-options] --year <YEAR> --kind <batting|pitching> [--format cli|csv|html] [--out PATH]
+```
+
+### 1) Player projection
+
+```bash
+backcaster player --name "Mookie Betts" --year 2026 --kind batting
+```
+
+### 2) Team projection
+
+```bash
+backcaster team --team LAD --year 2026 --kind pitching
+```
+
+### 3) Batch projection (all players returned by source data)
+
+```bash
+backcaster batch --year 2026 --kind batting
+```
+
+### File outputs
+
+```bash
+backcaster player --name "Mookie Betts" --year 2026 --kind batting --format csv --out ./out/mookie_2026.csv
+backcaster team --team LAD --year 2026 --kind pitching --format html --out ./out/lad_pitching_2026.html
+```
+
+> `--out` is required for `csv` and `html` formats.
+
+---
+
+## Output examples
+
+### CLI table output (`--format cli`, default)
+
+Example shape (columns vary by batting vs pitching):
+
+```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
+```
+
+### CSV output (`--format csv`)
+A single-row CSV for `player`; multi-row CSV for `team` and `batch`.
+
+### HTML output (`--format html`)
+A basic HTML table (no custom CSS) suitable for quick sharing or embedding.
+
+---
+
+## Cache behavior
+
+Backcaster caches season stat pulls under:
+
+```text
+~/.cache/backcaster/
+```
+
+Cache details:
+- Key pattern: `<kind>_<year>.parquet` (preferred) or `<kind>_<year>.csv` (fallback)
+- Read order: Parquet first, then CSV
+- Write behavior: atomic temp-file write + rename to reduce corruption risk
+- Parquet write failures automatically fall back to CSV
+
+Practical implications:
+- First run for a season may be slower (network fetch).
+- Re-runs are typically faster (local cache hit).
+- If upstream data changes and you need a refresh, delete the relevant cache file(s) and rerun.
+
+---
+
+## Dependency notes
+
+Runtime dependencies are intentionally minimal:
+- `pandas` for tabular data processing and projection output
+- `pybaseball` for MLB player/team seasonal stat retrieval and player ID lookup
+
+Development dependencies (`--extra dev`) include:
+- `pytest`, `pytest-cov`
+- `ruff`
+- `mypy`, `pandas-stubs`
+
+### Lockfile policy (`uv.lock`)
+
+`uv.lock` pins transitive versions for reproducible environments when working from a Git checkout.
+
+Release/source ZIP archives may not include `uv.lock`. If it is missing in your environment, regenerate it locally:
+
+```bash
+uv lock
+```
+
+Do not hand-edit `uv.lock`; regenerate it when dependencies change.
+
+---
+
+## What this projection does and does not claim
+
+### What it does
+- Implements a **Marcel-style** weighted/regressed projection over prior seasons.
+- Uses configurable reliability/regression/playing-time assumptions in code defaults.
+- Produces transparent, table-based outputs for downstream analysis.
+
+### What it does **not** claim
+- It is **not** an official MLB/club forecasting system.
+- It does **not** model injuries, role changes, park effects, coaching strategy, or transaction context in a comprehensive way.
+- It does **not** guarantee predictive superiority versus commercial/public projection systems.
+- It should be treated as a **baseline projection tool**, not a betting or financial decision engine.
+
+---
+
+## Development and quality checks
+
+For release preparation and PyPI Trusted Publishing, see [RELEASING.md](RELEASING.md).
+Changes for the next release are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Coverage + JUnit reports
+
+```bash
+pytest --junitxml=pytest.xml --cov=src --cov-report=xml:coverage.xml
+```
+
+### Lint and types
+
+```bash
+ruff check .
+mypy
+```
+
+### SonarScanner
+
+```bash
+sonar-scanner -Dsonar.projectVersion=$(PYTHONPATH=src python -c "from backcaster import __version__; print(__version__)")
+```
+
+Sonar consumes:
+- `coverage.xml`
+- `pytest.xml`
+
+---
+
+## Security and responsible use
+
+Please review `SECURITY.md` for reporting guidance. Backcaster is an analytical utility and should be validated independently before use in production pipelines.

backcaster-0.3.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "backcaster"
+dynamic = ["version"]
+description = "Marcel-style MLB projection CLI built on pybaseball"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+  "Environment :: Console",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.13"
+dependencies = [
+  "pandas>=2.0",
+  "pybaseball>=2.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/jeffreywevans/backcaster"
+Repository = "https://github.com/jeffreywevans/backcaster"
+Issues = "https://github.com/jeffreywevans/backcaster/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.11.0",
+  "mypy>=1.10",
+  "pandas-stubs>=2.2",
+  "build>=1.2",
+]
+
+[project.scripts]
+backcaster = "backcaster.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "backcaster.__version__"}
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["F401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+pretty = true
+show_error_codes = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["pandas", "pandas.*", "pybaseball", "pybaseball.*"]
+ignore_missing_imports = true

backcaster-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

backcaster-0.3.0/src/backcaster/__init__.py

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