brlib 0.5.0__tar.gz → 0.7.0__tar.gz

brlib-0.7.0/.github/workflows/full-test.yml

@@ -0,0 +1,46 @@
+name: Full Tests
+
+on:
+  # to be run manually before releases
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.14"]
+        resolution: ['highest']
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+            resolution: 'lowest-direct'
+          - os: windows-latest
+            python-version: "3.11"
+            resolution: 'lowest-direct'
+          - os: macos-latest
+            python-version: "3.11"
+            resolution: 'lowest-direct'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install brlib
+        run: uv sync --resolution ${{ matrix.resolution }} --group dev
+
+      - name: Run pytest with coverage
+        run: uv run --resolution ${{ matrix.resolution }} pytest --cov=. --cov-report=term-missing

brlib-0.7.0/.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - '**'
+  schedule:
+    # run at 12 UTC, hopefully after BR's daily in-season updates
+    # run weekly (on Saturday), because anything more would be overkill
+    - cron: '0 12 * * 6'
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.14"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.11"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install brlib
+        run: uv sync --resolution highest --group dev
+
+      - name: Check import sorting with isort
+        run: uv run isort --check-only .
+
+      - name: Check formatting with Black
+        run: uv run black --check .
+
+      - name: Run pytest with coverage
+        run: uv run pytest --cov=. --cov-report=term-missing

brlib-0.7.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: brlib
+Version: 0.7.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
+Project-URL: Issues, https://github.com/john-bieren/brlib/issues
+Project-URL: Release Notes, https://github.com/john-bieren/brlib/releases
+Author-email: John Bieren <jbieren64@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: baseball,baseball reference,baseball stats,mlb,mlb stats
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4<4.16.0,>=4.12.0
+Requires-Dist: curl-cffi<0.16.0,>=0.11.1
+Requires-Dist: lxml<7.0.0,>=5.0.0
+Requires-Dist: pandas<4.0.0,>=3.0.0
+Requires-Dist: platformdirs<5.0.0,>=4.0.0
+Requires-Dist: tqdm<5.0.0,>=4.66.0
+Description-Content-Type: text/markdown
+
+# brlib
+
+[![Tests](https://github.com/john-bieren/brlib/actions/workflows/test.yml/badge.svg)](https://github.com/john-bieren/brlib/actions/workflows/test.yml)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/brlib?label=PyPI&logo=pypi&logoColor=ffe873&color=0073b7)](https://pypi.org/project/brlib)
+[![Python Versions](https://img.shields.io/pypi/pyversions/brlib?label=Python%20Versions)](https://pypi.org/project/brlib)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+
+A library for collecting baseball statistics from
+[Baseball Reference](https://www.baseball-reference.com).
+
+> [!IMPORTANT]
+> brlib is in beta, breaking changes are possible until the release of version 1.
+
+## Key Features
+
+* `Game`, `Player`, and `Team` classes give you easy access to all associated data in one place,
+  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.
+* 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).
+
+## Install
+
+brlib can be installed using pip:
+
+```
+pip install brlib
+```
+
+Or by cloning this repo:
+
+```
+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:
+
+```python
+import brlib as br
+```
+
+## Data Use
+
+Since brlib gathers data from Baseball Reference, your use of this data is subject to their
+[data use policy](https://www.sports-reference.com/data_use.html).

brlib-0.7.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "brlib"
+description = "A library for collecting baseball statistics from Baseball Reference"
+authors = [{ name = "John Bieren", email = "jbieren64@gmail.com" }]
+dynamic = ["version"]
+requires-python = ">=3.11"
+dependencies = [
+    "beautifulsoup4>=4.12.0,<4.16.0",
+    "curl-cffi>=0.11.1,<0.16.0",
+    "lxml>=5.0.0,<7.0.0",
+    "pandas>=3.0.0,<4.0.0",
+    "platformdirs>=4.0.0,<5.0.0",
+    "tqdm>=4.66.0,<5.0.0",
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "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",
+]
+keywords = ["baseball reference", "baseball", "baseball stats", "mlb", "mlb stats"]
+
+[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.2.1,<10.0.0",
+    "pytest-cov>=4.1.0,<8.0.0",
+]
+
+[tool.hatch.version]
+path = "src/brlib/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311", "py312", "py313", "py314"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+known_first_party = ["brlib"]
+
+[tool.uv]
+package = true

brlib-0.7.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. 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
+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() -> 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
+    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`."""
+    games_list = []
+    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_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)
+        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()
+        game.info.to_csv(updated_dir / "info.csv", index=False)
+        game.pitching.to_csv(updated_dir / "pitching.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)
+
+        games_list.append(game)
+    game_set = br.GameSet(games_list)
+    game_set.records.to_csv(games_dir / "records.csv", index=False)
+
+
+def refresh_players(players_dir: Path) -> None:
+    """Refreshes expected data for players in `players_dir`."""
+    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_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()
+        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`."""
+    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_id)
+        team.info.to_csv(original_dir / "info.csv", index=False)
+        team.bling.to_csv(original_dir / "bling.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()
+        team.info.to_csv(updated_dir / "info.csv", index=False)
+        team.pitching.to_csv(updated_dir / "pitching.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.7.0/scripts/refresh_wiki.py

@@ -0,0 +1,189 @@
+#!/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_DTYPES,
+    GAME_BATTING_DTYPES,
+    GAME_FIELDING_DTYPES,
+    GAME_INFO_DTYPES,
+    GAME_PITCHING_DTYPES,
+    GAME_TEAM_INFO_DTYPES,
+    GAME_UMP_INFO_DTYPES,
+    PLAYER_BATTING_DTYPES,
+    PLAYER_BLING_DTYPES,
+    PLAYER_FIELDING_DTYPES,
+    PLAYER_INFO_DTYPES,
+    PLAYER_PITCHING_DTYPES,
+    PLAYER_SALARIES_DTYPES,
+    RECORDS_DTYPES,
+    TEAM_BATTING_DTYPES,
+    TEAM_BLING_DTYPES,
+    TEAM_FIELDING_DTYPES,
+    TEAM_INFO_DTYPES,
+    TEAM_PITCHING_DTYPES,
+)
+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
+    dtype_dicts = [
+        ALL_PLAYERS_DTYPES,
+        RECORDS_DTYPES,
+        GAME_INFO_DTYPES,
+        GAME_BATTING_DTYPES,
+        GAME_PITCHING_DTYPES,
+        GAME_FIELDING_DTYPES,
+        GAME_TEAM_INFO_DTYPES,
+        GAME_UMP_INFO_DTYPES,
+        PLAYER_INFO_DTYPES,
+        PLAYER_BLING_DTYPES,
+        PLAYER_BATTING_DTYPES,
+        PLAYER_PITCHING_DTYPES,
+        PLAYER_FIELDING_DTYPES,
+        PLAYER_SALARIES_DTYPES,
+        TEAM_INFO_DTYPES,
+        TEAM_BLING_DTYPES,
+        TEAM_BATTING_DTYPES,
+        TEAM_PITCHING_DTYPES,
+        TEAM_FIELDING_DTYPES,
+    ]
+
+    # 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.split(":", maxsplit=1)[0]  # exclude type; re-written later
+        # 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 = skip_df = 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
+            # there is no dtype dict for linescore, so just keep its existing lines
+            if skip_df := df_name == "Game.linescore":
+                continue
+            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
+            if skip_df:
+                file_lines.append(line)
+                continue
+            for col_name, col_dtype in dtype_dicts[i].items():
+                col_info = col_lines.get(f"{df_name}::{col_name}", "")
+                if col_info != "":
+                    # add dtype to line
+                    if "\n" in col_info:
+                        col_info = col_info.replace("`\n", f"`: `{col_dtype}`\n")
+                    else:
+                        col_info = f"{col_info}: `{col_dtype}`"
+                    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}`: `{col_dtype}`")
+            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.7.0/src/brlib/__init__.py

@@ -0,0 +1,42 @@
+"""
+A library for collecting baseball statistics from [Baseball
+Reference](https://www.baseball-reference.com).
+
+Documentation can be found on the [wiki](https://github.com/john-bieren/brlib/wiki).
+"""
+
+from .all_players import all_players
+from .find_asg import find_asg
+from .find_games import find_games
+from .find_teams import find_teams
+from .game import Game
+from .game_set import GameSet
+from .get_games import get_games
+from .get_players import get_players
+from .get_teams import get_teams
+from .options import options
+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.7.0"
+
+__all__ = [
+    "all_players",
+    "find_asg",
+    "find_games",
+    "find_teams",
+    "Game",
+    "GameSet",
+    "get_games",
+    "get_players",
+    "get_teams",
+    "options",
+    "Player",
+    "PlayerSet",
+    "Team",
+    "TeamSet",
+    "test_connection",
+]