baseball-api-wrapper 0.1.0__py3-none-any.whl

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/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/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/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

baseball_api_wrapper/modules/roster.py

@@ -0,0 +1,164 @@
+"""
+Roster
+======
+Functions for retrieving team roster data from the MLB Stats API.
+
+The primary entry point is :func:`get_roster`, which returns the list of
+players (or coaches) on a team's roster for a given season.
+
+Roster Types
+------------
+The API supports several roster types, all exposed via the :class:`RosterType`
+enum.  The most commonly used types are:
+
+* ``ACTIVE``          – The 26-man active roster (in-season).
+* ``FORTY_MAN``       – The full 40-man roster.
+* ``FULL_SEASON``     – Everyone who appeared on the roster at any point
+                        during the season.
+* ``FULL_ROSTER``     – Alias similar to FULL_SEASON.
+* ``NON_ROSTER_INVITEES`` – Spring training non-roster invitees.
+* ``DEPTH_CHART``     – Organizational depth chart.
+* ``GAMEDAY``         – Roster for a specific game day.
+* ``ALL_TIME``        – All-time historical roster.
+* ``COACH``           – Coaching staff.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from ..client import MLBStatsClient
+
+# API path template for the roster endpoint. teamId is a required path param.
+_ROSTER_PATH = "/api/v1/teams/{team_id}/roster"
+
+
+class RosterType(str, Enum):
+    """
+    Valid roster type identifiers accepted by the MLB Stats API.
+
+    Inherits from ``str`` so values can be passed directly wherever a
+    string is expected (e.g. as a query parameter).
+    """
+
+    ACTIVE = "active"
+    FORTY_MAN = "40Man"
+    FULL_SEASON = "fullSeason"
+    FULL_ROSTER = "fullRoster"
+    NON_ROSTER_INVITEES = "nonRosterInvitees"
+    DEPTH_CHART = "depthChart"
+    GAMEDAY = "gameday"
+    ALL_TIME = "allTime"
+    COACH = "coach"
+
+
+def get_roster(
+    team_id: int,
+    season: int | str,
+    roster_type: RosterType | str = RosterType.ACTIVE,
+    date: Optional[str] = None,
+    client: Optional[MLBStatsClient] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Return the roster for a team in a given MLB season.
+
+    Each entry in the returned list represents a single player (or coach,
+    depending on *roster_type*) and contains at minimum:
+
+    * ``person``       – dict with ``id``, ``fullName``, ``link``
+    * ``jerseyNumber`` – string jersey number
+    * ``position``     – dict with ``code``, ``name``, ``type``,
+                         ``abbreviation``
+    * ``status``       – dict describing roster transaction status
+    * ``parentTeamId`` – ID of the parent MLB club
+
+    Args:
+        team_id:
+            Unique team identifier, e.g. ``147`` for the New York Yankees.
+            Team IDs can be retrieved via :func:`~mlb_statsapi.teams.get_teams`.
+        season:
+            The MLB season year, e.g. ``2024`` or ``"2024"``.
+        roster_type:
+            The type of roster to retrieve.  Accepts a :class:`RosterType`
+            member or the equivalent raw string value.  Defaults to
+            :attr:`RosterType.ACTIVE` (the 26-man active roster).
+        date:
+            Optional date string in ``"YYYY-MM-DD"`` format.  When provided,
+            the roster is returned as it stood on that date.  Useful with
+            ``roster_type=RosterType.GAMEDAY``.
+        client:
+            Optional pre-configured :class:`~mlb_statsapi.client.MLBStatsClient`
+            instance.  If omitted, a default client pointing at the official
+            production endpoint is created and used for the single call.
+
+    Returns:
+        A list of roster-entry dictionaries as returned by the MLB Stats API.
+        Returns an empty list if the API response contains no roster entries.
+
+    Raises:
+        mlb_statsapi.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code (e.g. 404 for an
+            unknown team ID).
+        requests.RequestException:
+            On network-level failures (timeouts, DNS errors, etc.).
+        ValueError:
+            If *date* is provided but does not match the ``YYYY-MM-DD`` format.
+
+    Example::
+
+        from mlb_statsapi.roster import get_roster, RosterType
+
+        # Active 26-man roster for the 2024 Yankees
+        roster = get_roster(147, 2024)
+        for entry in roster:
+            print(entry["jerseyNumber"], entry["person"]["fullName"])
+
+        # Full 40-man roster
+        roster_40 = get_roster(147, 2024, roster_type=RosterType.FORTY_MAN)
+
+        # Roster as of a specific date
+        roster_date = get_roster(147, 2024, date="2024-07-04")
+    """
+    if date is not None:
+        _validate_date(date)
+
+    path = _ROSTER_PATH.format(team_id=team_id)
+
+    params: Dict[str, Any] = {
+        "season": str(season),
+        "rosterType": roster_type.value if isinstance(roster_type, RosterType) else roster_type,
+    }
+
+    if date is not None:
+        params["date"] = date
+
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(path, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    return data.get("roster", [])
+
+
+def _validate_date(date: str) -> None:
+    """
+    Ensure *date* matches the ``YYYY-MM-DD`` format expected by the API.
+
+    Args:
+        date: Date string to validate.
+
+    Raises:
+        ValueError: If the string is not a valid ``YYYY-MM-DD`` date.
+    """
+    import datetime
+
+    try:
+        datetime.date.fromisoformat(date)
+    except ValueError:
+        raise ValueError(
+            f"date must be in YYYY-MM-DD format, got {date!r}"
+        )

baseball_api_wrapper/modules/teams.py

@@ -0,0 +1,142 @@
+"""
+Teams
+=====
+Functions for retrieving MLB team data from the Stats API.
+
+The primary entry point is :func:`get_teams`, which returns a list of teams
+for a given MLB season.  Optional filters let callers narrow results by
+league, division, or active status.
+
+MLB Sport IDs
+-------------
+The Stats API serves data for multiple sports / levels. When fetching
+official MLB teams you almost always want ``sport_id=1`` (the default).
+
+Common sport IDs:
+  * 1  – MLB (majors)
+  * 11 – Triple-A
+  * 12 – Double-A
+  * 13 – High-A
+  * 14 – Single-A
+
+Common league IDs:
+  * 103 – American League
+  * 104 – National League
+"""
+
+from typing import Any, Dict, List, Optional
+
+from ..client import MLBStatsClient
+
+# The Stats API path for the teams collection resource.
+_TEAMS_PATH = "/api/v1/teams"
+
+# Sport ID for MLB (major leagues).
+MLB_SPORT_ID = 1
+
+
+def get_teams(
+    season: int | str,
+    sport_id: int = MLB_SPORT_ID,
+    league_ids: Optional[List[int]] = None,
+    division_id: Optional[int] = None,
+    active_status: Optional[str] = None,
+    client: Optional[MLBStatsClient] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Return a list of MLB teams for the specified season.
+
+    Each team is represented as a dictionary containing at minimum:
+    ``id``, ``name``, ``teamCode``, ``abbreviation``, ``teamName``,
+    ``locationName``, ``league``, ``division``, and ``venue``.
+
+    Args:
+        season:
+            The MLB season year to query, e.g. ``2024`` or ``"2024"``.
+        sport_id:
+            Top-level sport identifier.  Use ``1`` (default) for MLB
+            major-league teams.  Pass a different value to retrieve teams
+            from the minors or other affiliated leagues.
+        league_ids:
+            Optional list of league IDs to filter results.  For example,
+            ``[103]`` returns only American League teams and ``[104]``
+            returns only National League teams.
+        division_id:
+            Optional single division ID to restrict results to one division
+            (e.g. ``200`` for AL West).
+        active_status:
+            Controls which teams are included based on their franchise
+            status.  Accepted values:
+
+            * ``"Y"`` – active franchises only (default API behaviour)
+            * ``"N"`` – inactive / historical franchises only
+            * ``"P"`` – pending franchises
+            * ``"B"`` – all franchises regardless of status
+
+        client:
+            Optional pre-configured :class:`~mlb_statsapi.client.MLBStatsClient`
+            instance.  If omitted, a default client pointing at the official
+            production endpoint is created and used for the single call.
+
+    Returns:
+        A list of team dictionaries as returned by the MLB Stats API.
+        Returns an empty list if the API response contains no teams.
+
+    Raises:
+        mlb_statsapi.client.MLBStatsAPIError:
+            If the API returns a non-2xx HTTP status code.
+        requests.RequestException:
+            On network-level failures (timeouts, DNS errors, etc.).
+        ValueError:
+            If *active_status* is not one of the accepted values.
+
+    Example::
+
+        from mlb_statsapi.teams import get_teams
+
+        # All 30 MLB teams for the 2024 season
+        teams = get_teams(2024)
+        for team in teams:
+            print(team["id"], team["name"])
+
+        # Only American League teams
+        al_teams = get_teams(2024, league_ids=[103])
+
+        # All historical franchises (active + inactive)
+        all_franchises = get_teams(2024, active_status="B")
+    """
+    valid_statuses = {"Y", "N", "P", "B"}
+    if active_status is not None and active_status not in valid_statuses:
+        raise ValueError(
+            f"active_status must be one of {sorted(valid_statuses)}, "
+            f"got {active_status!r}"
+        )
+
+    params: Dict[str, Any] = {
+        "season": str(season),
+        "sportId": sport_id,
+    }
+
+    if league_ids is not None:
+        # The API accepts a comma-separated list for leagueIds.
+        params["leagueIds"] = ",".join(str(lid) for lid in league_ids)
+
+    if division_id is not None:
+        params["divisionId"] = division_id
+
+    if active_status is not None:
+        params["activeStatus"] = active_status
+
+    # Allow callers to inject a client (useful for testing / custom config).
+    # If none is provided, create a throw-away default client.
+    _owns_client = client is None
+    if _owns_client:
+        client = MLBStatsClient()
+
+    try:
+        data = client.get(_TEAMS_PATH, params=params)
+    finally:
+        if _owns_client:
+            client.close()
+
+    return data.get("teams", [])

baseball_api_wrapper-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+baseball_api_wrapper/__init__.py,sha256=CXwPig_Ts_GRRsGpxOr6gr_vqP7HBqhKIT-9oGqr9pE,807
+baseball_api_wrapper/client.py,sha256=fp0_fV8O0Lv-SL6eBoopINeLddn133Yiv7JQeDdh7jU,2605
+baseball_api_wrapper/modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+baseball_api_wrapper/modules/games.py,sha256=4QGc77PJsuuPFEQREgF54VqeVdNCA62s467WNSP3QBU,4167
+baseball_api_wrapper/modules/players.py,sha256=8zg1xMO81u21brAb1eBrBGL1encRNQBq62D2tW7kX-c,5359
+baseball_api_wrapper/modules/roster.py,sha256=yHsZJ5_aikR4_b2kfl3SAh4MyntRgB75qsseZGoINIw,5422
+baseball_api_wrapper/modules/teams.py,sha256=HyuNS-IVTVddZY3bfOFA5PDsvwylHlXxZiffki789M0,4649
+baseball_api_wrapper-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+baseball_api_wrapper-0.1.0.dist-info/METADATA,sha256=9US0YflCIZVMWreIhtOdy0WQ86agK894tYQj6ltG3Dc,2591
+baseball_api_wrapper-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+baseball_api_wrapper-0.1.0.dist-info/top_level.txt,sha256=Xywgv0rkNorrhzYPkSVaq1QJ7dvwrmSK3srpp1F5Xr8,21
+baseball_api_wrapper-0.1.0.dist-info/RECORD,,

baseball_api_wrapper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

baseball_api_wrapper-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+baseball_api_wrapper