Implement standings api method (#203)

Closes #198

Author: jaebradley

basketball_reference_web_scraper/client.py

@@ -5,13 +5,37 @@
 from basketball_reference_web_scraper.output.columns import BOX_SCORE_COLUMN_NAMES, SCHEDULE_COLUMN_NAMES, \
     PLAYER_SEASON_TOTALS_COLUMN_NAMES, \
     PLAYER_ADVANCED_SEASON_TOTALS_COLUMN_NAMES, TEAM_BOX_SCORES_COLUMN_NAMES, PLAY_BY_PLAY_COLUMN_NAMES, \
-    PLAYER_SEASON_BOX_SCORE_COLUMN_NAMES, SEARCH_RESULTS_COLUMN_NAMES
+    PLAYER_SEASON_BOX_SCORE_COLUMN_NAMES, SEARCH_RESULTS_COLUMN_NAMES, STANDINGS_COLUMNS_NAMES
 from basketball_reference_web_scraper.output.fields import format_value, BasketballReferenceJSONEncoder
 from basketball_reference_web_scraper.output.service import OutputService
-from basketball_reference_web_scraper.output.writers import CSVWriter, JSONWriter, FileOptions, OutputOptions, SearchCSVWriter
+from basketball_reference_web_scraper.output.writers import CSVWriter, JSONWriter, FileOptions, OutputOptions, \
+    SearchCSVWriter
 from basketball_reference_web_scraper.parser_service import ParserService
 
 
+def standings(season_end_year, output_type=None, output_file_path=None, output_write_option=None,
+              json_options=None):
+    try:
+        http_service = HTTPService(parser=ParserService())
+        values = http_service.standings(season_end_year=season_end_year)
+    except requests.exceptions.HTTPError as http_error:
+        if http_error.response.status_code == requests.codes.not_found:
+            raise InvalidSeason(season_end_year=season_end_year)
+        else:
+            raise http_error
+    options = OutputOptions.of(
+        file_options=FileOptions.of(path=output_file_path, mode=output_write_option),
+        output_type=output_type,
+        json_options=json_options,
+        csv_options={"column_names": STANDINGS_COLUMNS_NAMES}
+    )
+    output_service = OutputService(
+        json_writer=JSONWriter(value_formatter=BasketballReferenceJSONEncoder),
+        csv_writer=CSVWriter(value_formatter=format_value)
+    )
+    return output_service.output(data=values, options=options)
+
+
 def player_box_scores(day, month, year, output_type=None, output_file_path=None, output_write_option=None,
                       json_options=None):
     try:

basketball_reference_web_scraper/data.py

@@ -85,6 +85,31 @@ class League(Enum):
     BASKETBALL_ASSOCIATION_OF_AMERICA = "BASKETBALL_ASSOCIATION_OF_AMERICA"
 
 
+class Conference(Enum):
+    EASTERN = "EASTERN"
+    WESTERN = "WESTERN"
+
+
+class Division(Enum):
+    ATLANTIC = "ATLANTIC"
+    CENTRAL = "CENTRAL"
+    MIDWEST = "MIDWEST"
+    NORTHWEST = "NORTHWEST"
+    PACIFIC = "PACIFIC"
+    SOUTHEAST = "SOUTHEAST"
+    SOUTHWEST = "SOUTHWEST"
+
+
+DIVISIONS_TO_CONFERENCES = {
+    Division.ATLANTIC: Conference.EASTERN,
+    Division.CENTRAL: Conference.EASTERN,
+    Division.SOUTHEAST: Conference.EASTERN,
+    Division.MIDWEST: Conference.WESTERN,
+    Division.PACIFIC: Conference.WESTERN,
+    Division.SOUTHWEST: Conference.WESTERN,
+}
+
+
 TEAM_ABBREVIATIONS_TO_TEAM = {
     'ATL': Team.ATLANTA_HAWKS,
     'BOS': Team.BOSTON_CELTICS,

basketball_reference_web_scraper/html.py

@@ -716,6 +716,7 @@ def rows(self):
             for row_html in self.html.xpath(self.rows_query)
         ]
 
+
 class PlayerSeasonBoxScoresRow(PlayerBoxScoreRow):
     def __init__(self, html):
         super().__init__(html)
@@ -1128,3 +1129,101 @@ def totals_table(self):
             return PlayerPageTotalsTable(html=totals_tables[0])
 
         return None
+
+
+class StandingsPage:
+    def __init__(self, html):
+        self.html = html
+
+    @property
+    def division_standings(self):
+        division_standings = self.html.xpath('.//div[@id="all_standings"]')
+
+        if len(division_standings) == 1:
+            return DivisionStandings(html=division_standings[0])
+
+        return None
+
+
+class DivisionStandings:
+    def __init__(self, html):
+        self.html = html
+
+    @property
+    def eastern_conference_table(self):
+        tables = self.html.xpath('.//table[@id="divs_standings_E"]')
+
+        if len(tables) == 1:
+            return ConferenceDivisionStandingsTable(html=tables[0])
+
+        return None
+
+    @property
+    def western_conference_table(self):
+        tables = self.html.xpath('.//table[@id="divs_standings_W"]')
+
+        if len(tables) == 1:
+            return ConferenceDivisionStandingsTable(html=tables[0])
+
+        return None
+
+
+class ConferenceDivisionStandingsTable:
+    def __init__(self, html):
+        self.html = html
+
+    @property
+    def rows(self):
+        return [
+            ConferenceDivisionStandingsRow(html=row_html)
+            for row_html in self.html.xpath('.//tbody/tr')
+        ]
+
+
+class ConferenceDivisionStandingsRow:
+    def __init__(self, html):
+        self.html = html
+
+    @property
+    def is_division_name_row(self):
+        return self.html.attrib['class'] == 'thead'
+
+    @property
+    def is_standings_row(self):
+        return self.html.attrib['class'] == 'full_table'
+
+    @property
+    def division_name(self):
+        cells = self.html.xpath('.//th')
+
+        if len(cells) == 1:
+            return cells[0].text_content()
+
+        return None
+
+    @property
+    def team_name(self):
+        cells = self.html.xpath('.//th[@data-stat="team_name"]')
+
+        if len(cells) == 1:
+            return cells[0].text_content()
+
+        return None
+
+    @property
+    def wins(self):
+        cells = self.html.xpath('.//td[@data-stat="wins"]')
+
+        if len(cells) == 1:
+            return cells[0].text_content()
+
+        return None
+
+    @property
+    def losses(self):
+        cells = self.html.xpath('.//td[@data-stat="losses"]')
+
+        if len(cells) == 1:
+            return cells[0].text_content()
+
+        return None

basketball_reference_web_scraper/http_service.py

@@ -5,7 +5,7 @@
 from basketball_reference_web_scraper.errors import InvalidDate, InvalidPlayerAndSeason
 from basketball_reference_web_scraper.html import DailyLeadersPage, PlayerSeasonBoxScoresPage, PlayerSeasonTotalTable, \
     PlayerAdvancedSeasonTotalsTable, PlayByPlayPage, SchedulePage, BoxScoresPage, DailyBoxScoresPage, SearchPage, \
-    PlayerPage
+    PlayerPage, StandingsPage
 
 
 class HTTPService:
@@ -14,6 +14,20 @@ class HTTPService:
     def __init__(self, parser):
         self.parser = parser
 
+    def standings(self, season_end_year):
+        url = '{BASE_URL}/leagues/NBA_{season_end_year}.html'.format(
+            BASE_URL=HTTPService.BASE_URL,
+            season_end_year=season_end_year,
+        )
+
+        response = requests.get(url=url, allow_redirects=False)
+
+        response.raise_for_status()
+
+        page = StandingsPage(html=html.fromstring(response.content))
+        return self.parser.parse_division_standings(standings=page.division_standings.eastern_conference_table.rows) + \
+               self.parser.parse_division_standings(standings=page.division_standings.western_conference_table.rows)
+
     def player_box_scores(self, day, month, year):
         url = '{BASE_URL}/friv/dailyleaders.cgi?month={month}&day={day}&year={year}'.format(
             BASE_URL=HTTPService.BASE_URL,
@@ -38,11 +52,11 @@ def regular_season_player_box_scores(self, player_identifier, season_end_year):
         # starting with first few characters of player's surname
         url = '{BASE_URL}/players/{player_surname_starting_character}/{player_identifier}/gamelog/{season_end_year}' \
             .format(
-                BASE_URL=HTTPService.BASE_URL,
-                player_surname_starting_character=player_identifier[0],
-                player_identifier=player_identifier,
-                season_end_year=season_end_year,
-            )
+            BASE_URL=HTTPService.BASE_URL,
+            player_surname_starting_character=player_identifier[0],
+            player_identifier=player_identifier,
+            season_end_year=season_end_year,
+        )
 
         response = requests.get(url=url, allow_redirects=False)
         response.raise_for_status()
@@ -59,11 +73,11 @@ def playoff_player_box_scores(self, player_identifier, season_end_year):
         # starting with first few characters of player's surname
         url = '{BASE_URL}/players/{player_surname_starting_character}/{player_identifier}/gamelog/{season_end_year}' \
             .format(
-                BASE_URL=HTTPService.BASE_URL,
-                player_surname_starting_character=player_identifier[0],
-                player_identifier=player_identifier,
-                season_end_year=season_end_year,
-            )
+            BASE_URL=HTTPService.BASE_URL,
+            player_surname_starting_character=player_identifier[0],
+            player_identifier=player_identifier,
+            season_end_year=season_end_year,
+        )
 
         response = requests.get(url=url, allow_redirects=False)
         response.raise_for_status()

basketball_reference_web_scraper/output/columns.py

@@ -128,3 +128,11 @@
     "identifier",
     "leagues",
 ]
+
+STANDINGS_COLUMNS_NAMES = [
+    "team",
+    "wins",
+    "losses",
+    "division",
+    "conference",
+]

basketball_reference_web_scraper/parser_service.py

@@ -1,11 +1,12 @@
 from basketball_reference_web_scraper.data import TEAM_ABBREVIATIONS_TO_TEAM, LOCATION_ABBREVIATIONS_TO_POSITION, OUTCOME_ABBREVIATIONS_TO_OUTCOME, TEAM_NAME_TO_TEAM, \
-    POSITION_ABBREVIATIONS_TO_POSITION, LEAGUE_ABBREVIATIONS_TO_LEAGUE
+    POSITION_ABBREVIATIONS_TO_POSITION, LEAGUE_ABBREVIATIONS_TO_LEAGUE, Division, Team, DIVISIONS_TO_CONFERENCES
 from basketball_reference_web_scraper.parsers import PositionAbbreviationParser, TeamAbbreviationParser, \
     PlayerSeasonTotalsParser, TeamTotalsParser, LocationAbbreviationParser, OutcomeAbbreviationParser, \
     SecondsPlayedParser, PlayerBoxScoresParser, PlayerAdvancedSeasonTotalsParser, PeriodDetailsParser, \
     PeriodTimestampParser, ScoresParser, PlayByPlaysParser, TeamNameParser, ScheduledStartTimeParser, \
     ScheduledGamesParser, PlayerBoxScoreOutcomeParser, PlayerSeasonBoxScoresParser, SearchResultNameParser, \
-    ResourceLocationParser, SearchResultsParser, LeagueAbbreviationParser, PlayerDataParser
+    ResourceLocationParser, SearchResultsParser, LeagueAbbreviationParser, PlayerDataParser, DivisionNameParser, \
+    TeamStandingsParser, ConferenceDivisionStandingsParser
 
 
 class ParserService:
@@ -76,6 +77,16 @@ def __init__(self):
             league_abbreviation_parser=self.league_abbreviation_parser,
         )
         self.team_totals_parser = TeamTotalsParser(team_abbreviation_parser=self.team_abbreviation_parser)
+        self.division_name_parser = DivisionNameParser(divisions=Division)
+        self.team_standings_parser = TeamStandingsParser(teams=Team)
+        self.conference_division_standings_parser = ConferenceDivisionStandingsParser(
+            division_name_parser=self.division_name_parser,
+            team_standings_parser=self.team_standings_parser,
+            divisions_to_conferences=DIVISIONS_TO_CONFERENCES,
+        )
+
+    def parse_division_standings(self, standings):
+        return self.conference_division_standings_parser.parse(division_standings=standings)
 
     def parse_play_by_plays(self, play_by_plays, away_team_name, home_team_name):
         return self.play_by_plays_parser.parse(

basketball_reference_web_scraper/parsers.py

@@ -258,6 +258,30 @@ def parse_resource_identifier(self, resource_location):
         return self.search(resource_location=resource_location).group(self.resource_identifier_regex_group_name)
 
 
+class TeamStandingsParser:
+    def __init__(self, teams):
+        self.teams = teams
+
+    def parse_team(self, formatted_name):
+        for team in self.teams:
+            if formatted_name.upper().startswith(team.value):
+                return team
+
+        return None
+
+
+class DivisionNameParser:
+    def __init__(self, divisions):
+        self.divisions = divisions
+
+    def parse_division(self, formatted_name):
+        for division in self.divisions:
+            if formatted_name.upper() == "{division} DIVISION".format(division=division.value):
+                return division
+
+        return None
+
+
 class ScheduledGamesParser:
     def __init__(self, start_time_parser, team_name_parser):
         self.start_time_parser = start_time_parser
@@ -552,3 +576,26 @@ def parse(self, player):
                 )
             )
         }
+
+
+class ConferenceDivisionStandingsParser:
+    def __init__(self, division_name_parser, team_standings_parser, divisions_to_conferences):
+        self.division_name_parser = division_name_parser
+        self.team_standings_parser = team_standings_parser
+        self.divisions_to_conferences = divisions_to_conferences
+
+    def parse(self, division_standings):
+        current_division = None
+        results = []
+        for standing in division_standings:
+            if standing.is_division_name_row:
+                current_division = self.division_name_parser.parse_division(formatted_name=standing.division_name)
+            else:
+                results.append({
+                    "team": self.team_standings_parser.parse_team(formatted_name=standing.team_name),
+                    "wins": str_to_int(standing.wins),
+                    "losses": str_to_int(standing.losses),
+                    "division": current_division,
+                    "conference": self.divisions_to_conferences.get(current_division),
+                })
+        return results

docs/api.md

@@ -551,3 +551,46 @@ or appended to the specified file path (or any of other the Python file mode opt
     )
     ```
 
+### Standings
+
+* [`repli.t` Examples](https://repl.it/@jaebradley/Standings#main.py)
+
+=== "Python Data Structures"
+    ```python
+    from basketball_reference_web_scraper import client
+
+    client.standings(season_end_year=2019)
+    ```
+    
+=== "JSON"
+    ```python
+    from basketball_reference_web_scraper import client
+    from basketball_reference_web_scraper.data import OutputType
+
+    client.standings(season_end_year=2019, output_type=OutputType.JSON)
+    ```
+
+=== "JSON to file"
+    ```python
+    from basketball_reference_web_scraper import client
+    from basketball_reference_web_scraper.data import OutputType
+
+    client.standings(
+        season_end_year=2019,
+        output_type=OutputType.JSON, 
+        output_file_path="./2019_standings.json"
+    )
+    ```
+       
+=== "CSV to file"
+    ```python
+    from basketball_reference_web_scraper import client
+    from basketball_reference_web_scraper.data import OutputType
+
+    client.standings(
+        season_end_year=2019,
+        output_type=OutputType.JSON, 
+        output_file_path="./2019_standings.csv"
+    )
+    ```
+