brlib 0.4.0__tar.gz → 0.5.0__tar.gz

brlib-0.5.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    versioning-strategy: auto
+
+    cooldown:
+      default-days: 2
+
+    allow:
+      # ensure that transitive dependencies are updated
+      - dependency-type: "all"
+
+    groups:
+      # group patch updates into one PR
+      patch-updates:
+        update-types:
+          - "patch"
+        patterns:
+          - "*"
+      # do the same with most minor updates
+      safe-minor-updates:
+        update-types:
+          - "minor"
+        # exclude packages that could ship breaking changes or noisy deprecations in minor updates
+        exclude-patterns:
+          - "beautifulsoup4"
+          - "curl-cffi"
+          - "pandas"

{brlib-0.4.0 → brlib-0.5.0}/.github/workflows/full-test.yml

@@ -1,7 +1,7 @@
 name: Full Tests
 
 on:
-  # to be run before releases
+  # to be run manually before releases
   workflow_dispatch:
 
 jobs:
@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.14"]
         resolution: ['highest']
         include:
           - os: ubuntu-latest
@@ -21,7 +21,7 @@ jobs:
             python-version: "3.10"
             resolution: 'lowest-direct'
           - os: macos-latest
-            # there's no 3.10 wheel for lxml on ARM64 macOS
+            # there's no lxml wheel for 3.10 on ARM64 macOS
             python-version: "3.11"
             resolution: 'lowest-direct'
 
@@ -41,7 +41,7 @@ jobs:
         run: uv venv
 
       - name: Install brlib
-        run: uv pip install --resolution ${{ matrix.resolution }} -e .[dev]
+        run: uv sync --resolution ${{ matrix.resolution }} --group dev
 
-      - name: Run pytest
-        run: uv run pytest
+      - name: Run pytest with coverage
+        run: uv run pytest --cov=. --cov-report=term-missing

{brlib-0.4.0 → brlib-0.5.0}/.github/workflows/test.yml

@@ -6,7 +6,7 @@ on:
       - '**'
   schedule:
     # run at 12 UTC, hopefully after BR's daily in-season updates
-    # run weekly, because anything more would be overkill
+    # run weekly (on Saturday), because anything more would be overkill
     - cron: '0 12 * * 6'
 
 jobs:
@@ -37,7 +37,7 @@ jobs:
         run: uv venv
 
       - name: Install brlib
-        run: uv pip install --resolution highest -e .[dev]
+        run: uv sync --resolution highest --group dev
 
       - name: Check import sorting with isort
         run: uv run isort --check-only .
@@ -45,5 +45,5 @@ jobs:
       - name: Check formatting with Black
         run: uv run black --check .
 
-      - name: Run pytest
-        run: uv run pytest
+      - name: Run pytest with coverage
+        run: uv run pytest --cov=. --cov-report=term-missing

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brlib
-Version: 0.4.0
+Version: 0.5.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
@@ -29,15 +29,11 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4<4.15.0,>=4.12.0
-Requires-Dist: curl-cffi<0.15.0,>=0.11.1
+Requires-Dist: curl-cffi<0.16.0,>=0.11.1
 Requires-Dist: lxml<7.0.0,>=5.0.0
 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.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
@@ -57,11 +53,12 @@ A library for collecting baseball statistics from
 ## Key Features
 
 * `Game`, `Player`, and `Team` classes give you easy access to all associated data in one place,
-  with attributes for stats tables, information, and more.
+  with attributes for stat tables and other information.
 * Aggregate these into `GameSet`, `PlayerSet`, or `TeamSet` classes, which have similar attributes,
   for easy analysis of larger samples.
-* Quickly search for games, players, and teams of interest, and gather their stats without violating
-  the [rate limit](https://www.sports-reference.com/429.html).
+* Easily search for games, players, and teams, and gather their stats.
+* Quickly collect data without violating the
+  [rate limit](https://www.sports-reference.com/429.html).
 
 Learn more by reading the documentation on the [wiki](https://github.com/john-bieren/brlib/wiki).
 
@@ -73,10 +70,16 @@ brlib can be installed using pip:
 pip install brlib
 ```
 
-or by cloning this repo, in which case you'll want to install the development dependencies as well:
+Or by cloning this repo:
 
 ```
-pip install -e .[dev]
+pip install -e .
+```
+
+If you've cloned the repo, you can also install the development dependencies:
+
+```
+pip install --group dev
 ```
 
 Once installed, you can import brlib into your Python scripts:

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

@@ -15,11 +15,12 @@ A library for collecting baseball statistics from
 ## Key Features
 
 * `Game`, `Player`, and `Team` classes give you easy access to all associated data in one place,
-  with attributes for stats tables, information, and more.
+  with attributes for stat tables and other information.
 * Aggregate these into `GameSet`, `PlayerSet`, or `TeamSet` classes, which have similar attributes,
   for easy analysis of larger samples.
-* Quickly search for games, players, and teams of interest, and gather their stats without violating
-  the [rate limit](https://www.sports-reference.com/429.html).
+* Easily search for games, players, and teams, and gather their stats.
+* Quickly collect data without violating the
+  [rate limit](https://www.sports-reference.com/429.html).
 
 Learn more by reading the documentation on the [wiki](https://github.com/john-bieren/brlib/wiki).
 
@@ -31,10 +32,16 @@ brlib can be installed using pip:
 pip install brlib
 ```
 
-or by cloning this repo, in which case you'll want to install the development dependencies as well:
+Or by cloning this repo:
 
 ```
-pip install -e .[dev]
+pip install -e .
+```
+
+If you've cloned the repo, you can also install the development dependencies:
+
+```
+pip install --group dev
 ```
 
 Once installed, you can import brlib into your Python scripts:

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

@@ -10,7 +10,7 @@ dynamic = ["version"]
 requires-python = ">=3.10"
 dependencies = [
     "beautifulsoup4>=4.12.0,<4.15.0",
-    "curl-cffi>=0.11.1,<0.15.0",
+    "curl-cffi>=0.11.1,<0.16.0",
     "lxml>=5.0.0,<7.0.0",
     "pandas>=2.2.0,<3.0.0",
     "platformdirs>=4.0.0,<5.0.0",
@@ -40,19 +40,20 @@ classifiers = [
 ]
 keywords = ["baseball reference", "baseball", "baseball stats", "mlb", "mlb stats"]
 
-[project.optional-dependencies]
-dev = [
-    "black==26.3.0",
-    "isort==8.0.1",
-    "pytest>=7.0.0,<10.0.0",
-]
-
 [project.urls]
 Documentation = "https://github.com/john-bieren/brlib/wiki"
 GitHub = "https://github.com/john-bieren/brlib"
 Issues = "https://github.com/john-bieren/brlib/issues"
 "Release Notes" = "https://github.com/john-bieren/brlib/releases"
 
+[dependency-groups]
+dev = [
+    "black==26.5.1",
+    "isort==8.0.1",
+    "pytest>=7.0.0,<10.0.0",
+    "pytest-cov>=4.0.0,<8.0.0",
+]
+
 [tool.hatch.version]
 path = "src/brlib/__init__.py"
 

{brlib-0.4.0 → brlib-0.5.0}/scripts/refresh_tests.py

@@ -3,8 +3,8 @@
 """
 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.
+Reference. To avoid introducing errors into the test suite, all changes should be manually reviewed
+to make sure that they accurately reflect changes to the site.
 """
 
 import json
@@ -13,9 +13,10 @@ from pathlib import Path
 from tqdm import tqdm
 
 import brlib as br
+from tests.case_ids import game_test_cases, player_test_cases, team_test_cases
 
 
-def main():
+def main() -> None:
     """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
@@ -34,15 +35,13 @@ def main():
 
 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
+    for game_id in tqdm(game_test_cases, unit="game"):
+        # locate, create target directories
+        (original_dir := games_dir / "original" / game_id).mkdir(exist_ok=True)
+        (updated_dir := games_dir / "updated" / game_id).mkdir(exist_ok=True)
 
         # refresh original data
-        game = br.Game(game_dir.name)
-        original_dir = games_dir / "original" / game_dir.name
+        game = br.Game(game_id)
         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)
@@ -57,7 +56,6 @@ def refresh_games(games_dir: Path) -> None:
         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)
@@ -68,42 +66,40 @@ def refresh_games(games_dir: Path) -> None:
 
 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
+    for player_id in tqdm(player_test_cases, unit="player"):
+        # locate, create target directories
+        (original_dir := players_dir / "original" / player_id).mkdir(exist_ok=True)
+        (updated_dir := players_dir / "updated" / player_id).mkdir(exist_ok=True)
 
         # refresh original data
-        player = br.Player(player_dir.name)
-        original_dir = players_dir / "original" / player_dir.name
+        player = br.Player(player_id)
         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)
+        player.salaries.to_csv(original_dir / "salaries.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)
+        player.salaries.to_csv(updated_dir / "salaries.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
+    teams_list = []
+    for team_id in tqdm(team_test_cases, unit="team"):
+        # locate, create target directories
+        (original_dir := teams_dir / "original" / team_id).mkdir(exist_ok=True)
+        (updated_dir := teams_dir / "updated" / team_id).mkdir(exist_ok=True)
 
         # refresh original data
-        team = br.Team(team_dir.name)
-        original_dir = teams_dir / "original" / team_dir.name
+        team = br.Team(team_id)
         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)
@@ -114,12 +110,15 @@ def refresh_teams(teams_dir: Path) -> None:
         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)
 
+        teams_list.append(team)
+    team_set = br.TeamSet(teams_list)
+    team_set.records.to_csv(teams_dir / "records.csv", index=False)
+
 
 if __name__ == "__main__":
     main()

brlib-0.5.0/scripts/refresh_wiki.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+
+"""
+Refreshes the contents of an adjacent "wiki" directory, presumably a clone of brlib's GitHub
+wiki repo. Copies all public member docstrings into corresponding Markdown files, and refreshes
+the column lists in DataFrames-Info.md. All changes should be manually reviewed.
+"""
+
+import inspect
+from pathlib import Path
+
+import brlib
+from brlib._helpers.constants import (
+    ALL_PLAYERS_COLS,
+    GAME_BATTING_COLS,
+    GAME_FIELDING_COLS,
+    GAME_INFO_COLS,
+    GAME_PITCHING_COLS,
+    GAME_TEAM_INFO_COLS,
+    GAME_UMP_INFO_COLS,
+    PLAYER_BATTING_COLS,
+    PLAYER_BLING_COLS,
+    PLAYER_FIELDING_COLS,
+    PLAYER_INFO_COLS,
+    PLAYER_PITCHING_COLS,
+    PLAYER_SALARIES_COLS,
+    RECORDS_COLS,
+    TEAM_BATTING_COLS,
+    TEAM_FIELDING_COLS,
+    TEAM_INFO_COLS,
+    TEAM_PITCHING_COLS,
+)
+from brlib._helpers.utils import str_between
+
+
+def main() -> None:
+    """
+    Refreshes the contents of an adjacent "wiki" directory, presumably a clone of brlib's GitHub
+    wiki repo. Copies all public member docstrings into corresponding Markdown files, and refreshes
+    the column lists in DataFrames-Info.md. All changes should be manually reviewed.
+    """
+    wiki_dir = Path(__file__).parent.parent / "wiki"
+
+    print("Refreshing public member wiki files")
+    refresh_files(wiki_dir)
+
+    print("Refreshing column lists in DataFrames-info.md")
+    refresh_cols(wiki_dir)
+
+    # update version in footer title
+    file_path = wiki_dir / "_Footer.md"
+    lines = file_path.read_text(encoding="UTF-8").splitlines()
+    lines[0] = f"# brlib v{brlib.__version__}"
+    file_path.write_text("\n".join(lines) + "\n", encoding="UTF-8")
+
+
+def refresh_files(wiki_dir: Path) -> None:
+    """Copies all public member docstrings into corresponding Markdown files."""
+    public_members = {
+        name: mem for name, mem in inspect.getmembers(brlib) if not name.startswith("_")
+    }
+    for member_name, member in public_members.items():
+        if inspect.ismodule(member):
+            continue
+        file_path = wiki_dir / f"{member_name}.md"
+        file_path.write_text(clean_docstring(member.__doc__), encoding="UTF-8")
+
+        # for classes or variables that are the instantiation of a singleton class
+        if not inspect.isfunction(member):
+            # create files for each of the class's public methods
+            methods = inspect.getmembers(member, predicate=is_function_or_method)
+            public_methods = {name: mem for name, mem in methods if not name.startswith("_")}
+            for method_name, method in public_methods.items():
+                file_path = wiki_dir / f"{member_name}.{method_name}.md"
+                file_path.write_text(clean_docstring(method.__doc__), encoding="UTF-8")
+
+
+def clean_docstring(docstring: str) -> str:
+    """Reformat whitespace in `docstring`."""
+    # remove leading newline
+    if docstring.startswith("\n"):
+        docstring = docstring[1:]
+    return docstring
+
+
+def is_function_or_method(member: object) -> bool:
+    """
+    Checks whether `inspect.isfunction` or `inspect.ismethod` is `True`. `isfunction` finds methods
+    if `member` is a class, and `ismethod` finds methods if `member` is a class instance.
+    """
+    return inspect.isfunction(member) or inspect.ismethod(member)
+
+
+def refresh_cols(wiki_dir: Path) -> None:
+    """Refreshes the column lists in DataFrames-Info.md."""
+    df_info_file = wiki_dir / "DataFrames-Info.md"
+    # the current column lists, in the same order as DataFrames-Info.md
+    cols_lists = [
+        ALL_PLAYERS_COLS,
+        RECORDS_COLS,
+        GAME_INFO_COLS,
+        GAME_BATTING_COLS,
+        GAME_PITCHING_COLS,
+        GAME_FIELDING_COLS,
+        GAME_TEAM_INFO_COLS,
+        GAME_UMP_INFO_COLS,
+        PLAYER_INFO_COLS,
+        PLAYER_BLING_COLS,
+        PLAYER_BATTING_COLS,
+        PLAYER_PITCHING_COLS,
+        PLAYER_FIELDING_COLS,
+        PLAYER_SALARIES_COLS,
+        TEAM_INFO_COLS,
+        TEAM_BATTING_COLS,
+        TEAM_PITCHING_COLS,
+        TEAM_FIELDING_COLS,
+    ]
+
+    # first pass: gather the line(s) for each column (including the name and any additional notes)
+    col_lines = {}
+    df_name = current_col_name = current_col_lines = ""
+    for line in df_info_file.read_text(encoding="UTF-8").splitlines():
+        # start of a new DataFrame
+        if line.startswith("###"):
+            # previous column's lines are complete and must be recorded
+            if current_col_lines != "":
+                col_lines[f"{df_name}::{current_col_name}"] = current_col_lines
+            df_name = line[4:].replace("`", "").split(" and", maxsplit=1)[0]
+            current_col_lines = ""
+        # start of a new column
+        elif line.startswith("* `"):
+            # previous column's lines are complete and must be recorded
+            if current_col_lines != "":
+                col_lines[f"{df_name}::{current_col_name}"] = current_col_lines
+            current_col_name = str_between(line, "`", "`")
+            current_col_lines = line
+        # additional note about a column
+        elif line.startswith(" "):
+            current_col_lines += f"\n{line}"
+
+    # second pass: refresh column lists (including info) using the current columns in constants.py
+    file_lines = []
+    df_cols_written = False
+    df_name = ""
+    i = -1
+    for line in df_info_file.read_text(encoding="UTF-8").splitlines():
+        # start of a new DataFrame
+        if line.startswith("###"):
+            file_lines.append(line)
+            df_name = line[4:].replace("`", "").split(" and", maxsplit=1)[0]
+            df_cols_written = False
+            i += 1
+        # start of column list
+        elif line.startswith("* `"):
+            if df_cols_written:
+                # all of a DataFrame's columns are written at once, so skip to the next DataFrame
+                continue
+            for col_name in cols_lists[i]:
+                col_info = col_lines.get(f"{df_name}::{col_name}", "")
+                if col_info != "":
+                    file_lines.append(col_info)
+                # if the column is new (or renamed, in which case info must be manually restored)
+                else:
+                    file_lines.append(f"* `{col_name}`")
+            df_cols_written = True
+        # skip column notes, as they have already been added
+        elif line.startswith("    *"):
+            continue
+        # pass all other lines through
+        else:
+            file_lines.append(line)
+    df_info_file.write_text("\n".join(file_lines) + "\n", encoding="UTF-8")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -19,8 +19,9 @@ from .player import Player
 from .player_set import PlayerSet
 from .team import Team
 from .team_set import TeamSet
+from .test_connection import test_connection
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "all_players",
@@ -37,4 +38,5 @@ __all__ = [
     "PlayerSet",
     "Team",
     "TeamSet",
+    "test_connection",
 ]