Metadata-Version: 2.4
Name: fantasyfb
Version: 0.8.0
Summary: Fantasy football league simulation and optimization tool.
Author-email: Taylor Firman <tefirman@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/tefirman/fantasyfb
Project-URL: Repository, https://github.com/tefirman/fantasyfb
Project-URL: Issues, https://github.com/tefirman/fantasyfb/issues
Keywords: fantasy-football,nfl,simulation,yahoo-fantasy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: nflreadpy>=0.1.5
Requires-Dist: pyarrow>=14.0
Requires-Dist: yahoo-fantasy-api>=2.6
Requires-Dist: yahoo-oauth>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pytz>=2023.3
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
Dynamic: license-file

<table>
<tr>
  <td><img src="https://github.com/tefirman/fantasyfb/blob/main/assets/fantasyfb_logo.png?raw=true" width="400" alt="fantasyfb logo"></td>
  <td>
    <h1>fantasyfb</h1>
    <p>Fantasy football league simulation and optimization toolkit. Pulls projections from <a href="https://github.com/nflverse">nflverse</a> data, syncs roster state from a Yahoo Fantasy league, and runs Monte Carlo season simulations to value pickups, trades, and draft picks.</p>
  </td>
</tr>
</table>

[![PyPI version](https://badge.fury.io/py/fantasyfb.svg)](https://badge.fury.io/py/fantasyfb)
[![Run Tests](https://github.com/tefirman/fantasyfb/actions/workflows/test.yml/badge.svg)](https://github.com/tefirman/fantasyfb/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Docs:** <https://tefirman.github.io/fantasyfb/>

## Install

```bash
pip install fantasyfb
```

For local development:

```bash
git clone https://github.com/tefirman/fantasyfb.git
cd fantasyfb
pip install -e ".[dev]"
```

Python 3.10+ is required.

## Quickstart

```python
import fantasyfb as fb

league = fb.League(name="My Team")
schedule_sim, standings_sim = league.season_sims(postseason=True)
print(standings_sim[["team", "wins_avg", "playoffs", "winner"]])
```

`fb.League(name=...)` reads from the Yahoo Fantasy API, so you'll need
`oauth2.json` (and `.env` with `CONSUMER_KEY` / `CONSUMER_SECRET`) set
up alongside the script. See the
[yahoo_oauth docs](https://github.com/josuebrunel/yahoo-oauth) for a
walkthrough.

## Command-line tools

After install, four entry points are on your PATH:

| Command            | Source                              | Use                                  |
| ------------------ | ----------------------------------- | ------------------------------------ |
| `fantasyfb`        | `fantasyfb.league:main`             | Weekly projections + lineup analysis |
| `snake-draft`      | `fantasyfb.drafts.snake:main`       | Live snake-draft cockpit             |
| `salary-cap-draft` | `fantasyfb.drafts.salary_cap:main`  | Live salary-cap (auction) draft tool |
| `draft-prep`       | `fantasyfb.drafts.prep:main`        | Pre-draft tiers / VORP / mocks       |

```bash
# Weekly run for a team
fantasyfb --team "My Team" --sims 1000 --adds --drops

# Pre-draft analytics
draft-prep tiers --team "My Team"
draft-prep mock --team "My Team" --adp ADP.csv --my-pick 7 --sims 50

# Draft-day cockpit
snake-draft --team "My Team" --adp ADP.csv
salary-cap-draft --team "My Team"
```

Run any command with `--help` for the full option list.

NFL data (stats, schedules, rosters) is cached to disk for 24 hours, so
repeated runs within that window work offline. Past the 24h mark you'll
need a live connection again to refresh the cache — see
[nflreadpy caching](docs/architecture.md#nflreadpy-caching) for details
and the `--refresh-cache` flag.

## Public API

```python
from fantasyfb import (
    League,                            # main entry point
    FantasyScorer,                     # scoring rules -> points
    MatchupModel, ProjectionEngineV2,  # projection internals
    LineupOptimizer,
    SeasonSimulator, ScheduleManager,
    NflreadpyProvider,                 # default data backend
)
```

Lower-level utilities live in submodules and can be imported directly:

```python
from fantasyfb.drafts.tools import compute_vorp, assign_tiers, MockDraft
from fantasyfb.drafts.snake_cockpit import build_board, view_best
from fantasyfb.sim.backtest import run_backtest, evaluate
from fantasyfb.io.excel_exporter import FantasyExcelExporter
```

| Subpackage              | Purpose                                    |
| ----------------------- | ------------------------------------------ |
| `fantasyfb.league`      | Top-level `League` class                   |
| `fantasyfb.configs`     | League / scoring presets                   |
| `fantasyfb.drafts`      | Snake, salary-cap, prep, shared draft math |
| `fantasyfb.data`        | Yahoo client + nflverse providers          |
| `fantasyfb.scoring`     | Scoring, lineup optimization, matchups     |
| `fantasyfb.projections` | V2 projection engine, walk-forward fitter  |
| `fantasyfb.sim`         | Season simulation, backtests, schedule     |
| `fantasyfb.analysis`    | WAR, move analysis                         |
| `fantasyfb.io`          | Excel export                               |

## Development

```bash
pip install -e ".[dev]"
pytest                       # full test suite
python -m build              # produce sdist + wheel under dist/
```

The `tests/` directory pulls a small slice of nflverse parquet data on
first run; subsequent runs are cached locally.

## License

MIT. See [LICENSE](LICENSE).
