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

# 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 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.