Reference

League

class espyn.League(league_id: int, season: Optional[int] = None, cache: Optional[Cache] = None)

Bases: object

Representation of an ESPN fantasy football league

Retrieve and model a league for a given season. Makes API request unless given cache contains league data.

Parameters

league_id (int) – ID of ESPN league
season (Optional[int]) – NFL season
cache (Optional[Cache]) – cache to reduce network requests

all_scores(include_playoffs: bool = True) → List[float]

Get list of scores for all matchups up to (and excluding) current week

Parameters: include_playoffs (bool) – whether to include scores from playoff matchups
Returns: list of team scores
Return type: List[float]

average_score(include_playoffs: bool = True) → float

Get league’s average score (per scoring period)

Parameters: include_playoffs (bool) – whether to include scores from playoff matchups
Returns: average score
Return type: float

current_matchup_num() → int

Get current matchup number

Returns: matchup number
Return type: int

get_matchup(number: int, team_id: int, boxscore: bool = False) → Matchup

Get matchup by matchup number and team ID

Parameters

number (int) – matchup number (usually a week number during reg season)
team_id (int) – team ID
boxscore (bool) – whether to load boxscore (will require Internet connection if data not cached)

Returns

specified matchup

Return type

Matchup

get_matchups_by_number(number: int, boxscore: bool = False) → List[Matchup]

Get all matchups from matchup number

Parameters

number (int) – matchup number (usually a week number during reg season)
boxscore (bool) – whether to load boxscore (will require Internet connection if data not cached)

Returns

specified matchups

Return type

List[Matchup]

get_team_by_id(team_id: int) → Team

Get team with given team ID

Parameters: team_id (int) – team ID
Returns: Team with given ID
Return type: Team

matchup_num_to_scoring_periods(matchup_num: int) → List[int]

Get scoring periods corresponding to a matchup number

Parameters: matchup_num (int) – matchup number
Returns: scoring period(s) composing matchup
Return type: List[int]

name_from_user_id(user_id: str) → Optional[str]

Get member name from ESPN user ID

Parameters: user_id (str) – ESPN user ID
Returns: member name
Return type: Optional[str]

scoring_period_to_matchup_num(scoring_period: int) → Optional[int]

Get matchup number corresponding to a scoring period

Returns None if scoring period is not part of any matchup

Parameters: scoring_period (int) – scoring period
Returns: matchup number
Return type: Optional[int]

property teams: List[Team]

Teams composing the league.

Returns: list of teams in league
Return type: List[Team]

to_json() → Dict[str, Any]

Get JSON-serializable dictionary representation

Returns: dictionary representation of league
Return type: Dict[str, Any]

Team

class espyn.Team(team_data: Dict[str, Any], league: League)

Bases: object

Representation of fantasy team

Parameters

team_data (Dict[str, Any]) – data from API response
league (League) – fantasy league to which team belongs

property full_name: str

Full team name (location and nickname)

Returns: full team name
Return type: str

get_data_by_matchup(number: int) → List[TeamWeek]

Get team’s boxscore (player-level data) for matchup

Parameters: number – matchup number
Returns: boxscore data
Return type: List[TeamWeek]

get_matchup(number: int, boxscore: bool = False) → Matchup

Get team’s matchup by number

Parameters

number (int) – matchup number
boxscore (bool) – whether to load boxscore

Returns

matchup for given scoring period

Return type

Matchup

property record: str

Team record (W-L-T)

Returns: record
Return type: str

scores(include_playoffs: bool = True) → List[float]

Get scores from individual scoring periods

Parameters: include_playoffs (bool) – include scores from playoff matchups
Returns: team’s scores
Return type: List[float]

to_json() → Dict[str, Any]

Get JSON-serializable dictionary representation

Returns: dictionary representation of team
Return type: Dict[str, Any]

Matchup

class espyn.Matchup(matchup_data: Dict[str, Any], league: League)

Bases: object

Representation of a fantasy matchup

Matchups may contain one or more scoring periods depending on the league settings. A scoring period is one NFL week.

Parameters

matchup_data (Dict[str, Any]) – data from API response
league (League) – fantasy league to which matchup belongs

property all_data: List[Optional[List[TeamWeek]]]

All boxscores in matchup

Returns: home and away boxscores
Return type: List[Optional[List[TeamWeek]]]
Raise: RuntimeError if boxscore data not yet loaded

property away_data: Optional[List[TeamWeek]]

Away team’s boxscore(s) if loaded (and not bye)

Returns: away team’s boxscore(s) or None
Return type: Optional[List[TeamWeek]]

property away_team: Optional[Team]

Away team

Returns: away team, if not bye matchup
Return type: Optional[Team]

property boxscore_loaded: bool

Whether boxscore (player-level) data have been loaded

Requires network request if data are not cached.

Returns: whether boxscore is loaded
Return type: bool

property error: Optional[str]

Description of errors encountered setting boxscore data

Returns: errors encountered setting boxscore data
Return type: Optional[str]

get_individual_scores() → List[float]

Get scores from individual scoring periods for both teams

Returns: scores from all scoring periods
Return type: List[float]

property home_data: Optional[List[TeamWeek]]

Home team’s boxscore(s) if loaded

Returns: home team’s boxscore(s) or None
Return type: Optional[List[TeamWeek]]

property home_team: Team

Home team

Returns: home team
Return type: Team

set_boxscore_data(data, scoring_period)

property team_ids: List[int]

Team IDs of matchup teams

Returns: team IDs
Return type: List[int]

to_json() → Dict[str, Any]

Get JSON-serializable dictionary representation

Returns: dictionary representation of matchup
Return type: Dict[str, Any]

TeamWeek

class espyn.TeamWeek(week_data: Dict[str, Any], scoring_period: int)

Bases: object

Representation of team boxscore for a scoring period

Parameters

week_data (Dict[str, Any]) – data from API response
scoring_period (int) – scoring period

PlayerWeek

class espyn.PlayerWeek(stat_data: Dict[str, Any])

Bases: object

Representation of player stat line for one NFL week

Parameters: stat_data (Dict[str, Any]) – data from API response

calculate_points(score_values: Dict[int, float]) → float

Manually calculate points from code to points mapping

Parameters: score_values (Dict[int, float]) – code to point-value mapping
Returns: player’s fantasy points according to mapping
Return type: float

proj_line = {}

property projection_error: float

Difference between projection and actual score

Returns: projection error, positive if projection too high
Return type: float

stat_line = {}

to_json() → Dict[str, Any]

Get JSON-serializable dictionary representation

Returns: dictionary representation of player-week
Return type: Dict[str, Any]

Player

class espyn.Player(player_data: Dict[str, Any])

Bases: object

Representation of NFL player

Parameters: player_data (Dict[str, Any]) – data from API response

property full_name: str

Player’s full name

Returns: player name
Return type: str

to_json()

Get JSON-serializable dictionary representation

Returns: dictionary representation of player
Return type: Dict[str, Any]

espyn.caches module

class espyn.caches.Cache

Bases: object

Abstract base class for caches

load(scoring_period: Optional[int] = None) → Any

Load data from cache

If scoring_period is given, the API response containing that period’s boxscores will be loaded.

Parameters: scoring_period (Optional[int]) – scoring period to load (optional)
Returns: JSON-deserialized cache entry
Return type: Any

save(data: Any, scoring_period: Optional[int] = None) → None

Save data to cache

Parameters

data (Any) – JSON-serializable data to cache
scoring_period (Optional[int]) – scoring period of boxscores in data

set_league(league: League) → None

Set league to be used with cache

Parameters: league (League) – league whose data will be cached

class espyn.caches.LocalCache(cache_dir, ignore_cache=False)

Bases: Cache

Concrete Cache implementation to read/write local JSON files

load(scoring_period=None)

Load data from cache

If scoring_period is given, the API response containing that period’s boxscores will be loaded.

Parameters: scoring_period (Optional[int]) – scoring period to load (optional)
Returns: JSON-deserialized cache entry
Return type: Any

save(data, scoring_period=None)

Save data to cache

Parameters

data (Any) – JSON-serializable data to cache
scoring_period (Optional[int]) – scoring period of boxscores in data

espyn.caches.cache_operation(func: Callable) → Callable

Wrap a League method in cache load/save attempts

Decorated methods will first pass their parameters to the load method of the League’s Cache instance. If the cache hits, the data are returned. Otherwise the decorated method is called, and the retrieved data are passed to the Cache’s save method with the parameters of the original call.

The first parameter of the decorated method is expected to have a cache attribute (typically the League instance). The decorator is dependent on the load and save methods expecting the same parameters as the decorated functions.

Parameters: func (Callable) – function/method to decorate
Returns: decorated function/method
Return type: Callable