Merge pull request vuejs#5 from American-Soccer-Analysis/python-xg

Adding get_games function to Python package

Author: tyler-richardett

.github/workflows/R-check-release.yml

@@ -1,11 +1,15 @@
 # For help debugging build failures open an issue on the RStudio community with the 'github-actions' tag.
 # https://community.rstudio.com/new-topic?category=Package%20development&tags=github-actions
 name: R-CMD-check
-on: [push]
+on:
+  push:
+    paths:
+      - "R-package/"
+      - ".github/workflows/R-check-release.yml"
 
 jobs:
   R-CMD-check:
-    runs-on: macOS-latest
+    runs-on: macos-latest
     steps:
       - name: Check out repository code
         uses: actions/checkout@v2

.github/workflows/python-tests.yml

@@ -1,6 +1,10 @@
 name: Python tests
 
-on: [push]
+on:
+  push:
+    paths:
+      - "python-package/"
+      - ".github/workflows/python-tests.yml"
 
 jobs:
   python:
@@ -20,9 +24,6 @@ jobs:
           python -m pip install --upgrade pip
           cd python-package && pip install --editable .
           if [ -f requirements.dev.txt ]; then pip install -r requirements.dev.txt; fi
-      - name: Test with pytest
-        run: |
-          pytest python-package/tests/
       - name: Behave tests
         run: |
           cd python-package/tests

README.md

@@ -1,3 +1,8 @@
 # itscalledsoccer
 
-R and Python packages that wrap the ASA API
+R and Python packages that wrap the American Soccer Analysis API.
+
+See the READMEs in the respective package directories for usage information:
+
+- [Python](python-package/README.md)
+- [R](R-package/README.md)

python-package/README.md

@@ -13,6 +13,7 @@
     - [Stadia](#stadia)
     - [Managers](#managers)
     - [Referees](#referees)
+    - [Games](#games)
   - [Maintainers](#maintainers)
   - [Contributing](#contributing)
   - [License](#license)
@@ -41,6 +42,8 @@ asa = AmericanSoccerAnalysis()
 
 ### Referees
 
+### Games
+
 ## Maintainers
 
 ## Contributing

python-package/itscalledsoccer/client.py

@@ -1,5 +1,5 @@
 import requests
-from typing import Dict, List, Any, Union
+from typing import Dict, List, Union
 from cachecontrol import CacheControl
 from fuzzywuzzy import fuzz, process
 import pandas as pd
@@ -12,6 +12,7 @@ class AmericanSoccerAnalysis:
     API_VERSION = "v1"
     BASE_URL = f"https://app.americansocceranalysis.com/api/{API_VERSION}/"
     LEAGUES = ["nwsl", "mls", "uslc", "usl1", "nasl"]
+    MAX_API_LIMIT = 1000
 
     def __init__(self) -> None:
         """Class constructor"""
@@ -103,27 +104,28 @@ def _convert_names_to_ids(
                 ids.append(self._convert_name_to_id(type, n))
             return ids
 
-    def _check_leagues(self, leagues: Union[str, List[str]]):
+    def _check_leagues(self, leagues: Union[str, List[str]]) -> None:
         """Validates the leagues parameter
 
         :param leagues: league abbreviation or list of league abbreviations
         """
         if isinstance(leagues, list):
-            if not all(l in leagues for l in self.LEAGUES):
-                print(
-                    f"Leagues are limited only to the following options: {self.LEAGUES.join(',')}."
-                )
-                exit()
+            for l in leagues:
+                if l not in self.LEAGUES:
+                    print(
+                        f"Leagues are limited only to the following options: {self.LEAGUES}."
+                    )
+                    raise SystemExit(1)
         else:
             if leagues not in self.LEAGUES:
                 print(
-                    f"Leagues are limited only to the following options: {self.LEAGUES.join(',')}."
+                    f"Leagues are limited only to the following options: {self.LEAGUES}."
                 )
-                exit()
+                raise SystemExit(1)
 
     def _check_ids_names(
         self, ids: Union[str, List[str]], names: Union[str, List[str]]
-    ):
+    ) -> None:
         """Makes sure only ids or names are passed to a function and verifies
         they are the right data type.
 
@@ -132,17 +134,17 @@ def _check_ids_names(
         """
         if ids and names:
             print("Please specify only IDs or names, not both.")
-            exit()
+            raise SystemExit(1)
 
         if ids:
             if not isinstance(ids, str) and not isinstance(ids, list):
                 print("IDs must be passed as a string or list of strings.")
-                exit()
+                raise SystemExit(1)
 
         if names:
             if not isinstance(names, str) and not isinstance(names, list):
                 print("Names must be passed as a string or list of names.")
-                exit()
+                raise SystemExit(1)
 
     def _filter_entity(
         self,
@@ -151,7 +153,7 @@ def _filter_entity(
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Filters a dataframe based on the arguments given.
 
         :param entity_all: a dataframe containing the complete set of data
@@ -180,20 +182,53 @@ def _filter_entity(
         if converted_ids:
             entity = entity[entity[f"{entity_type}_id"].isin(converted_ids)]
 
-        return entity.to_json(orient="records")
+        return entity
+
+    def _execute_query(self, url: str, params: Dict[str,List[str]]) -> pd.DataFrame:
+        """Executes a query while handling the max number of responses from the API
+
+        :param url: the API endpoint to call
+        :param params: URL query strings
+        :returns: Dataframe
+        """
+        temp_response = self._single_request(url, params)
+        response = temp_response
+
+        if (isinstance(response, pd.DataFrame)):
+            offset = self.MAX_API_LIMIT
+
+            while(len(temp_response) == self.MAX_API_LIMIT):
+                params["offset"] = offset
+                temp_response = self._execute_query(url, params)
+                response = response.append(temp_response)
+                offset = offset + self.MAX_API_LIMIT
+        
+        return response
+
+    def _single_request(self, url: str, params: Dict[str, List[str]]) -> pd.DataFrame:
+        """Handles single call to the API
+
+        :param url: the API endpoint to call
+        :param params: URL query strings
+        :returns: Dataframe
+        """
+        response = self.session.get(url=url, params=params)
+        response.raise_for_status()
+        resp_df = pd.read_json(json.dumps(response.json()))
+        return resp_df
 
     def get_stadia(
         self,
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Get information associated with stadia
 
         :param leagues: league abbreviation or a list of league abbreviations
         :param ids: a single stadium id or a list of stadia ids (optional)
         :param names: a single stadium name or a list of stadia names (optional)
-        :returns: list of dictionaries
+        :returns: Dataframe
         """
         stadia = self._filter_entity(self.stadia, "stadium", leagues, ids, names)
         return stadia
@@ -203,13 +238,13 @@ def get_referees(
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Get information associated with referees
 
         :param leagues: league abbreviation or a list of league abbreviations
         :param ids: a single referee id or a list of referee ids (optional)
         :param names: a single referee name or a list of referee names (optional)
-        :returns: list of dictionaries
+        :returns: Dataframe
         """
         referees = self._filter_entity(self.referees, "referee", leagues, ids, names)
         return referees
@@ -219,13 +254,13 @@ def get_managers(
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Get information associated with managers
 
         :param leagues: league abbreviation or a list of league abbreviations
         :param ids: a single referee id or a list of referee ids (optional)
         :param names: a single referee name or a list of referee names (optional)
-        :returns: list of dictionaries
+        :returns: Dataframe
         """
         managers = self._filter_entity(self.managers, "manager", leagues, ids, names)
         return managers
@@ -235,13 +270,13 @@ def get_teams(
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Get information associated with teams
 
         :param leagues: league abbreviation or a list of league abbreviations
         :param ids: a single team id or a list of team ids (optional)
         :param names: a single team name or a list of team names (optional)
-        :returns: list of dictionaries
+        :returns: Dataframe
         """
         teams = self._filter_entity(self.teams, "team", leagues, ids, names)
         return teams
@@ -251,13 +286,63 @@ def get_players(
         leagues: Union[str, List[str]],
         ids: Union[str, List[str]] = None,
         names: Union[str, List[str]] = None,
-    ) -> List[Dict[str, Any]]:
+    ) -> pd.DataFrame:
         """Get information associated with players
 
         :param league: league abbreviation or a list of league abbreviations
         :param ids: a single player id or a list of player ids (optional)
         :param names: a single player name or a list of player names (optional)
-        :returns: list of dictionaries
+        :returns: Dataframe
         """
         players = self._filter_entity(self.players, "player", leagues, ids, names)
         return players
+
+    def get_games(
+        self,
+        leagues: Union[str, List[str]],
+        game_ids: Union[str, List[str]] = None,
+        team_ids: Union[str, List[str]] = None,
+        team_names: Union[str, List[str]] = None,
+        seasons: Union[str, List[str]] = None,
+        stages: Union[str, List[str]] = None,
+    ) -> pd.DataFrame:
+        """Get information related to games
+        
+        :param leagues: league abbreviation or a list of league abbreviations
+        :param game_ids: a single game id or a list of game ids
+        :param team_ids: a single team id or a list of team ids
+        :param team_names: a single team name or a list of team names
+        :param seasons: a single year of a league season or a list of years
+        :param stages: a single stage of competition in which a game took place or list of stages
+        :returns: Dataframe
+        """
+        self._check_leagues(leagues)
+        self._check_ids_names(team_ids, team_names)
+
+        query = {}
+
+        if game_ids:
+            query["game_id"] = game_ids
+        if team_names:
+            query["team_id"] = self._convert_names_to_ids("team",team_names)
+        if team_ids:
+            query["team_id"] = team_ids
+        if seasons:
+            query["season_name"] = seasons
+        if stages:
+            query["stage_name"] = stages
+
+        games = pd.DataFrame([])
+        if isinstance(leagues, str):
+            games_url = f"{self.base_url}{leagues}/games"
+            response = self._execute_query(games_url, query)
+
+            games = games.append(response)
+        elif isinstance(leagues, list):
+            for league in leagues:
+                games_url = f"{self.base_url}{league}/games"
+                response = self._execute_query(games_url, query)
+
+                games = games.append(response)
+
+        return games.sort_values(by=["date_time_utc"], ascending=False)

python-package/requirements.dev.txt

@@ -3,5 +3,5 @@ CacheControl==0.12.6
 fuzzywuzzy==0.18.0
 python-Levenshtein==0.12.2
 behave==1.2.6
-pytest==6.2.4
-pandas==1.3.1
+pandas==1.3.1
+black==21.11.b1

python-package/setup.py

@@ -1,12 +1,12 @@
-from distutils.core import setup
+from setuptools import setup
 
 with open("README.md", "r") as f:
     long_description = f.read()
 
 setup(
     name="itscalledsoccer",
     version="0.0.1",
-    description="Programmatically interact with the ASA API",
+    description="Programmatically interact with the American Soccer Analysis API",
     long_description=long_description,
     author="American Soccer Analysis",
     author_email="[email protected]",

python-package/tests/__init__.py

@@ -0,0 +1,16 @@
+Feature: Client
+
+	Scenario Outline: When I create a client, it has metadata
+		Given I have an ASA client
+		Then the API_VERSION should be "v1"
+		And the BASE_URL should be "https://app.americansocceranalysis.com/api/v1/"
+		And the MAX_API_LIMIT should be "1000"
+		And "<league>" should be in LEAGUES
+
+		Examples: Leagues
+			| league |
+			| nwsl   |
+			| mls    |
+			| uslc   |
+			| usl1   |
+			| nasl   |

python-package/tests/features/client.feature

@@ -0,0 +1,7 @@
+from itscalledsoccer.client import AmericanSoccerAnalysis
+from unittest.mock import patch, Mock
+
+
+@patch.object(AmericanSoccerAnalysis, "_get_all", return_value={})
+def before_all(context, mock_all_ids: Mock):
+    context.soccer = AmericanSoccerAnalysis()

python-package/tests/features/environment.py

@@ -0,0 +1,26 @@
+from behave import *
+
+
+@given("I have an ASA client")
+def step_impl(context):
+    pass
+
+
+@then(u'the API_VERSION should be "{value}"')
+def step_impl(context, value):
+    assert context.soccer.API_VERSION == value
+
+
+@then(u'the BASE_URL should be "{value}"')
+def step_impl(context, value):
+    assert context.soccer.BASE_URL == value
+
+@then(u'the MAX_API_LIMIT should be "{value}"')
+def step_impl(context, value):
+    assert context.soccer.MAX_API_LIMIT == int(value)
+
+
+@then(u'"{league}" should be in LEAGUES')
+def step_impl(context, league):
+    print(context.soccer.LEAGUES)
+    assert league in context.soccer.LEAGUES