Skip to content

Data providers

NFL data

League(nfl_provider=...) accepts any subclass of NFLDataProvider. The default is NflreadpyProvider.

fantasyfb.data.nfl_provider.NFLDataProvider

Bases: ABC

Abstract base for NFL data backends.

The legacy column name player_id_sr is preserved as the canonical cross-table player identifier. Concrete providers are free to populate it with whatever ID system they natively use (PFR id, GSIS id, etc.) as long as the same value joins stats, rosters, and depth charts.

get_player_stats abstractmethod 

get_player_stats(start: int, finish: int) -> pd.DataFrame

Per-game player + team-defense stats for the YYYYWW range.

Required columns

player_id_sr, name, position, team, opponent, season, week, game_id, points_allowed, rush_yds, rush_att, rush_td, rush_first_down, rec, rec_yds, rec_td, rec_first_down, pass_yds, pass_cmp, pass_td, pass_first_down, pass_int, fumbles_lost, kick_ret_yds, punt_ret_yds, kick_ret_td, punt_ret_td, xpm, fgm, sacks, def_int, fumbles_rec, def_int_td, fumbles_rec_td

Defenses are emitted as one row per team-week with position == "DEF" and player_id_sr set to the team abbreviation.

get_schedule abstractmethod 

get_schedule(start_year: int, end_year: int) -> pd.DataFrame

NFL schedule with one row per team-game (two rows per game).

Required columns

season, week, date, team, home_away, opp_team, elo_diff, opp_elo

elo_diff and opp_elo carry forward the legacy "opponent strength" signal. Providers without true Elo ratings should map a strength proxy (e.g. Vegas spread) into elo_diff with consistent sign: positive elo_diff means the team is favored.

get_rosters abstractmethod 

get_rosters(start_year: int, end_year: int) -> pd.DataFrame

Active rosters for the year range.

Required columns

name, current_team, position, player_id_sr

Optional columns (populated when available): yahoo_id -- enables direct Yahoo->NFL ID linkage

get_depth_charts abstractmethod 

get_depth_charts(season: int | None = None, week: int | None = None) -> pd.DataFrame

Depth charts, current-week by default or a historical snapshot.

Parameters:

Name Type Description Default
season int | None

if given, look up this season's depth chart instead of the live/current one. Historical lookups are only meaningful for seasons before the provider's rolling current-snapshot feed took over (nflreadpy: pre-2025).

 None
week int | None

if given alongside season, the specific week within that season. Ignored when season is omitted.

 None
Required columns

name, current_team, position, string

string follows the legacy convention: 1.0 = starter, 2.0 = backup, 3.0 = third string, etc.

get_draft abstractmethod 

get_draft(year: int) -> pd.DataFrame

Draft picks for the given year.

Required columns

name, current_team, player_id_sr

team_aliases abstractmethod 

team_aliases() -> pd.DataFrame

Translation table between Yahoo and provider-native team codes.

Required columns

yahoo -- value Yahoo emits as editorial_team_abbr real_abbrev -- provider-native team code (matches the team column returned by get_player_stats and get_schedule)

The column names mirror the legacy team_abbrevs.csv schema so that existing callers reading nfl_teams.real_abbrev keep working; the values now point at the active backend rather than at PFR.

fantasyfb.data.nflreadpy_provider.NflreadpyProvider 

NflreadpyProvider(*, cache_mode: str | None = None, cache_duration: int | None = None, live_cache_duration: int | None = None, refresh: bool = False)

Bases: NFLDataProvider

Concrete NFLDataProvider backed by the nflreadpy parquet feeds.

Parameters:

Name Type Description Default
cache_mode str | None

Override nflreadpy's cache mode ("filesystem", "memory", or "off"). Defaults to "filesystem" so downloaded parquet files survive across separate fantasyfb invocations -- draft prep runs the CLI repeatedly over hours or days, and nflreadpy's own default ("memory") is cleared at the end of every process, so every run re-downloaded from nflverse over the network. Left alone if the NFLREADPY_CACHE env var is already set, so an explicit user preference always wins.

 None
cache_duration int | None

Override nflreadpy's cache TTL in seconds. Left at nflreadpy's own default (24h) unless given.

 None
live_cache_duration int | None

Shorter cache TTL in seconds to use only during a live NFL window (see is_live_nfl_window), so game-day runs see newly finished games. Ignored when cache_duration is given or the NFLREADPY_CACHE_DURATION env var is set, so an explicit choice always wins.

 None
refresh bool

Clear nflreadpy's cache before use, forcing a fresh download on the next pull despite cache_mode. Escape hatch for callers that explicitly want current data (e.g. a --refresh-cache CLI flag).

 False

Yahoo Fantasy client

fantasyfb.data.yahoo_client

Yahoo Fantasy API client.

This module provides a clean interface for interacting with Yahoo's Fantasy API, handling authentication, rate limiting, and common API operations.

FantasyPlatformClient

Bases: ABC

Abstract base for fantasy platform backends.

get_current_week abstractmethod 

get_current_week() -> int

Current fantasy week for the connected league.

get_league_config abstractmethod 

get_league_config() -> Dict

League settings, scoring, and roster composition.

Returns:

Type Description
Dict

Dict with keys: settings -- dict including at least playoff_start_week, num_playoff_teams, end_week (all int) scoring -- dict of fantasyfb scoring category -> value roster_spots -- DataFrame with 'position'/'count' columns

get_fantasy_teams abstractmethod 

get_fantasy_teams() -> List[Dict]

All teams in the league.

Returns:

Type Description
List[Dict]

List of dicts with keys: team_key, name, manager.

get_all_players abstractmethod 

get_all_players(injury_tries: int = 10) -> pd.DataFrame

Full eligible player pool for the league.

get_team_rosters abstractmethod 

get_team_rosters(teams: List[Dict], week: int) -> pd.DataFrame

Rosters for all teams for the given week.

Returns:

Type Description
DataFrame

DataFrame with columns: player_id, selected_position, fantasy_team.

get_schedule abstractmethod 

get_schedule(teams: List[Dict], current_week: int, playoff_start_week: int, end_week: Optional[int] = None) -> pd.DataFrame

Fantasy schedule and scores through the given week.

Returns:

Type Description
DataFrame

DataFrame with columns: week, team_1, team_2, score_1, score_2.

get_roster_percentages abstractmethod 

get_roster_percentages(players_df: DataFrame, chunk_size: int = 25) -> Optional[pd.DataFrame]

Roster/ownership percentages for the given players.

Returns:

Type Description
Optional[DataFrame]

DataFrame with player_id/pct_rostered columns, or None for
Optional[DataFrame]

backends with no ownership-percentage concept (e.g. Sleeper).

get_my_team_key abstractmethod 

get_my_team_key() -> Optional[str]

team_key of the team this client is scoped to, if known.

refresh_oauth 

refresh_oauth(threshold: int = 59) -> None

Refresh the auth token if it's near expiration.

No-op by default; only Yahoo needs this (Sleeper's read API is unauthenticated). Kept on the interface so callers don't need to special-case which backend they're talking to.

YahooFantasyClient 

YahooFantasyClient()

Bases: FantasyPlatformClient

Client for interacting with Yahoo Fantasy API.

Handles OAuth authentication, rate limiting, and provides clean methods for common fantasy football operations.

Initialize the Yahoo client with credentials and OAuth.

refresh_oauth 

refresh_oauth(threshold: int = 59)

Check auth token status and refresh if expired.

Parameters:

Name Type Description Default
threshold int

Minutes before expiration to refresh token

 59

list_team_names 

list_team_names(season: int) -> List[str]

List the user's fantasy team name(s) for season, without connecting to any league or picking one -- e.g. to populate a dropdown before calling :meth:connect_to_league.

Returns:

Type Description
List[str]

Team names in Yahoo's own order (empty if no NFL entry is found
List[str]

for that season). Note distinct names can belong to entirely
List[str]

different leagues (see :meth:_find_nfl_league_teams).

connect_to_league 

connect_to_league(season: int, team_name: Optional[str] = None) -> Tuple[str, str]

Connect to a fantasy league for the specified season.

Parameters:

Name Type Description Default
season int

NFL season year

 required
team_name Optional[str]

Specific team name if user has multiple teams

 None

Returns:

Type Description
Tuple[str, str]

Tuple of (team_name, league_id)

get_current_week 

get_current_week() -> int

Get the current fantasy week.

Returns:

Type Description
int

The league's current week, per Yahoo.

get_my_team_key 

get_my_team_key() -> Optional[str]

Get the team_key of the team this client is connected as.

Returns:

Type Description
Optional[str]

The team_key resolved during connect_to_league(), or None if
Optional[str]

not yet connected.

get_league_config 

get_league_config() -> Dict

Get league settings, scoring, and roster composition in the shape FantasyPlatformClient callers expect.

Returns:

Type Description
Dict

Dict with 'settings' (including playoff_start_week,
Dict

num_playoff_teams, end_week), 'scoring', and 'roster_spots' keys.

get_league_settings 

get_league_settings() -> Tuple[Dict, pd.DataFrame, Dict]

Get league settings including roster spots and scoring.

Returns:

Type Description
Tuple[Dict, DataFrame, Dict]

Tuple of (settings_dict, roster_spots_df, scoring_dict)

get_fantasy_teams 

get_fantasy_teams() -> List[Dict]

Get list of all teams in the league.

Returns:

Type Description
List[Dict]

List of team dictionaries with keys: team_key, name, manager

get_all_players 

get_all_players(injury_tries: int = 10) -> pd.DataFrame

Get all eligible players with roster percentages and injury status.

Parameters:

Name Type Description Default
injury_tries int

Number of attempts to get injury statuses

 10

Returns:

Type Description
DataFrame

DataFrame with player information

get_team_rosters 

get_team_rosters(teams: List[Dict], week: int) -> pd.DataFrame

Get current rosters for all teams.

Parameters:

Name Type Description Default
teams List[Dict]

List of team dictionaries from get_fantasy_teams()

 required
week int

Week number to get rosters for

 required

Returns:

Type Description
DataFrame

DataFrame with player rosters

get_roster_percentages 

get_roster_percentages(players_df: DataFrame, chunk_size: int = 25) -> pd.DataFrame

Get roster percentages for players.

Parameters:

Name Type Description Default
players_df DataFrame

DataFrame with player_id column

 required
chunk_size int

Number of players to query per API call

 25

Returns:

Type Description
DataFrame

DataFrame with player_id and pct_rostered columns

get_schedule 

get_schedule(teams: List[Dict], current_week: int, playoff_start_week: int, end_week: Optional[int] = None) -> pd.DataFrame

Get fantasy league schedule.

Parameters:

Name Type Description Default
teams List[Dict]

List of team dictionaries

 required
current_week int

Current week number

 required
playoff_start_week int

Week when playoffs start

 required
end_week Optional[int]

Last playable week of the season, if known. Caps the query range so requesting a schedule past the end of the season doesn't retry against nonexistent weeks.

 None

Returns:

Type Description
DataFrame

DataFrame with schedule information

Player data manager

fantasyfb.data.player_data_manager

Player data management for fantasy football.

This module handles player ID mapping, name corrections, injury tracking, bye weeks, roster percentages, and depth chart integration.

NFLDataProvider

Bases: ABC

Abstract base for NFL data backends.

The legacy column name player_id_sr is preserved as the canonical cross-table player identifier. Concrete providers are free to populate it with whatever ID system they natively use (PFR id, GSIS id, etc.) as long as the same value joins stats, rosters, and depth charts.

get_player_stats abstractmethod 

get_player_stats(start: int, finish: int) -> pd.DataFrame

Per-game player + team-defense stats for the YYYYWW range.

Required columns

player_id_sr, name, position, team, opponent, season, week, game_id, points_allowed, rush_yds, rush_att, rush_td, rush_first_down, rec, rec_yds, rec_td, rec_first_down, pass_yds, pass_cmp, pass_td, pass_first_down, pass_int, fumbles_lost, kick_ret_yds, punt_ret_yds, kick_ret_td, punt_ret_td, xpm, fgm, sacks, def_int, fumbles_rec, def_int_td, fumbles_rec_td

Defenses are emitted as one row per team-week with position == "DEF" and player_id_sr set to the team abbreviation.

get_schedule abstractmethod 

get_schedule(start_year: int, end_year: int) -> pd.DataFrame

NFL schedule with one row per team-game (two rows per game).

Required columns

season, week, date, team, home_away, opp_team, elo_diff, opp_elo

elo_diff and opp_elo carry forward the legacy "opponent strength" signal. Providers without true Elo ratings should map a strength proxy (e.g. Vegas spread) into elo_diff with consistent sign: positive elo_diff means the team is favored.

get_rosters abstractmethod 

get_rosters(start_year: int, end_year: int) -> pd.DataFrame

Active rosters for the year range.

Required columns

name, current_team, position, player_id_sr

Optional columns (populated when available): yahoo_id -- enables direct Yahoo->NFL ID linkage

get_depth_charts abstractmethod 

get_depth_charts(season: int | None = None, week: int | None = None) -> pd.DataFrame

Depth charts, current-week by default or a historical snapshot.

Parameters:

Name Type Description Default
season int | None

if given, look up this season's depth chart instead of the live/current one. Historical lookups are only meaningful for seasons before the provider's rolling current-snapshot feed took over (nflreadpy: pre-2025).

 None
week int | None

if given alongside season, the specific week within that season. Ignored when season is omitted.

 None
Required columns

name, current_team, position, string

string follows the legacy convention: 1.0 = starter, 2.0 = backup, 3.0 = third string, etc.

get_draft abstractmethod 

get_draft(year: int) -> pd.DataFrame

Draft picks for the given year.

Required columns

name, current_team, player_id_sr

team_aliases abstractmethod 

team_aliases() -> pd.DataFrame

Translation table between Yahoo and provider-native team codes.

Required columns

yahoo -- value Yahoo emits as editorial_team_abbr real_abbrev -- provider-native team code (matches the team column returned by get_player_stats and get_schedule)

The column names mirror the legacy team_abbrevs.csv schema so that existing callers reading nfl_teams.real_abbrev keep working; the values now point at the active backend rather than at PFR.

FantasyPlatformClient

Bases: ABC

Abstract base for fantasy platform backends.

get_current_week abstractmethod 

get_current_week() -> int

Current fantasy week for the connected league.

get_league_config abstractmethod 

get_league_config() -> Dict

League settings, scoring, and roster composition.

Returns:

Type Description
Dict

Dict with keys: settings -- dict including at least playoff_start_week, num_playoff_teams, end_week (all int) scoring -- dict of fantasyfb scoring category -> value roster_spots -- DataFrame with 'position'/'count' columns

get_fantasy_teams abstractmethod 

get_fantasy_teams() -> List[Dict]

All teams in the league.

Returns:

Type Description
List[Dict]

List of dicts with keys: team_key, name, manager.

get_all_players abstractmethod 

get_all_players(injury_tries: int = 10) -> pd.DataFrame

Full eligible player pool for the league.

get_team_rosters abstractmethod 

get_team_rosters(teams: List[Dict], week: int) -> pd.DataFrame

Rosters for all teams for the given week.

Returns:

Type Description
DataFrame

DataFrame with columns: player_id, selected_position, fantasy_team.

get_schedule abstractmethod 

get_schedule(teams: List[Dict], current_week: int, playoff_start_week: int, end_week: Optional[int] = None) -> pd.DataFrame

Fantasy schedule and scores through the given week.

Returns:

Type Description
DataFrame

DataFrame with columns: week, team_1, team_2, score_1, score_2.

get_roster_percentages abstractmethod 

get_roster_percentages(players_df: DataFrame, chunk_size: int = 25) -> Optional[pd.DataFrame]

Roster/ownership percentages for the given players.

Returns:

Type Description
Optional[DataFrame]

DataFrame with player_id/pct_rostered columns, or None for
Optional[DataFrame]

backends with no ownership-percentage concept (e.g. Sleeper).

get_my_team_key abstractmethod 

get_my_team_key() -> Optional[str]

team_key of the team this client is scoped to, if known.

refresh_oauth 

refresh_oauth(threshold: int = 59) -> None

Refresh the auth token if it's near expiration.

No-op by default; only Yahoo needs this (Sleeper's read API is unauthenticated). Kept on the interface so callers don't need to special-case which backend they're talking to.

PlayerDataManager 

PlayerDataManager(client: FantasyPlatformClient, season: int, current_week: int, nfl_provider: NFLDataProvider)

Manages all player data operations including ID mapping, corrections, and enrichment.

Initialize the player data manager.

Parameters:

Name Type Description Default
client FantasyPlatformClient

FantasyPlatformClient instance

 required
season int

Current NFL season

 required
current_week int

Current week in season

 required
nfl_provider NFLDataProvider

Pluggable NFL data backend.

 required

map_player_ids 

map_player_ids(players: DataFrame) -> pd.DataFrame

Map platform player IDs to NFL player IDs.

nflreadpy's weekly roster feed carries the Yahoo player ID directly, so we can join on that instead of the legacy name-matching cascade. That eliminates the bespoke name_corrections.csv layer that used to be required because Pro Football Reference and Yahoo disagreed on player spellings.

Non-Yahoo clients (e.g. Sleeper) already resolve player_id_sr themselves (via gsis_id) and use real NFL team codes directly in editorial_team_abbr rather than Yahoo's own abbreviations, so the Yahoo-team-code translation and yahoo_id join are skipped for them; the name+team fallback below still runs to backfill anyone their client-side ID resolution missed.

Parameters:

Name Type Description Default
players DataFrame

DataFrame with player data from the active platform client

 required

Returns:

Type Description
DataFrame

DataFrame with mapped player IDs

add_injuries 

add_injuries(players: DataFrame, week: int) -> pd.DataFrame

Add manual projections for injury timespans.

Parameters:

Name Type Description Default
players DataFrame

DataFrame with player data

 required
week int

Current week being analyzed

 required

Returns:

Type Description
DataFrame

DataFrame with injury information added

add_bye_weeks 

add_bye_weeks(players: DataFrame, nfl_schedule: DataFrame) -> pd.DataFrame

Derive bye weeks based on the current NFL schedule.

Parameters:

Name Type Description Default
players DataFrame

DataFrame with player data

 required
nfl_schedule DataFrame

NFL schedule DataFrame

 required

Returns:

Type Description
DataFrame

DataFrame with bye week information added

add_roster_percentages 

add_roster_percentages(players: DataFrame, inc: int = 25) -> pd.DataFrame

Pull the percentage of leagues each player is rostered in.

Parameters:

Name Type Description Default
players DataFrame

DataFrame with player data

 required
inc int

Number of players to pull per API call

 25

Returns:

Type Description
DataFrame

DataFrame with roster percentage information added. Backends
DataFrame

with no ownership-percentage concept (e.g. Sleeper) get
DataFrame

pct_rostered = 0.0 for every player -- callers filtering on
DataFrame

min_rostership should pass 0.0 explicitly for those leagues.

add_depth_charts 

add_depth_charts(players: DataFrame, week: int) -> pd.DataFrame

Pull current team depth charts from nflreadpy and merge into players DataFrame.

Parameters:

Name Type Description Default
players DataFrame

DataFrame with player data

 required
week int

Current week being analyzed

 required

Returns:

Type Description
DataFrame

DataFrame with depth chart information added

process_players 

process_players(players: DataFrame, nfl_schedule: DataFrame, week: int) -> pd.DataFrame

Run the complete player data processing pipeline.

Parameters:

Name Type Description Default
players DataFrame

Raw player data from the active platform client

 required
nfl_schedule DataFrame

NFL schedule for bye weeks

 required
week int

Current week being analyzed

 required

Returns:

Type Description
DataFrame

Fully processed player DataFrame

normalize_name_key 

normalize_name_key(names: Series) -> pd.Series

Build a join-key copy of a name column: trailing generational suffix stripped, whitespace collapsed, lowercased. Never overwrites the display name -- callers merge on this and keep name as-is.