sleeper-api-wrapper 1.0.7__tar.gz → 1.2.1__tar.gz

sleeper_api_wrapper-1.2.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Swapnik Katkoori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sleeper_api_wrapper-1.2.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.1
+Name: sleeper-api-wrapper
+Version: 1.2.1
+Summary: A Python API wrapper for Sleeper Fantasy sports, as well as tools to simplify received data.
+Home-page: https://github.com/dtsong/sleeper-api-wrapper
+License: MIT
+Keywords: fantasy football,fantasy sports,sports,sleeper fantasy,sleeper
+Author: Dan Song, Ford Higgins
+Author-email: py-sleeper-api-wrapper-maintainers@googlegroups.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: requests (>=2.22.0,<3.0.0)
+Project-URL: Documentation, https://github.com/dtsong/sleeper-api-wrapper/tree/master/docs
+Project-URL: Repository, https://github.com/dtsong/sleeper-api-wrapper
+Description-Content-Type: text/markdown
+
+![GitHub](https://img.shields.io/github/license/dtsong/sleeper-api-wrapper.svg?color=blue)
+![GitHub issues](https://img.shields.io/github/issues/dtsong/sleeper-api-wrapper.svg?color=orange)
+![PyPI](https://img.shields.io/pypi/v/sleeper-api-wrapper)
+# sleeper-api-wrapper
+A Python API wrapper for Sleeper Fantasy Sports, as well as tools to simplify data received. It makes all endpoints found in the Sleeper API docs: https://docs.sleeper.app/ available and turns the JSON response received into Python types for easy usage.
+
+Ownership was transferred from @SwapnikKatkoori to @dtsong in March 2022 to continue efforts.
+Original Repository: https://github.com/SwapnikKatkoori/sleeper-api-wrapper
+
+# Table of Contents
+1. [Project Roadmap](#roadmap)
+2. [Installation](#install)
+3. [Documentation](#documentation)
+4. [Notes](#notes)
+5. [Dependencies](#depends)
+6. [License](#license)
+
+<a name="roadmap"></a>
+# Project Roadmap
+* Establish solid CICD practices with automated testing and validation of pull requests via GitHub Actions
+* Ensure libraries are up to date and secure.
+* Update endpoints and logic with the current Sleeper API docs
+* Investigate performance optimization (effort, implementation, etc)
+
+Want to help? Send me a message to @dtsong
+
+<a name="install"></a>
+# Install
+```
+pip install sleeper-api-wrapper
+```
+
+<a name="documentation"></a>
+# Documentation
+There are five objects in the package that get data from the Sleeper API. Most of them are intuitive based on the [Sleeper API docs](https://docs.sleeper.com/), but full documentation for the Python objects and their methods can be found in the [`docs` folder](https://github.com/dtsong/sleeper-api-wrapper/tree/master/docs). There are some bespoke methods for transforming the data into more useful structures in addition to the methods that directly call the API.
+
+<a name="notes"></a>
+# Notes
+This package is intended to be used by Python version 3.8 and higher. There might be some wacky results for previous versions.
+
+<a name="depends"></a>
+# Dependencies
+
+[requests](https://github.com/kennethreitz/requests)
+- Used for all http requests in sleeper_wrapper
+
+[pytest](https://github.com/pytest-dev/pytest)
+- Used for all testing in sleeper_wrapper
+
+<a name="license"></a>
+# License
+This project is licensed under the terms of the MIT license.
+

sleeper_api_wrapper-1.2.1/README.md

@@ -0,0 +1,52 @@
+![GitHub](https://img.shields.io/github/license/dtsong/sleeper-api-wrapper.svg?color=blue)
+![GitHub issues](https://img.shields.io/github/issues/dtsong/sleeper-api-wrapper.svg?color=orange)
+![PyPI](https://img.shields.io/pypi/v/sleeper-api-wrapper)
+# sleeper-api-wrapper
+A Python API wrapper for Sleeper Fantasy Sports, as well as tools to simplify data received. It makes all endpoints found in the Sleeper API docs: https://docs.sleeper.app/ available and turns the JSON response received into Python types for easy usage.
+
+Ownership was transferred from @SwapnikKatkoori to @dtsong in March 2022 to continue efforts.
+Original Repository: https://github.com/SwapnikKatkoori/sleeper-api-wrapper
+
+# Table of Contents
+1. [Project Roadmap](#roadmap)
+2. [Installation](#install)
+3. [Documentation](#documentation)
+4. [Notes](#notes)
+5. [Dependencies](#depends)
+6. [License](#license)
+
+<a name="roadmap"></a>
+# Project Roadmap
+* Establish solid CICD practices with automated testing and validation of pull requests via GitHub Actions
+* Ensure libraries are up to date and secure.
+* Update endpoints and logic with the current Sleeper API docs
+* Investigate performance optimization (effort, implementation, etc)
+
+Want to help? Send me a message to @dtsong
+
+<a name="install"></a>
+# Install
+```
+pip install sleeper-api-wrapper
+```
+
+<a name="documentation"></a>
+# Documentation
+There are five objects in the package that get data from the Sleeper API. Most of them are intuitive based on the [Sleeper API docs](https://docs.sleeper.com/), but full documentation for the Python objects and their methods can be found in the [`docs` folder](https://github.com/dtsong/sleeper-api-wrapper/tree/master/docs). There are some bespoke methods for transforming the data into more useful structures in addition to the methods that directly call the API.
+
+<a name="notes"></a>
+# Notes
+This package is intended to be used by Python version 3.8 and higher. There might be some wacky results for previous versions.
+
+<a name="depends"></a>
+# Dependencies
+
+[requests](https://github.com/kennethreitz/requests)
+- Used for all http requests in sleeper_wrapper
+
+[pytest](https://github.com/pytest-dev/pytest)
+- Used for all testing in sleeper_wrapper
+
+<a name="license"></a>
+# License
+This project is licensed under the terms of the MIT license.

sleeper_api_wrapper-1.2.1/pyproject.toml

@@ -0,0 +1,32 @@
+# pyproject.toml
+
+[tool.poetry]
+name = "sleeper-api-wrapper"
+packages = [ { include = "sleeper_wrapper" } ]
+version = "1.2.1"
+description = "A Python API wrapper for Sleeper Fantasy sports, as well as tools to simplify received data."
+authors = ["Dan Song, Ford Higgins <py-sleeper-api-wrapper-maintainers@googlegroups.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/dtsong/sleeper-api-wrapper"
+repository = "https://github.com/dtsong/sleeper-api-wrapper"
+documentation = "https://github.com/dtsong/sleeper-api-wrapper/tree/master/docs"
+keywords = ["fantasy football", "fantasy sports", "sports", "sleeper fantasy", "sleeper"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = "^2.22.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-mock = "*"
+tox = "^4.31.0"

{sleeper-api-wrapper-1.0.7 → sleeper_api_wrapper-1.2.1}/sleeper_wrapper/__init__.py

@@ -1,4 +1,4 @@
-from .league import League
+from .league import get_sport_state, League
 from .base_api import BaseApi
 from .user import User
 from .drafts import Drafts

{sleeper-api-wrapper-1.0.7 → sleeper_api_wrapper-1.2.1}/sleeper_wrapper/base_api.py

@@ -3,7 +3,7 @@ import json
 
 
 class BaseApi():
-	def _call(self, url):
+	def _call(self, url: str) -> dict:
 		result_json_string = requests.get(url);
 		try:
 			result_json_string.raise_for_status()
@@ -12,4 +12,4 @@ class BaseApi():
 			#return SleeperWrapperException("Empty value returned")
 
 		result = result_json_string.json()
-		return result;
+		return result

sleeper_api_wrapper-1.2.1/sleeper_wrapper/drafts.py

@@ -0,0 +1,33 @@
+from typing import Union
+
+from .base_api import BaseApi
+
+class Drafts(BaseApi):
+	"""The data associated with a given Sleeper draft.
+
+	Attributes:
+	  draft_id: Union[str, int]
+	    The Sleeper ID for the draft. May be provided as a string or int.
+	"""
+
+	def __init__(self, draft_id: Union[str, int]) -> None:
+		"""Initializes the instance based on draft ID.
+
+		Args:
+		  draft_id: Union[str, int]
+	        The Sleeper ID for the draft. May be provided as a string or int.
+		"""
+		self.draft_id = draft_id
+		self._base_url = "https://api.sleeper.app/v1/draft/{}".format(self.draft_id)
+
+	def get_specific_draft(self) -> dict:
+		"""Returns the draft's data."""
+		return self._call(self._base_url)
+
+	def get_all_picks(self) -> list:
+		"""Returns all the picks in the specified draft."""
+		return self._call("{}/{}".format(self._base_url,"picks"))
+
+	def get_traded_picks(self) -> list:
+		"""Returns all the traded picks in the specified draft."""
+		return self._call("{}/{}".format(self._base_url,"traded_picks"))

sleeper_api_wrapper-1.2.1/sleeper_wrapper/league.py

@@ -0,0 +1,322 @@
+from typing import Union
+
+from .base_api import BaseApi
+from .stats import Stats
+
+class League(BaseApi):
+	"""The data associated with the given Sleeper league.
+
+	Can retrieve data for the league such as matchups, transactions, brackets,
+	drafts, scoreboards, and more. Some of these are simple calls to the 
+	Sleeper API while others add on a layer of data transformation or include
+	multiple calls.
+
+	Attributes:
+	  league_id: Union[str, int]
+	    The Sleeper ID for the league. May be provided as a string or int.
+	"""
+
+	def __init__(self, league_id: Union[str, int]) -> None:
+		"""Initializes the instance based on league ID.
+
+		Args:
+		  league_id: Union[str, int]
+		    Defines the league ID for data retrieval.
+		"""
+		self.league_id = league_id
+		self._base_url = "https://api.sleeper.app/v1/league/{}".format(self.league_id)
+		self._league = self._call(self._base_url)
+
+	def get_league(self) -> dict:
+		"""Returns the league data."""
+		return self._league
+
+	def get_rosters(self) -> list:
+		"""Retrieves the league's rosters."""
+		return self._call("{}/{}".format(self._base_url,"rosters"))
+
+	def get_users(self) -> list:
+		"""Retrieves the league's users."""
+		return self._call("{}/{}".format(self._base_url,"users"))
+
+	def get_matchups(self, week: Union[str, int]) -> list:
+		"""Retrieves the league's matchups for the given week."""
+		return self._call("{}/{}/{}".format(self._base_url,"matchups", week))
+
+	def get_playoff_winners_bracket(self) -> list:
+		"""Retrieves the winner's playoff bracket."""
+		return self._call("{}/{}".format(self._base_url,"winners_bracket"))
+
+	def get_playoff_losers_bracket(self) -> list:
+		"""Retrieves the loser's playoff bracket."""
+		return self._call("{}/{}".format(self._base_url,"losers_bracket"))
+
+	def get_transactions(self, week: Union[str, int]) -> list:
+		"""Retrieves all of a league's transactions for the given week."""
+		return self._call("{}/{}/{}".format(self._base_url,"transactions", week))
+
+	def get_trades(self, week: Union[str, int]) -> list:
+		"""Retrieves the league's trades for the given week."""
+		transactions = self.get_transactions(week)
+		return [t for t in transactions if t["type"] == "trade"]
+
+	def get_waivers(self, week: Union[str, int]) -> list:
+		"""Retrieves the league's waiver transactions for the given week."""
+		transactions = self.get_transactions(week)
+		return [t for t in transactions if t["type"] == "waiver"]
+
+	def get_free_agents(self, week: Union[str, int]) -> list:
+		"""Retrieves the league's free agent transactions for the given week."""
+		transactions = self.get_transactions(week)
+		return [t for t in transactions if t["type"] == "free_agent"]
+
+	def get_traded_picks(self) -> list:
+		"""Retrieves the league's traded draft picks."""
+		return self._call("{}/{}".format(self._base_url,"traded_picks"))
+
+	def get_all_drafts(self) -> list:
+		"""Retrieves all of a league's drafts.
+
+		This will typically return only one draft. 
+		"""
+		return self._call("{}/{}".format(self._base_url, "drafts"))
+
+	def map_users_to_team_name(self, users: list) -> dict:
+		"""Creates a mapping from user ID to team name.
+		
+		Args:
+		  users: list
+		    List of user IDs for the league.
+
+		Returns:
+		  A dict mapping the user ID to team name for each user / team
+		  combination in the league.
+		"""
+		users_dict = {}
+		
+		# Maps the user_id to team name for easy lookup
+		for user in users:
+			try:
+				users_dict[user["user_id"]] = user["metadata"]["team_name"]
+			except:
+				users_dict[user["user_id"]] = user["display_name"]
+		return users_dict
+
+	def get_standings(self, rosters: list, users: list) -> dict:
+		"""Creates standings based on the team's wins, losses, and ties.
+
+		Args:
+		  rosters: 
+		    List of rosters for the league.
+		  users: list
+		    List of user IDs for the league.
+
+		Returns:
+		  List of tuples (team_name, wins, losses, points) sorted by wins in
+		  descending order.
+		"""
+		users_dict = self.map_users_to_team_name(users)
+
+		roster_standings_list = []
+		for roster in rosters:
+			wins = roster["settings"]["wins"]
+			points = roster["settings"]["fpts"]
+			name = roster["owner_id"]
+			losses = roster["settings"]["losses"]
+			if name is not None:
+				roster_tuple = (wins, losses, points, users_dict[name])
+			else:
+				roster_tuple = (wins, losses, points, None)
+			roster_standings_list.append(roster_tuple)
+
+		roster_standings_list.sort(reverse = 1)
+
+		clean_standings_list = []
+		for item in roster_standings_list:
+			clean_standings_list.append((item[3], str(item[0]), str(item[1]), str(item[2])))
+		
+		return clean_standings_list
+
+	def map_rosterid_to_ownerid(self, rosters: list) -> dict:
+		"""Creates a mapping from roster ID to owner ID.
+		
+		Args:
+		  rosters: list
+		    List of rosters for the league.
+
+		Returns:
+		  A dict mapping the roster ID to owner ID for each roster / owner
+		  combination in the league.
+		"""
+		result_dict = {}
+		for roster in rosters:
+			roster_id = roster["roster_id"]
+			owner_id = roster["owner_id"]
+			result_dict[roster_id] = owner_id
+
+		return result_dict
+
+	def get_scoreboards(self, rosters: list, matchups: list, users: list, score_type: str, season: Union[str, int], week: Union[str, int]) -> Union[dict, None]:
+		"""Returns the team names and scores from each matchup.
+
+		Uses the provided information about the league to create a scoreboard
+		for the given week. It pulls data from the rosters and users to find
+		the team name and then pulls the team's score. It does not currently
+		support leagues with custom scoring options and relies on the `Stats()`
+		class, which is no longer officially documented by Sleeper.
+
+		Args:
+		  rosters: list
+		    List of rosters for the league.
+		  matchups: list
+		    List of matchups for that week.
+		  users: list
+		    List of users for the league.
+		  score_type: str
+		    Scoring type for the league, eg "pts_std", "pts_ppr", or "pts_half_ppr"
+		  season: Union[str, int]
+		    The season to retrieve the scoreboards. May be provided as either a
+		    str or an int.
+		  week: Union[str, int]
+		    The week to retrieve the scoreboards. May be provided as either a
+		    str or an int.
+
+		Returns:
+		  A dict with the matchup ID as key and the corresponding teams' names
+		  and scores for that matchup.
+		"""
+		roster_id_dict = self.map_rosterid_to_ownerid(rosters)
+
+		if len(matchups) == 0:
+			return None
+
+		# Get the users to team name stats
+		users_dict = self.map_users_to_team_name(users)
+
+		# Map roster_id to points
+		scoreboards_dict = {}
+
+		for team in matchups:
+			matchup_id = team["matchup_id"]
+			current_roster_id = team["roster_id"]
+			owner_id = roster_id_dict[current_roster_id]
+			if owner_id is not None:
+				team_name = users_dict[owner_id]
+			else:
+				team_name = "Team name not available"
+
+			team_score = self.get_team_score(team["starters"], score_type, season, week)
+			if team_score is None:
+				team_score = 0
+
+			team_score_tuple = (team_name, team_score)
+			if matchup_id not in scoreboards_dict:
+				scoreboards_dict[matchup_id] = [team_score_tuple]
+			else:
+				scoreboards_dict[matchup_id].append(team_score_tuple)
+		return scoreboards_dict
+
+	def get_close_games(self, scoreboards: list, close_num: float) -> dict:
+		"""Returns scoreboard's games where final margin is beneath given number.
+
+		Args:
+		  scoreboards: list
+		    List of scoreboards, which can be retrieved with the
+		    `get_scoreboards()` method.
+		  close_num: float
+		    The final margin to use as a threshold for determining close games.
+
+		Returns:
+		  A dict of matchups qualifying as close.
+		"""
+		close_games_dict = {}
+		for key in scoreboards:
+			team_one_score = scoreboards[key][0][1]
+			team_two_score = scoreboards[key][1][1]
+
+			if abs(team_one_score-team_two_score) < close_num:
+				close_games_dict[key] = scoreboards[key]
+		return close_games_dict
+
+	def get_team_score(self, starters: list, score_type: str, season: Union[str, int], week: Union[str, int]) -> float:
+		"""Retrieves a team's scores for a week based on the score type.
+
+		Uses the provided list of starters to pull their stats for that week
+		with the given score type. It does not currently support leagues with
+		custom scoring options because it pulls the pre-calculated score based
+		on score type and does not calculate the score based on the league's
+		scoring setting. It relies on the `Stats()` class to do this, which is 
+		no longer officially documented by Sleeper.
+
+		Args:
+		  starters: list
+		    A list of starters for the team.
+		  score_type: str
+		    Scoring type for the league, eg "pts_std", "pts_ppr", or "pts_half_ppr"
+		  season: Union[str, int]
+		    The season to retrieve the scores. May be provided as either a str 
+		    or an int.
+		  week: Union[str, int]
+		    The week to retrieve the scores. May be provided as either a str or
+		    an int.
+
+		Returns:
+		  The total score as a float for the team in that week.
+		"""
+		total_score = 0
+		stats = Stats()
+		week_stats = stats.get_week_stats("regular", season, week)
+		for starter in starters:
+			if stats.get_player_week_stats(week_stats, starter) is not None:
+				try:
+					total_score += stats.get_player_week_stats(week_stats, starter)[score_type]
+				except KeyError:
+					total_score += 0
+
+		return total_score
+
+	def empty_roster_spots(self, user_id: Union[str, int]) -> Union[int, None]:
+		"""Returns the number of empty roster spots on a user's team.
+
+		Args:
+		  user_id: Union[str, int]
+		    The user's ID to check for empty roster spots.
+
+		Returns:
+		  The number of empty roster spots assuming the user was found. Otherwise
+		  returns `None`.
+		"""
+		# get size of maximum roster
+		max_roster_size = len(self._league["roster_positions"])
+
+		# finds roster of user, returns max size - size of user roster
+		rosters = self.get_rosters()
+		for roster in rosters:
+			if user_id == roster["owner_id"]:
+				return max_roster_size - len(roster["players"])
+
+		# returns None if user was not found
+		return None
+
+	
+	def get_league_name(self) -> str:
+		"""Returns name of league."""
+		return self._league["name"]
+
+	def get_negative_scores(self, week: Union[str, int]) -> None:
+		pass
+
+	def get_rosters_players(self) -> None:
+		pass
+
+
+def get_sport_state(sport: str = "nfl") -> dict:
+	"""
+	Returns info about the current state of the specified sport.
+
+	https://docs.sleeper.com/#get-nfl-state
+
+	Parameters:
+	  - sport: str: Options are "nfl", "nba", "lcs". Default "nfl".
+	"""
+	return BaseApi()._call("https://api.sleeper.app/v1/state/{}".format(sport))

sleeper_api_wrapper-1.2.1/sleeper_wrapper/players.py

@@ -0,0 +1,65 @@
+import logging
+
+from .base_api import BaseApi
+
+logger = logging.getLogger(__name__)
+
+class Players(BaseApi):
+	"""Retrieves player data from Sleeper."""
+	
+	def __init__(self):
+		pass
+
+	def get_all_players(self, sport: str = "nfl") -> dict:
+		"""Gets all players from Sleeper.
+
+		Retrieves data pertaining to each player in the Sleeper, including
+		positions, biographical data, height / weight, team, and more.
+
+		Args:
+		  sport: str
+			The sport to retrieve the players. Options include "nfl",
+			"nba", and "lcs".
+
+		Returns:
+		  A dict of dicts where the keys are the player IDs and the values
+		  contain all of the player information.
+		"""
+
+		message = """Please use this call sparingly, as it is intended only to be used once per day at most to keep your player IDs updated.
+
+		Save the information to your own servers, if possible.
+		"""
+		logger.info(message)
+		return self._call("https://api.sleeper.app/v1/players/nfl")
+
+	def get_trending_players(self, sport: str, add_drop: str = "add", hours: int = 24, limit: int = 25) -> list:
+		"""Gets trending players from Sleeper.
+
+		Retrieves the player ID and number of adds / drops for that player
+		during the specified lookback hours.
+
+		Args:
+		  sport: str
+			The sport to retrieve the players. Options include "nfl",
+			"nba", and "lcs".
+		  add_drop: str
+		    Type of action to retreive. Either "add" or "drop".
+		  hours: int
+		    The number of hours to look back.
+		  limit: int
+		    The number of players to retrieve.
+
+		Returns:
+		  A list of dicts containing the player ID and a count of the adds /
+		  drops.
+		"""
+
+
+		message = """If you use this trending data, please attribute Sleeper.
+
+		Copy the code below to embed it in your app:
+		<iframe src="https://sleeper.app/embed/players/nfl/trending/add?lookback_hours=24&limit=25" width="350" height="500" allowtransparency="true" frameborder="0"></iframe>
+		"""
+		logger.info(message)
+		return self._call("https://api.sleeper.app/v1/players/{}/trending/{}?lookback_hours={}&limit={}".format(sport, add_drop, hours, limit))