baseball-api-wrapper 0.1.0__tar.gz

baseball_api_wrapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

baseball_api_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: baseball-api-wrapper
+Version: 0.1.0
+Summary: A Python wrapper for the official MLB Stats API (https://statsapi.mlb.com)
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# baseball-api-wrapper
+
+A Python wrapper for the official [MLB Stats API](https://statsapi.mlb.com).
+
+## Installation
+
+Clone the repo and install in editable mode so changes to the source are reflected immediately:
+
+```bash
+git clone <your-repo-url>
+cd baseball-api-wrapper
+pip install -e ".[dev]"   # includes pytest and test dependencies
+```
+
+For use in another project without dev tools:
+
+```bash
+pip install -e /path/to/baseball-api-wrapper
+```
+
+## Quick Start
+
+```python
+from baseball_api_wrapper import get_teams, get_roster
+
+# List all MLB teams for the 2024 season
+teams = get_teams(2024)
+for team in teams:
+    print(team["id"], team["name"])
+
+# Get the active roster for the New York Yankees (teamId=147)
+roster = get_roster(147, season=2024)
+for player in roster:
+    print(player["person"]["fullName"], player["position"]["name"])
+```
+
+## Using the Low-Level Client
+
+For endpoints not yet covered by a module, use `MLBStatsClient` directly:
+
+```python
+from baseball_api_wrapper import MLBStatsClient
+
+with MLBStatsClient() as client:
+    data = client.get("/api/v1/standings", params={"leagueId": 103, "season": 2024})
+    print(data)
+```
+
+## Project Structure
+
+```
+baseball_api_wrapper/          # Installable package
+    __init__.py        # Public API surface
+    client.py          # Low-level HTTP client (MLBStatsClient, MLBStatsAPIError)
+    modules/
+        teams.py       # get_teams()
+        roster.py      # get_roster()
+tests/                 # pytest test suite
+    test_teams.py
+    test_roster.py
+pyproject.toml         # Build & dependency config
+```
+
+## Running Tests
+
+```bash
+pytest                        # Run all tests
+pytest --cov=baseball_api_wrapper     # Run with coverage report
+```
+
+## Error Handling
+
+Network or API errors raise `MLBStatsAPIError`:
+
+```python
+from baseball_api_wrapper import MLBStatsClient, MLBStatsAPIError
+
+try:
+    with MLBStatsClient() as client:
+        data = client.get("/api/v1/teams/99999")  # Non-existent team
+except MLBStatsAPIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

baseball_api_wrapper-0.1.0/README.md

@@ -0,0 +1,87 @@
+# baseball-api-wrapper
+
+A Python wrapper for the official [MLB Stats API](https://statsapi.mlb.com).
+
+## Installation
+
+Clone the repo and install in editable mode so changes to the source are reflected immediately:
+
+```bash
+git clone <your-repo-url>
+cd baseball-api-wrapper
+pip install -e ".[dev]"   # includes pytest and test dependencies
+```
+
+For use in another project without dev tools:
+
+```bash
+pip install -e /path/to/baseball-api-wrapper
+```
+
+## Quick Start
+
+```python
+from baseball_api_wrapper import get_teams, get_roster
+
+# List all MLB teams for the 2024 season
+teams = get_teams(2024)
+for team in teams:
+    print(team["id"], team["name"])
+
+# Get the active roster for the New York Yankees (teamId=147)
+roster = get_roster(147, season=2024)
+for player in roster:
+    print(player["person"]["fullName"], player["position"]["name"])
+```
+
+## Using the Low-Level Client
+
+For endpoints not yet covered by a module, use `MLBStatsClient` directly:
+
+```python
+from baseball_api_wrapper import MLBStatsClient
+
+with MLBStatsClient() as client:
+    data = client.get("/api/v1/standings", params={"leagueId": 103, "season": 2024})
+    print(data)
+```
+
+## Project Structure
+
+```
+baseball_api_wrapper/          # Installable package
+    __init__.py        # Public API surface
+    client.py          # Low-level HTTP client (MLBStatsClient, MLBStatsAPIError)
+    modules/
+        teams.py       # get_teams()
+        roster.py      # get_roster()
+tests/                 # pytest test suite
+    test_teams.py
+    test_roster.py
+pyproject.toml         # Build & dependency config
+```
+
+## Running Tests
+
+```bash
+pytest                        # Run all tests
+pytest --cov=baseball_api_wrapper     # Run with coverage report
+```
+
+## Error Handling
+
+Network or API errors raise `MLBStatsAPIError`:
+
+```python
+from baseball_api_wrapper import MLBStatsClient, MLBStatsAPIError
+
+try:
+    with MLBStatsClient() as client:
+        data = client.get("/api/v1/teams/99999")  # Non-existent team
+except MLBStatsAPIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

baseball_api_wrapper-0.1.0/baseball_api_wrapper/__init__.py

@@ -0,0 +1,32 @@
+"""
+baseball_api_wrapper
+====================
+A Python wrapper for the official MLB Stats API (https://statsapi.mlb.com).
+
+Quick start::
+
+    from baseball_api_wrapper import get_teams
+
+    teams = get_teams(2024)
+    for team in teams:
+        print(team["id"], team["name"])
+"""
+
+from .client import MLBStatsAPIError, MLBStatsClient
+from .modules.teams import get_teams
+from .modules.roster import get_roster
+from .modules.players import get_player_info, get_player_stats, get_player_career_splits
+from .modules.games import get_schedule, get_boxscore, get_game_by_pk
+
+__all__ = [
+    "MLBStatsClient",
+    "MLBStatsAPIError",
+    "get_teams",
+    "get_roster",
+    "get_player_info",
+    "get_player_stats",
+    "get_player_career_splits",
+    "get_schedule",
+    "get_boxscore",
+    "get_game_by_pk",
+]

baseball_api_wrapper-0.1.0/baseball_api_wrapper/client.py

@@ -0,0 +1,86 @@
+"""
+MLB Stats API Client
+====================
+A Python wrapper for the official MLB Stats API (https://statsapi.mlb.com).
+
+This module provides a low-level HTTP client that handles request construction,
+error handling, and response parsing for the MLB Stats API.
+"""
+
+import requests
+from typing import Any, Dict, Optional
+
+
+class MLBStatsAPIError(Exception):
+    """Raised when the MLB Stats API returns an error response."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"MLB Stats API error {status_code}: {message}")
+
+
+class MLBStatsClient:
+    """
+    Low-level HTTP client for the MLB Stats API.
+
+    Handles base URL configuration, session management, and common
+    request/response logic. Higher-level endpoint wrappers build on
+    top of this class.
+
+    Args:
+        base_url: The root URL of the Stats API. Defaults to the
+                  official production endpoint.
+        timeout:  Request timeout in seconds. Defaults to 10.
+
+    Example::
+
+        client = MLBStatsClient()
+        data = client.get("/api/v1/teams", params={"season": "2024", "sportId": 1})
+    """
+
+    DEFAULT_BASE_URL = "https://statsapi.mlb.com"
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 10,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({"Accept": "application/json"})
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Perform a GET request against the Stats API.
+
+        Args:
+            path:   API path, e.g. ``"/api/v1/teams"``.
+            params: Optional dictionary of query-string parameters.
+
+        Returns:
+            Parsed JSON response as a Python dictionary.
+
+        Raises:
+            MLBStatsAPIError: If the server returns a non-2xx status code.
+            requests.RequestException: On network-level failures.
+        """
+        url = f"{self.base_url}{path}"
+        response = self._session.get(url, params=params, timeout=self.timeout)
+
+        if not response.ok:
+            raise MLBStatsAPIError(response.status_code, response.text)
+
+        return response.json()
+
+    def close(self):
+        """Close the underlying HTTP session, freeing connection-pool resources."""
+        self._session.close()
+
+    # Support use as a context manager
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()

baseball_api_wrapper-0.1.0/baseball_api_wrapper/modules/games.py

@@ -0,0 +1,147 @@
+"""
+Games
+=====
+Functions for retrieving MLB game schedule and score data from the Stats API.
+
+The primary entry point is :func:`get_schedule`, which returns games for a
+given date.  By default it fetches regular-season MLB games only.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from ..client import MLBStatsClient
+
+_SCHEDULE_PATH = "/api/v1/schedule"
+_BOXSCORE_PATH = "/api/v1/game/{game_pk}/boxscore"
+
+MLB_SPORT_ID = 1
+
+
+def get_schedule(
+    date: str,
+    sport_id: int = MLB_SPORT_ID,
+    game_type: str = "R",
+    client: Optional[MLBStatsClient] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Return all games scheduled for the given date.
+
+    Args:
+        date:
+            The date to query in ``YYYY-MM-DD`` format, e.g. ``"2024-04-01"``.
+        sport_id:
+            Top-level sport identifier.  Use ``1`` (default) for MLB.
+        game_type:
+            Game type filter.  ``"R"`` (default) returns regular-season games.
+            Pass ``"S"`` for spring training, ``"P"`` for playoffs, or ``"A"``
+            for the All-Star game.
+        client:
+            Optional pre-configured :class:`~baseball_api_wrapper.client.MLBStatsClient`.
+            If omitted, a default client is created for this single call.
+
+    Returns:
+        A list of game dictionaries as returned by the MLB Stats API
+        ``/api/v1/schedule`` endpoint.  Returns an empty list when no games
+        are scheduled for the requested date.
+
+    Raises:
+        baseball_api_wrapper.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code.
+        requests.RequestException:
+            On network-level failures.
+    """
+    params: Dict[str, Any] = {
+        "sportId": sport_id,
+        "date": date,
+        "gameType": game_type,
+    }
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(_SCHEDULE_PATH, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    dates = data.get("dates", [])
+    if not dates:
+        return []
+    return dates[0].get("games", [])
+
+
+def get_game_by_pk(
+    game_pk: int,
+    client: Optional[MLBStatsClient] = None,
+) -> Dict[str, Any]:
+    """
+    Return the schedule entry for a single game by its ``gamePk``.
+
+    Useful for fetching lightweight metadata (status, date, teams) without
+    the full boxscore payload.
+
+    Args:
+        game_pk: The unique game identifier.
+        client: Optional pre-configured :class:`~baseball_api_wrapper.client.MLBStatsClient`.
+
+    Returns:
+        The game dictionary for the requested ``gamePk``, or an empty dict
+        if the game is not found.
+    """
+    params: Dict[str, Any] = {"gamePks": game_pk, "sportId": MLB_SPORT_ID}
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(_SCHEDULE_PATH, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    dates = data.get("dates", [])
+    if not dates:
+        return {}
+    games = dates[0].get("games", [])
+    return games[0] if games else {}
+
+
+def get_boxscore(
+    game_pk: int,
+    client: Optional[MLBStatsClient] = None,
+) -> Dict[str, Any]:
+    """
+    Return the box score for a single game.
+
+    Args:
+        game_pk:
+            The unique game identifier (``gamePk``) returned by
+            :func:`get_schedule`.
+        client:
+            Optional pre-configured :class:`~baseball_api_wrapper.client.MLBStatsClient`.
+            If omitted, a default client is created for this single call.
+
+    Returns:
+        The raw box score dictionary as returned by the MLB Stats API
+        ``/api/v1/game/{gamePk}/boxscore`` endpoint.
+
+    Raises:
+        baseball_api_wrapper.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code.
+        requests.RequestException:
+            On network-level failures.
+    """
+    path = _BOXSCORE_PATH.format(game_pk=game_pk)
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        return client.get(path)
+    finally:
+        if _owns_client:
+            client.close()

baseball_api_wrapper-0.1.0/baseball_api_wrapper/modules/players.py

@@ -0,0 +1,178 @@
+"""
+Players
+=======
+Functions for retrieving player information and statistics from the MLB Stats API.
+
+The two primary entry points are:
+
+* :func:`get_player_info`  – Basic biographical data for a player.
+* :func:`get_player_stats` – Season statistics for a player, split by group
+                             (``"hitting"`` or ``"pitching"``).
+"""
+
+from typing import Any, Dict, List, Optional
+
+from ..client import MLBStatsClient
+
+_PLAYER_INFO_PATH = "/api/v1/people/{player_id}"
+_PLAYER_STATS_PATH = "/api/v1/people/{player_id}/stats"
+
+
+def get_player_career_splits(
+    player_id: int,
+    group: str = "hitting",
+    client: Optional[MLBStatsClient] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Return year-by-year career splits for a player.
+
+    Each element in the returned list is a split dict with at minimum:
+    * ``season`` – The season year as a string, e.g. ``"2024"``.
+    * ``stat``   – Dict of raw stat fields for that season.
+
+    Args:
+        player_id: The player's unique MLB identifier.
+        group:     ``"hitting"`` or ``"pitching"``. Defaults to ``"hitting"``.
+        client:    Optional pre-configured MLBStatsClient.
+
+    Returns:
+        A list of split dicts, one per season, or an empty list if none found.
+    """
+    path = _PLAYER_STATS_PATH.format(player_id=player_id)
+    params: Dict[str, Any] = {"stats": "yearByYear", "group": group, "hydrate": "team"}
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(path, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    for stat_block in data.get("stats", []):
+        splits = stat_block.get("splits", [])
+        if splits:
+            return splits
+
+    return []
+
+
+def get_player_info(
+    player_id: int,
+    client: Optional[MLBStatsClient] = None,
+) -> Dict[str, Any]:
+    """
+    Return biographical information for a single player.
+
+    The returned dict contains at minimum:
+
+    * ``id``               – Player's unique MLB identifier.
+    * ``fullName``         – Full display name.
+    * ``primaryPosition``  – Nested dict with ``code``, ``name``, ``type``,
+                             ``abbreviation``.
+    * ``active``           – Boolean indicating whether the player is active.
+
+    Args:
+        player_id:
+            The player's unique MLB identifier, e.g. ``660271`` for Juan Soto.
+        client:
+            Optional pre-configured :class:`~baseball_api_wrapper.client.MLBStatsClient`.
+            If omitted, a default client is created for the single call.
+
+    Returns:
+        A dict of player attributes as returned by the MLB Stats API.
+
+    Raises:
+        mlb_statsapi.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code.
+        requests.RequestException:
+            On network-level failures.
+        KeyError:
+            If the response contains no ``people`` entry for the given ID.
+    """
+    path = _PLAYER_INFO_PATH.format(player_id=player_id)
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(path)
+    finally:
+        if _owns_client:
+            client.close()
+
+    people: List[Dict[str, Any]] = data.get("people", [])
+    if not people:
+        raise KeyError(f"No player found with id {player_id}")
+
+    return people[0]
+
+
+def get_player_stats(
+    player_id: int,
+    season: int | str,
+    group: str = "hitting",
+    client: Optional[MLBStatsClient] = None,
+) -> Optional[Dict[str, Any]]:
+    """
+    Return season statistics for a player for a specific stat group.
+
+    Args:
+        player_id:
+            The player's unique MLB identifier.
+        season:
+            The MLB season year, e.g. ``2024`` or ``"2024"``.
+        group:
+            The stat group to retrieve: ``"hitting"`` or ``"pitching"``.
+            Defaults to ``"hitting"``.
+        client:
+            Optional pre-configured :class:`~baseball_api_wrapper.client.MLBStatsClient`.
+            If omitted, a default client is created for the single call.
+
+    Returns:
+        A dict of raw stat fields as returned by the MLB Stats API (the
+        ``stat`` object from the first split), or ``None`` if no stats are
+        available for this player/season/group combination.
+
+    Raises:
+        mlb_statsapi.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code.
+        requests.RequestException:
+            On network-level failures.
+
+    Example::
+
+        from baseball_api_wrapper.modules.players import get_player_stats
+
+        # Juan Soto's 2024 hitting stats
+        stats = get_player_stats(660271, 2024, group="hitting")
+        if stats:
+            print(stats["avg"], stats["homeRuns"], stats["rbi"])
+    """
+    path = _PLAYER_STATS_PATH.format(player_id=player_id)
+
+    params: Dict[str, Any] = {
+        "stats": "season",
+        "season": str(season),
+        "group": group,
+    }
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(path, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    for stat_block in data.get("stats", []):
+        splits = stat_block.get("splits", [])
+        if splits:
+            return splits[0].get("stat")
+
+    return None