brlib 0.3.0__tar.gz → 0.4.0__tar.gz

{brlib-0.3.0 → brlib-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brlib
-Version: 0.3.0
+Version: 0.4.0
 Summary: A library for collecting baseball statistics from Baseball Reference
 Project-URL: Documentation, https://github.com/john-bieren/brlib/wiki
 Project-URL: GitHub, https://github.com/john-bieren/brlib
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -34,9 +35,9 @@ Requires-Dist: pandas<3.0.0,>=2.2.0
 Requires-Dist: platformdirs<5.0.0,>=4.0.0
 Requires-Dist: tqdm<5.0.0,>=4.66.0
 Provides-Extra: dev
-Requires-Dist: black==26.1.0; extra == 'dev'
-Requires-Dist: isort==7.0.0; extra == 'dev'
-Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: black==26.3.0; extra == 'dev'
+Requires-Dist: isort==8.0.1; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # brlib
@@ -72,11 +73,9 @@ brlib can be installed using pip:
 pip install brlib
 ```
 
-or from this repo, in which case you'll want to install the development dependencies as well:
+or by cloning this repo, in which case you'll want to install the development dependencies as well:
 
 ```
-git clone https://github.com/john-bieren/brlib.git
-cd brlib
 pip install -e .[dev]
 ```
 

{brlib-0.3.0 → brlib-0.4.0}/README.md

@@ -31,11 +31,9 @@ brlib can be installed using pip:
 pip install brlib
 ```
 
-or from this repo, in which case you'll want to install the development dependencies as well:
+or by cloning this repo, in which case you'll want to install the development dependencies as well:
 
 ```
-git clone https://github.com/john-bieren/brlib.git
-cd brlib
 pip install -e .[dev]
 ```
 

{brlib-0.3.0 → brlib-0.4.0}/pyproject.toml

@@ -14,7 +14,7 @@ dependencies = [
     "lxml>=5.0.0,<7.0.0",
     "pandas>=2.2.0,<3.0.0",
     "platformdirs>=4.0.0,<5.0.0",
-    "tqdm>=4.66.0,<5.0.0"
+    "tqdm>=4.66.0,<5.0.0",
 ]
 readme = "README.md"
 license = "MIT"
@@ -33,6 +33,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
     "Topic :: Scientific/Engineering :: Information Analysis",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -41,9 +42,9 @@ keywords = ["baseball reference", "baseball", "baseball stats", "mlb", "mlb stat
 
 [project.optional-dependencies]
 dev = [
-    "black==26.1.0",
-    "isort==7.0.0",
-    "pytest>=7.0.0"
+    "black==26.3.0",
+    "isort==8.0.1",
+    "pytest>=7.0.0,<10.0.0",
 ]
 
 [project.urls]
@@ -67,3 +68,6 @@ target-version = ["py310", "py311", "py312", "py313", "py314"]
 profile = "black"
 line_length = 100
 known_first_party = ["brlib"]
+
+[tool.uv]
+package = true

brlib-0.4.0/scripts/refresh_tests.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+
+"""
+Refreshes the expected data for games, players, and teams to match their current outputs. This is
+meant to automate the process of adapting to stat adjustments and other changes on Baseball
+Reference. All changes should be reviewed to make sure that they accurately reflect changes to the
+site, so as not to introduce errors into the test suite.
+"""
+
+import json
+from pathlib import Path
+
+from tqdm import tqdm
+
+import brlib as br
+
+
+def main():
+    """Refreshes the expected data for games, players, and teams to match their current outputs."""
+    expected_dir = Path(__file__).parent.parent / "tests" / "expected"
+    br.options.add_no_hitters = False
+    br.options.update_team_names = False
+    br.options.update_venue_names = False
+
+    tqdm.write("Refreshing expected game data")
+    refresh_games(expected_dir / "games")
+
+    tqdm.write("Refreshing expected player data")
+    refresh_players(expected_dir / "players")
+
+    tqdm.write("Refreshing expected team data")
+    refresh_teams(expected_dir / "teams")
+
+
+def refresh_games(games_dir: Path) -> None:
+    """Refreshes expected data for games in `games_dir`."""
+    ids_dir = games_dir / "original"
+    total = sum(1 for entry in ids_dir.iterdir() if entry.is_dir())
+    for game_dir in tqdm(ids_dir.iterdir(), total=total, unit="game"):
+        if not game_dir.is_dir():
+            continue
+
+        # refresh original data
+        game = br.Game(game_dir.name)
+        original_dir = games_dir / "original" / game_dir.name
+        game.info.to_csv(original_dir / "info.csv", index=False)
+        game.batting.to_csv(original_dir / "batting.csv", index=False)
+        game.pitching.to_csv(original_dir / "pitching.csv", index=False)
+        game.fielding.to_csv(original_dir / "fielding.csv", index=False)
+        game.team_info.to_csv(original_dir / "team_info.csv", index=False)
+        game.ump_info.to_csv(original_dir / "ump_info.csv", index=False)
+        game.linescore.to_csv(original_dir / "linescore.csv", index=False)
+        (original_dir / "players.json").write_text(json.dumps(game.players))
+        (original_dir / "teams.json").write_text(json.dumps(game.teams))
+
+        # refresh updated data
+        game.add_no_hitters()
+        game.update_team_names()
+        game.update_venue_names()
+        updated_dir = games_dir / "updated" / game_dir.name
+        game.info.to_csv(updated_dir / "info.csv", index=False)
+        game.batting.to_csv(updated_dir / "batting.csv", index=False)
+        game.pitching.to_csv(updated_dir / "pitching.csv", index=False)
+        game.fielding.to_csv(updated_dir / "fielding.csv", index=False)
+        game.team_info.to_csv(updated_dir / "team_info.csv", index=False)
+        game.linescore.to_csv(updated_dir / "linescore.csv", index=False)
+
+
+def refresh_players(players_dir: Path) -> None:
+    """Refreshes expected data for players in `players_dir`."""
+    ids_dir = players_dir / "original"
+    total = sum(1 for entry in ids_dir.iterdir() if entry.is_dir())
+    for player_dir in tqdm(ids_dir.iterdir(), total=total, unit="player"):
+        if not player_dir.is_dir():
+            continue
+
+        # refresh original data
+        player = br.Player(player_dir.name)
+        original_dir = players_dir / "original" / player_dir.name
+        player.info.to_csv(original_dir / "info.csv", index=False)
+        player.bling.to_csv(original_dir / "bling.csv", index=False)
+        player.batting.to_csv(original_dir / "batting.csv", index=False)
+        player.pitching.to_csv(original_dir / "pitching.csv", index=False)
+        player.fielding.to_csv(original_dir / "fielding.csv", index=False)
+        (original_dir / "relatives.json").write_text(json.dumps(player.relatives))
+        (original_dir / "teams.json").write_text(json.dumps(player.teams))
+
+        # refresh updated data
+        player.add_no_hitters()
+        player.update_team_names()
+        updated_dir = players_dir / "updated" / player_dir.name
+        player.info.to_csv(updated_dir / "info.csv", index=False)
+        player.pitching.to_csv(updated_dir / "pitching.csv", index=False)
+
+
+def refresh_teams(teams_dir: Path) -> None:
+    """Refreshes expected data for the teams in `teams_dir`."""
+    ids_dir = teams_dir / "original"
+    total = sum(1 for entry in ids_dir.iterdir() if entry.is_dir())
+    for team_dir in tqdm(ids_dir.iterdir(), total=total, unit="team"):
+        if not team_dir.is_dir():
+            continue
+
+        # refresh original data
+        team = br.Team(team_dir.name)
+        original_dir = teams_dir / "original" / team_dir.name
+        team.info.to_csv(original_dir / "info.csv", index=False)
+        team.batting.to_csv(original_dir / "batting.csv", index=False)
+        team.pitching.to_csv(original_dir / "pitching.csv", index=False)
+        team.fielding.to_csv(original_dir / "fielding.csv", index=False)
+        (original_dir / "players.json").write_text(json.dumps(team.players))
+
+        # refresh updated data
+        team.add_no_hitters()
+        team.update_team_names()
+        team.update_venue_names()
+        updated_dir = teams_dir / "updated" / team_dir.name
+        team.info.to_csv(updated_dir / "info.csv", index=False)
+        team.batting.to_csv(updated_dir / "batting.csv", index=False)
+        team.pitching.to_csv(updated_dir / "pitching.csv", index=False)
+        team.fielding.to_csv(updated_dir / "fielding.csv", index=False)
+
+
+if __name__ == "__main__":
+    main()

brlib-0.3.0/scripts/wiki.py → brlib-0.4.0/scripts/refresh_wiki.py

@@ -8,6 +8,8 @@ presumably a clone of brlib's GitHub wiki repo. This is used to refresh the wiki
 import inspect
 from pathlib import Path
 
+from tqdm import tqdm
+
 import brlib
 
 
@@ -16,12 +18,13 @@ def main() -> None:
     Copies public member docstrings into Markdown files in an adjacent "wiki" directory,
     presumably a clone of brlib's GitHub wiki repo. This is used to refresh the wiki's contents.
     """
+    tqdm.write("Refreshing wiki files")
     wiki_dir = Path(__file__).parent.parent / "wiki"
     public_members = {
         name: mem for name, mem in inspect.getmembers(brlib) if not name.startswith("_")
     }
 
-    for member_name, member in public_members.items():
+    for member_name, member in tqdm(public_members.items(), unit="files"):
         if inspect.ismodule(member):
             continue
         file_path = wiki_dir / f"{member_name}.md"
@@ -40,7 +43,7 @@ def main() -> None:
 def clean_docstring(docstring: str) -> str:
     """Reformat whitespace in `docstring`."""
     # remove leading newline
-    if docstring[0] == "\n":
+    if docstring.startswith("\n"):
         docstring = docstring[1:]
     return docstring
 

{brlib-0.3.0 → brlib-0.4.0}/src/brlib/__init__.py

@@ -20,7 +20,7 @@ from .player_set import PlayerSet
 from .team import Team
 from .team_set import TeamSet
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "all_players",

{brlib-0.3.0 → brlib-0.4.0}/src/brlib/_helpers/abbreviations_manager.py

@@ -16,7 +16,8 @@ from .constants import (
     CURRENT_YEAR,
     CY_BASEBALL,
     FIRST_GAMES_YEAR,
-    SEASON_START_DATE,
+    SEASON_START_DAY,
+    SEASON_START_MONTH,
     TEAM_ALIASES,
 )
 from .requests_manager import req_man
@@ -26,19 +27,35 @@ from .singleton import Singleton
 class AbbreviationsManager(Singleton):
     """
     A wrapper for a DataFrame which contains information on all historical team and
-    franchise abbreviations used by Baseball Reference. Manages retrieval and caching of the data,
-    loads data on import of brlib. Has methods for working with these abbreviations.
+    franchise abbreviations used by Baseball Reference. Has methods for working with these
+    abbreviations. Manages retrieval and caching of the data, loads data on import of brlib.
     """
 
     def __init__(self) -> None:
         self._cache_file = CACHE_DIR / "abv_data_v1.csv"
+        self._populated = False
+
         self.df = pd.DataFrame()
 
+        self.populate()
+
+    def reset(self) -> None:
+        """Re-initializes `AbbreviationsManager`, resulting in `self.df` being reloaded."""
+        self.__init__()
+
+    def populate(self) -> None:
+        """Populates `self.df` from cache or the web if it is not already populated."""
+        if self._populated:
+            return
+
         if self._has_valid_cache:
             self._load()
         else:
             self._get()
 
+        assert not self.df.empty
+        self._populated = True
+
     @property
     def _has_valid_cache(self) -> bool:
         """
@@ -51,7 +68,7 @@ class AbbreviationsManager(Singleton):
         last_save = os.path.getmtime(self._cache_file)
         last_save_time = datetime.fromtimestamp(last_save).astimezone(CACHE_TIMEZONE)
 
-        cy_refresh_date = f"{CURRENT_YEAR}-{SEASON_START_DATE}"
+        cy_refresh_date = f"{CURRENT_YEAR}-{SEASON_START_MONTH}-{SEASON_START_DAY}"
         refresh_time = datetime.strptime(cy_refresh_date, "%Y-%m-%d").astimezone(CACHE_TIMEZONE)
 
         current_time = datetime.now(CACHE_TIMEZONE)
@@ -66,12 +83,11 @@ class AbbreviationsManager(Singleton):
         self.df.loc[self.df["Alias"].isna(), "Alias"] = ""
 
     def _get(self) -> None:
-        """Gets abbreviations data from Baseball Reference."""
+        """Gets abbreviations data from Baseball Reference, save to cache."""
         write("brlib: gathering team abbreviations")
         page = req_man.get_page("/about/team_IDs.shtml")
         self._gather_abbreviations(page)
         self.df.to_csv(self._cache_file, index=False)
-        self.df.rename({"Team ID": "Team", "Franchise ID": "Franchise"}, axis=1, inplace=True)
 
     def _gather_abbreviations(self, page: Response) -> None:
         """Scrapes team_IDs page and create `self.df`."""
@@ -92,7 +108,7 @@ class AbbreviationsManager(Singleton):
             if i == 0:
                 record.append("BML")
             else:
-                # noinspection PyTypeChecker
+                # noinspection PyTypeChecker TODO
                 record.append(record[0] in BML_FRANCHISE_ABVS)
             records.append(record)
 
@@ -204,7 +220,8 @@ class AbbreviationsManager(Singleton):
         team_row = self._find_correct_teams(abbreviation, season, era_adjustment=False)
         if not team_row.empty:
             alias = team_row["Alias"].values[0]
-            if alias != "":
+            # the Angels have used LAA in two stints, the first stint did not use an alias
+            if alias != "" and not (alias == "ANA" and season in range(1961, 1965)):
                 return alias
         return abbreviation
 
@@ -223,7 +240,8 @@ class AbbreviationsManager(Singleton):
         alias_rows = self.df.loc[self.df["Alias"] == abbreviation]
         years_mask = (alias_rows["First Year"] <= season) & (alias_rows["Last Year"] >= season)
         correct_row = alias_rows.loc[years_mask]
-        if correct_row.empty:
+        # the Angels have used LAA in two stints, the first stint did not use an alias
+        if correct_row.empty or (abbreviation == "ANA" and season in range(1961, 1965)):
             return abbreviation
         return correct_row["Team"].values[0]
 

{brlib-0.3.0 → brlib-0.4.0}/src/brlib/_helpers/constants.py

@@ -26,41 +26,36 @@ NO_POSTSEASON_YEARS = {1901, 1902, 1904, 1994}
 
 # the day after (that's when the stats are posted) the expected earliest/latest possible game dates
 # these dates allow for games that are two days earlier/later than the most extreme past examples
-SEASON_START_DATE = "03-17"
-SEASON_END_DATE = "11-08"
+SEASON_START_MONTH, SEASON_START_DAY = "03", "17"
+SEASON_END_MONTH, SEASON_END_DAY = "11", "08"
 
 # determine if there's been baseball played in the current year
-SEASON_START_MONTH, SEASON_START_DAY = [int(s) for s in SEASON_START_DATE.split("-", maxsplit=1)]
-if (
-    CURRENT_MONTH < SEASON_START_MONTH
-    or CURRENT_MONTH == SEASON_START_MONTH
-    and CURRENT_DAY < SEASON_START_DAY
-):
-    CY_BASEBALL = False
-else:
-    CY_BASEBALL = True
-
+CY_BASEBALL = (
+    CURRENT_MONTH > int(SEASON_START_MONTH)
+    or CURRENT_MONTH == int(SEASON_START_MONTH)
+    and CURRENT_DAY >= int(SEASON_START_DAY)
+)
 # best safe guess at earliest plausible ASG date
-if CURRENT_YEAR in NO_ASG_YEARS:
-    CY_ASG = False
-else:
-    CY_ASG = CURRENT_MONTH > 7 or CURRENT_MONTH == 7 and CURRENT_DAY > 7
+CY_ASG = CURRENT_YEAR not in NO_ASG_YEARS and (
+    CURRENT_MONTH > 7 or CURRENT_MONTH == 7 and CURRENT_DAY > 7
+)
 
 # selected so that hour 0 lines up with when BR should have posted the previous day's results
 CACHE_TIMEZONE = pytz.timezone("US/Aleutian")
 
 # pre-compiled regular expressions
-MULTI_TEAM_REGEX = re.compile("^[1-9]TM$")
-SEASON_REGEX = re.compile("^[1-2][0-9]{3}$")
-SEASON_RANGE_REGEX = re.compile("^[1-2][0-9]{3}-[1-2][0-9]{3}$")
-GAME_DATE_REGEX = re.compile("^[0-9]{4}[0-1][0-9][0-3][0-9]$")
-DOUBLEHEADER_REGEX = re.compile("^[0-3]$")
-DATE_REGEX = re.compile("^[0-1]?[0-9][0-3][0-9]$")
-DATE_RANGE_REGEX = re.compile("^[0-1]?[0-9][0-3][0-9]-[0-1]?[0-9][0-3][0-9]$")
-PLAYER_ID_REGEX = re.compile("^[a-z.'_]{3,7}[0-9]{2}$")
+MULTI_TEAM_REGEX = re.compile("[1-9]TM")
+SEASON_REGEX = re.compile("[0-9]{4}")
+SEASON_RANGE_REGEX = re.compile("[0-9]{4}-[0-9]{4}")
+DATE_REGEX = re.compile("[0-1]?[0-9][0-3][0-9]")
+DATE_RANGE_REGEX = re.compile("[0-1]?[0-9][0-3][0-9]-[0-1]?[0-9][0-3][0-9]")
+GAME_ID_REGEX = re.compile("[A-Z1-4]{2,3}[0-9]{9}", re.IGNORECASE)
+ASG_ID_REGEX = re.compile("[0-9]{4}-allstar-game(?P<doubleheader>-[12])?", re.IGNORECASE)
+PLAYER_ID_REGEX = re.compile("[a-z.'_]{3,7}[0-9]{2}")
+TEAM_ID_REGEX = re.compile("[A-Z1-4]{2,3}[0-9]{4}", re.IGNORECASE)
 SCHEDULE_TAG_REGEX = re.compile("^all_[0-9]")
 GAME_URL_REGEX = re.compile(
-    r"https://www\.baseball-reference\.com/boxes/[A-Z1-2]{2,3}/[A-Z1-2]{2,3}[0-9]{4}[0-1][0-9][0-3][0-9][0-3]\.shtml"
+    r"https://www\.baseball-reference\.com/boxes/[A-Z1-4]{2,3}/[A-Z1-4]{2,3}[0-9]{4}[0-1][0-9][0-3][0-9][0-3]\.shtml"
 )
 ALLSTAR_GAME_URL_REGEX = re.compile(
     r"https://www\.baseball-reference\.com/allstar/[1-2][0-9]{3}-allstar-game-?[1-2]?\.shtml"
@@ -72,12 +67,16 @@ TEAM_URL_REGEX = re.compile(
     r"https://www\.baseball-reference\.com/teams/[A-Z1-4]{2,3}/[1-2][0-9]{3}\.shtml"
 )
 SB_ATTEMPT_REGEX = re.compile(
-    r"^(?P<base>2nd base|3rd base|Home) (?:off|by) (?P<pitcher>\D+)/(?P<catcher>\D+)(?P<times>[0-9]?)$"
+    r"(?P<base>2nd base|3rd base|Home) (?:off|by) (?P<pitcher>\D+)/(?P<catcher>\D+)(?P<times>[0-9]?)"
 )
 PICKOFF_REGEX = re.compile(
-    r"^(?P<base>1st base|2nd base|3rd base|Home) by (?P<pitcher>\D+)(?P<times>[0-9]?)$"
+    r"(?P<base>1st base|2nd base|3rd base|Home) by (?P<pitcher>\D+)(?P<times>[0-9]?)"
 )
 
+# exponent used when calculating team Pythagorean W-L%
+# see https://www.sports-reference.com/blog/baseball-reference-faqs/
+PYTHAGOREAN_EXPONENT = 1.83
+
 # old names for teams (which have box scores) that didn't relocate
 TEAM_REPLACEMENTS = {
     "Boston Americans": "Boston Red Sox",
@@ -539,13 +538,8 @@ GAME_BATTING_COLS = (
     "2-Out RBI",
     "LOB",
     "RISP",
-    "Team",
     "Team ID",
-    "Opponent",
     "Opponent Team ID",
-    "Team Score",
-    "Result for Team",
-    "Home/Away",
     "Game ID",
 )
 
@@ -595,13 +589,8 @@ GAME_PITCHING_COLS = (
     "NH",
     "PG",
     "CNH",
-    "Team",
     "Team ID",
-    "Opponent",
     "Opponent Team ID",
-    "Team Score",
-    "Result for Team",
-    "Home/Away",
     "Game ID",
 )
 
@@ -628,13 +617,8 @@ GAME_FIELDING_COLS = (
     "1B Pick",
     "2B Pick",
     "3B Pick",
-    "Team",
     "Team ID",
-    "Opponent",
     "Opponent Team ID",
-    "Team Score",
-    "Result for Team",
-    "Home/Away",
     "Game ID",
 )
 
@@ -943,6 +927,7 @@ TEAM_INFO_COLS = (
     "Wins",
     "Losses",
     "Ties",
+    "W-L%",
     "Division Finish",
     "Division",
     "Postseason Finish",
@@ -960,6 +945,7 @@ TEAM_INFO_COLS = (
     "One-Year Pitching Park Factor",
     "Pythagorean Wins",
     "Pythagorean Losses",
+    "Pythagorean W-L%",
     "Runs",
     "Runs Allowed",
     "Team Gold Glove",