fantasyfb Fantasy football league simulation and optimization toolkit. Pulls projections from nflverse data, syncs roster state from a Yahoo Fantasy league, and runs Monte Carlo season simulations to value pickups, trades, and draft picks.

Docs: https://tefirman.github.io/fantasyfb/

Install

pip install fantasyfb

For local development:

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

Python 3.10+ is required.

Quickstart

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 for a walkthrough.

Command-line tools

After install, four entry points are on your PATH:

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

# Same run, as a self-contained interactive HTML report (or --format both)
fantasyfb --team "My Team" --sims 1000 --adds --drops --format html

# 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. The fantasyfb weekly CLI shortens that to 30 minutes on game days (September through January, every day except Wednesday and Friday), so reruns pick up finished games. Past the cache window you'll need a live connection again to refresh it — see nflreadpy caching for details and the --refresh-cache flag.

Public API

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:

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

Development

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.