nhl-api-py 2.2.0__tar.gz → 2.2.1__tar.gz

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nhl-api-py
-Version: 2.2.0
+Version: 2.2.1
 Summary: NHL API.  For standings, team stats, outcomes, player information.  Contains each individual API endpoint as well as convience methods for easy data loading in Pandas or any ML applications.
 Home-page: https://github.com/coreyjs/nhl-api-py
 License: GPL-3.0-or-later

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/nhlpy/_version.py

@@ -1,3 +1,3 @@
 # Should this be driven by the main pyproject.toml file? yes, is it super convoluted? yes, can it wait? sure
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"

nhl_api_py-2.2.1/nhlpy/api/misc.py

@@ -0,0 +1,45 @@
+from typing import List
+
+from nhlpy.http_client import HttpClient
+
+
+class Misc:
+    def __init__(self, http_client: HttpClient) -> None:
+        self.client = http_client
+
+    def glossary(self) -> List[dict]:
+        """
+        Get the glossary for the NHL API.
+        :return: dict
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/glossary?sort=fullName").json()[
+            "data"
+        ]
+
+    def config(self) -> dict:
+        """
+        Seems to be various options for the filters?.
+        :return: dict
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/config").json()
+
+    def countries(self) -> List[dict]:
+        """
+        Get the countries for the NHL API.
+        :return: dict
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/country").json()["data"]
+
+    def season_specific_rules_and_info(self) -> List[dict]:
+        """
+        Get the season specific rules and info for the NHL API.
+        :return: dict
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/season").json()["data"]
+
+    def draft_year_and_rounds(self) -> List[dict]:
+        """
+        Get the draft year and rounds for the NHL API.  This only has "id", "draftYear" and "rounds count".
+        :return: dict
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/draft").json()["data"]

nhl_api_py-2.2.1/nhlpy/api/stats.py

@@ -0,0 +1,92 @@
+import urllib.parse
+import json
+from typing import List
+
+
+from nhlpy.http_client import HttpClient
+
+
+class Stats:
+    def __init__(self, http_client: HttpClient):
+        self.client = http_client
+
+    def club_stats_season(self, team_abbr: str) -> dict:
+        """
+        This seems to return gameTypes for every season the team was in existence.  Maybe its useful?
+        :param team_abbr: The 3 letter abbreviation of the team.  BUF, TOR, etc
+        :return: dict
+        """
+        return self.client.get(resource=f"club-stats-season/{team_abbr}").json()
+
+    def player_career_stats(self, player_id: int) -> dict:
+        """
+        This returns the career stats for a player as well as player information.
+
+        example: https://api-web.nhle.com/v1/player/8481528/landing
+
+        :param player_id: The player_id for the player you want the stats for.
+        :return: dict
+        """
+        return self.client.get(resource=f"player/{player_id}/landing").json()
+
+    def team_summary(
+        self,
+        start_season: str,
+        end_season: str,
+        game_type_id: int = 2,
+        is_game: bool = False,
+        is_aggregate: bool = False,
+        sort_expr: List[dict] = None,
+        start: int = 0,
+        limit: int = 50,
+        fact_cayenne_exp: str = "gamesPlayed>1",
+        default_cayenne_exp: str = None,
+    ) -> List[dict]:
+        """
+        Example: c.stats.team_summary(start_season="20202021", end_season="20212022", game_type_id=2)
+                 c.stats.team_summary(start_season="20202021", end_season="20212022")
+        :param start_season: Season id, in format 20202021, 20212022, etc, that will be the start of the range.  This
+            allows for searching over multiple season.  If you just want one season, set start_season and end_season.
+        :param end_season: Season id for the end range.
+        :param game_type_id: 2 is for regular season, 3 is for playoffs.  I think 1 is for preseason.
+        :param is_game: (dev notes: not sure what this is, its part of the api call)
+        :param is_aggregate:
+        :param sort_expr: A list of key/value pairs of properties and their sort direction.  For Example this defaults
+            to [
+            {"property":"points","direction":"DESC"},
+            {"property":"wins","direction":"DESC"},
+            {"property":"teamId","direction":"ASC"}
+            ]
+        :param start:
+        :param limit:
+        :param fact_cayenne_exp:  An expression used by apache cayenne.  This defaults to 'gamesPlayed>=1'.
+            You can experiment at will, this was taken from the nhl.com website.
+        :param default_cayenne_exp: Similar to above, I believe this provides a filter for the data returned.
+            This will look something like: "gameTypeId=2 and seasonId<=20232024 and seasonId>=20232024".
+
+            If this value is supplied, it will override a generated one, giving the user ability to experiment.
+        :return:
+        """
+        q_params = {
+            "isAggregate": is_aggregate,
+            "isGame": is_game,
+            "start": start,
+            "limit": limit,
+            "factCayenneExp": fact_cayenne_exp,
+        }
+
+        if not sort_expr:
+            sort_expr = [
+                {"property": "points", "direction": "DESC"},
+                {"property": "wins", "direction": "DESC"},
+                {"property": "teamId", "direction": "ASC"},
+            ]
+        q_params["sort"] = urllib.parse.quote(json.dumps(sort_expr))
+
+        if not default_cayenne_exp:
+            default_cayenne_exp = f"gameTypeId={game_type_id} and seasonId<={end_season} and seasonId>={start_season}"
+        q_params["cayenneExp"] = default_cayenne_exp
+
+        return self.client.get_by_url("https://api.nhle.com/stats/rest/en/team/summary", query_params=q_params).json()[
+            "data"
+        ]

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/nhlpy/api/teams.py

@@ -1,6 +1,6 @@
 import json
 import importlib.resources
-
+from warnings import warn
 from typing import List
 
 from nhlpy.http_client import HttpClient
@@ -12,12 +12,18 @@ class Teams:
         self.base_url = "https://api.nhle.com"
         self.api_ver = "/stats/rest/"
 
+    # todo deprecate this
     def team_stats_summary(self, lang="en") -> List[dict]:
         """
-        I really dont know what this endpoint does.  It returns a list of dicts with team stats.
+        I really don't know what this endpoint does.  It returns a list of dicts with team stats.
         :param lang: Language param.  'en' for English, 'fr' for French
         :return:
         """
+        warn(
+            "This endpoint will be deprecated in the future.  Use stats.team_summary() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.client.get_by_url(full_resource=f"{self.base_url}{self.api_ver}{lang}/team/summary").json()["data"]
 
     def teams_info(self) -> dict:
@@ -41,3 +47,10 @@ class Teams:
         :return:
         """
         return self.client.get(resource=f"roster/{team_abbr}/{season}").json()
+
+    def all_franchises(self) -> List[dict]:
+        """
+        Returns a list of all past and current NHL franchises.  This includes ones long forgotten.
+        :return:
+        """
+        return self.client.get_by_url(full_resource="https://api.nhle.com/stats/rest/en/franchise").json()["data"]

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/nhlpy/http_client.py

@@ -23,13 +23,14 @@ class HttpClient:
 
         return r
 
-    def get_by_url(self, full_resource: str) -> httpx.request:
+    def get_by_url(self, full_resource: str, query_params: dict = None) -> httpx.request:
         """
         Private method to make a get request to any HTTP resource.  This wraps the lib httpx functionality.
+        :param query_params:
         :param full_resource:  The full resource to get.
         :return:
         """
-        r: httpx.request = httpx.get(url=full_resource, follow_redirects=True)
+        r: httpx.request = httpx.get(url=full_resource, params=query_params, follow_redirects=True)
 
         if self._config.verbose:
             logging.info(f"API URL: {r.url}")

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/nhlpy/nhl_client.py

@@ -1,4 +1,4 @@
-from nhlpy.api import teams, standings, schedule, game_center
+from nhlpy.api import teams, standings, schedule, game_center, stats, misc
 from nhlpy.http_client import HttpClient
 from nhlpy.config import ClientConfig
 
@@ -24,3 +24,5 @@ class NHLClient:
         self.standings = standings.Standings(http_client=self._http_client)
         self.schedule = schedule.Schedule(http_client=self._http_client)
         self.game_center = game_center.GameCenter(http_client=self._http_client)
+        self.stats = stats.Stats(http_client=self._http_client)
+        self.misc = misc.Misc(http_client=self._http_client)

{nhl_api_py-2.2.0 → nhl_api_py-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "nhl-api-py"
-version = "2.2.0"
+version = "2.2.1"
 description = "NHL API.  For standings, team stats, outcomes, player information.  Contains each individual API endpoint as well as convience methods for easy data loading in Pandas or any ML applications."
 authors = ["Corey Schaf <cschaf@gmail.com>"]
 readme = "README.md"