mlbrecaps 0.0.2__tar.gz → 0.1.0__tar.gz

mlbrecaps-0.0.2/LICENSE.txt → mlbrecaps-0.1.0/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Karsten Larson
+Copyright (c) 2025 Karsten Larson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

mlbrecaps-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: mlbrecaps
+Version: 0.1.0
+Summary: Package that gathers information on given MLB games and allows downloading of video clips of plays.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: bs4>=0.0.2
+Requires-Dist: curl-cffi>=0.13.0
+Requires-Dist: fireducks>=1.3.3
+Requires-Dist: lark>=1.2.2
+Requires-Dist: lxml>=6.0.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyyaml>=6.0.2
+Dynamic: license-file
+
+# mlbrecaps
+
+mlbrecaps is a Python library for querying and retrieving highlight videos and play information from Major League Baseball (MLB) games. It provides a simple interface to access game recaps, top plays, and player highlights programmatically.
+
+## Features
+
+- Query highlight videos for specific MLB games
+- Retrieve top plays for a given day, month, or year
+- Get player-specific highlight clips
+- Easily integrate with your own Python scripts
+
+## Installation
+
+You can install mlbrecaps directly from PyPI using pip:
+
+```bash
+pip install mlbrecaps
+```
+
+### Install from Source
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/yourusername/mlbrecaps.git
+   cd mlbrecaps
+   ```
+
+2. **Install dependencies with uv:**
+
+   ```bash
+   uv pip install -e .
+   ```
+
+   This will install the package in editable mode along with all required dependencies.
+
+## Example Scripts
+
+The `examples/` directory contains ready-to-run scripts:
+
+- `examples/top_player_plays.py` — Get top plays for a player
+- `examples/top_plays_of_month.py` — Get top plays for a month
+- `examples/top_plays_of_year.py` — Get top plays for a year
+
+Run an example with:
+
+```bash
+python examples/top_player_plays.py
+```
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository and create your branch.
+2. Make your changes and add tests if applicable.
+3. Ensure code style and formatting are consistent.
+4. Submit a pull request with a clear description of your changes.
+
+## License
+
+This project is open source and available under the MIT License.

mlbrecaps-0.1.0/README.md

@@ -0,0 +1,62 @@
+# mlbrecaps
+
+mlbrecaps is a Python library for querying and retrieving highlight videos and play information from Major League Baseball (MLB) games. It provides a simple interface to access game recaps, top plays, and player highlights programmatically.
+
+## Features
+
+- Query highlight videos for specific MLB games
+- Retrieve top plays for a given day, month, or year
+- Get player-specific highlight clips
+- Easily integrate with your own Python scripts
+
+## Installation
+
+You can install mlbrecaps directly from PyPI using pip:
+
+```bash
+pip install mlbrecaps
+```
+
+### Install from Source
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/yourusername/mlbrecaps.git
+   cd mlbrecaps
+   ```
+
+2. **Install dependencies with uv:**
+
+   ```bash
+   uv pip install -e .
+   ```
+
+   This will install the package in editable mode along with all required dependencies.
+
+## Example Scripts
+
+The `examples/` directory contains ready-to-run scripts:
+
+- `examples/top_player_plays.py` — Get top plays for a player
+- `examples/top_plays_of_month.py` — Get top plays for a month
+- `examples/top_plays_of_year.py` — Get top plays for a year
+
+Run an example with:
+
+```bash
+python examples/top_player_plays.py
+```
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository and create your branch.
+2. Make your changes and add tests if applicable.
+3. Ensure code style and formatting are consistent.
+4. Submit a pull request with a clear description of your changes.
+
+## License
+
+This project is open source and available under the MIT License.

mlbrecaps-0.1.0/mlbrecaps/__init__.py

@@ -0,0 +1,21 @@
+from .date import Date, Season
+from .games import Games
+from .game import Game
+from .plays import Play, PlayField
+from .team import Team
+from .broadcast import BroadcastType
+from .clip import Clip
+from .player import Player
+
+__all__ = [
+    "Date",
+    "Season",
+    "Games",
+    "Game",
+    "Play",
+    "PlayField",
+    "Team",
+    "BroadcastType",
+    "Clip",
+    "Player"
+]

mlbrecaps-0.1.0/mlbrecaps/broadcast.py

@@ -0,0 +1,9 @@
+from enum import Enum, auto
+
+class BroadcastType(Enum):
+    """
+    Enum representing different types of broadcasts.
+    """
+    HOME = auto()
+    AWAY = auto()
+    NETWORK = auto()

mlbrecaps-0.1.0/mlbrecaps/clip.py

@@ -0,0 +1,112 @@
+from bs4 import BeautifulSoup, Tag
+
+from curl_cffi.requests.exceptions import Timeout
+from pathlib import Path
+
+from .play import Play
+from .utils import fetch_html_from_url, fetch_url
+from .broadcast import BroadcastType
+from .team import Team
+
+class Clip():
+    """A wrapper class for Play that allows for plays to be downloaded"""
+
+    def __init__(self, play: Play, broadcast_type: Team | BroadcastType | None = None):
+        self._play: Play = play
+        self.broadcast_type: BroadcastType | None = None
+
+        # Find the broadcast type based on the given team
+        if isinstance(broadcast_type, Team):
+            if self._play.home_team == broadcast_type.name:
+                self.broadcast_type = BroadcastType.HOME
+            else:
+                self.broadcast_type = BroadcastType.AWAY
+        else:
+            self.broadcast_type: BroadcastType | None = broadcast_type
+
+    @property
+    def play(self) -> Play:
+        return self._play
+    
+    async def __get_url(self, site_url: str) -> str:
+        """
+        Gets the url of the clip to be downloaded from the savant clip
+        """
+        # Get the savant site
+        site = await fetch_html_from_url(site_url)
+
+        # Find the video element of the savant clip, find the source url of the clip
+        soup = BeautifulSoup(site, features="lxml")
+        video_obj = soup.find("video", id="sporty")
+
+        if not isinstance(video_obj, Tag):
+            raise ValueError("Clip url is not found")
+
+        source = video_obj.find('source')
+
+        if not isinstance(source, Tag):
+            raise ValueError("Clip url is not found")
+
+        clip_url = source.get('src')
+        
+        if not isinstance(clip_url, str) or clip_url is None:
+            raise ValueError("Clip url is not found or not a string")
+
+        # Return the source url of the clip so it can be downloaded later
+        return clip_url
+
+    async def __generate(self) -> str:
+        """
+        Generates a savant clip based on the given at-bat information
+
+        Row must be a pandas dataframe row.
+        """
+
+        # find the broadcast type so it's always corresponding
+        # to the given batter's home team's broadcast
+        if self.broadcast_type:
+            broadcast_type = self.broadcast_type
+        elif self._play.inning_topbot == "TOP":
+            broadcast_type = BroadcastType.AWAY
+        else:
+            broadcast_type = BroadcastType.HOME
+
+        # with the play id find the url for the savant clip
+        site_url = f"https://baseballsavant.mlb.com/sporty-videos?playId={self._play.play_id}&videoType={broadcast_type.name}"
+        clip_url = await self.__get_url(site_url)
+
+        # if the clip is alright return it
+        if clip_url != "":
+            return clip_url
+        
+        if broadcast_type == BroadcastType.NETWORK:
+            raise ValueError("Clip url is not found or not a string")
+
+        # if the clip is screwed up then it was a national tv game
+        # return the correct national tv clip url
+        site_url = f"https://baseballsavant.mlb.com/sporty-videos?playId={self._play.play_id}&videoType=NETWORK"
+        clip_url = await self.__get_url(site_url)
+
+        return clip_url
+
+    async def download(self, path: str | Path, verbose: bool = False) -> Path:
+        path = Path(path)
+
+        clip_url = await self.__generate()
+
+        # create response object
+        try:
+            r = await fetch_url(clip_url)
+        except Timeout:
+            print(f'Timeout has been raised. Link: {clip_url}')
+            raise
+
+        # Download video
+        with path.open("wb") as f:
+            f.write(r.content)
+
+        # State the video was successfully downloaded
+        if verbose:
+            print(f"Successfully downloaded: {path.absolute()}")
+
+        return path

mlbrecaps-0.1.0/mlbrecaps/date.py

@@ -0,0 +1,33 @@
+from typing import Optional
+from datetime import date
+
+def parse_date(v: str | date) -> date:
+    if isinstance(v, str):
+        return date.fromisoformat(v)
+    return v
+
+class Date():
+    def __init__(self, start_date: date | str, end_date: Optional[date | str] = None):
+        self._start_date = parse_date(start_date)
+        self._end_date = parse_date(end_date) if end_date else self._start_date
+
+        if self._start_date > self._end_date:
+            raise ValueError("start_date must be less than or equal to end_date")
+
+    @property
+    def start_date(self) -> date:    
+        return self._start_date
+
+    @property
+    def end_date(self) -> date:
+        return self._end_date    
+
+class Season(Date):
+    """
+    Represents a season in MLB.
+    Inherits from Date to provide start and end dates.
+    """
+    def __init__(self, year: int):
+        start_date = date(year, 1, 1)  # Assuming season starts in March
+        end_date = date(year, 12, 31)   # Assuming season ends in November
+        super().__init__(start_date, end_date)

mlbrecaps-0.1.0/mlbrecaps/game.py

@@ -0,0 +1,108 @@
+from pydantic import BaseModel, ConfigDict
+from typing import Optional
+
+from .plays import Plays
+
+class Status(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    abstractGameState: str
+    codedGameState: str
+    detailedState: str
+    statusCode: str
+    startTimeTBD: bool
+    abstractGameCode: str
+
+
+class LeagueRecord(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    wins: int
+    losses: int
+    pct: str
+
+
+class Team(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    id: int
+    name: str
+    link: str
+
+
+class TeamResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    leagueRecord: LeagueRecord
+    score: Optional[int] = None
+    team: Team
+    isWinner: Optional[bool] = None
+    splitSquad: Optional[bool] = None
+    seriesNumber: Optional[int] = None
+
+
+class Teams(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    away: TeamResult
+    home: TeamResult
+
+
+class Venue(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    id: int
+    name: str
+    link: str
+
+
+class Content(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    link: str
+
+
+class Game(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    gamePk: int
+    gameGuid: str
+    link: str
+    gameType: str
+    season: str
+    gameDate: str
+    officialDate: str
+    status: Status
+    teams: Teams
+    venue: Venue
+    content: Content
+    # isTie: Optional[bool] = None
+    gameNumber: int
+    publicFacing: bool
+    doubleHeader: str
+    gamedayType: str
+    tiebreaker: str
+    calendarEventID: str
+    seasonDisplay: str
+    dayNight: str
+    scheduledInnings: int
+    reverseHomeAwayStatus: bool
+    inningBreakLength: int
+    gamesInSeries: Optional[int] = None
+    seriesGameNumber: Optional[int] = None
+    seriesDescription: Optional[str] = None
+    recordSource: str
+    ifNecessary: str
+    ifNecessaryDescription: str
+
+    @property
+    def plays(self) -> Plays:
+        """Returns a Plays instance for the game."""
+        return Plays([self.gamePk])
+    
+    @property
+    def is_final(self) -> bool:
+        """Returns True if the game is final."""
+        return self.status.codedGameState == "F"
+    
+    @property
+    def is_regular_season(self) -> bool:
+        """Returns True if the game is a regular season game."""
+        return self.gameType == "R"
+    
+    @property
+    def is_valid_game(self) -> bool:
+        """Returns True if the game is a valid regular season game."""
+        return self.is_final and self.is_regular_season

mlbrecaps-0.1.0/mlbrecaps/game_play_ids.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel
+from typing import Optional
+
+class Scoreboard(BaseModel):
+    gamePk: int
+
+
+class PlayItem(BaseModel):
+    play_id: str
+    inning: int
+    ab_number: int
+    cap_index: int
+    outs: int
+    batter: int
+    pitcher: int
+    pitch_number: int
+    player_total_pitches: int
+    game_total_pitches: int
+    rowId: str
+    game_pk: int
+
+class GamePlayIds(BaseModel):
+    game_status_code: str
+    game_status: str
+    gamedayType: str
+    gameDate: str
+    scoreboard: Scoreboard
+    team_home: list[PlayItem] = []
+    team_away: list[PlayItem] = []
+
+    @property
+    def play_data(self) -> list[PlayItem]:
+        return self.team_home + self.team_away

mlbrecaps-0.1.0/mlbrecaps/games.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Iterator
+from pydantic import BaseModel, ConfigDict
+from functools import cached_property
+
+from .date import Date
+from .plays import Plays
+from .game import Game
+from .team import Team
+from .utils import fetch_model_from_url
+
+class GameDate(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    date: str
+    totalGames: int
+    totalGamesInProgress: int
+    games: list[Game]
+
+    @property
+    def final_games(self) -> list[Game]:
+        """Returns a list of final games for the date."""
+        return [game for game in self.games if game.is_valid_game]
+
+
+class Games(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    totalGames: int
+    totalGamesInProgress: int
+    dates: list[GameDate]
+
+    @cached_property
+    def game_pks(self) -> set[int]:
+        """Returns a list of game Pks."""
+        return {game.gamePk for date in self.dates for game in date.final_games}
+
+    @cached_property
+    def games_by_pk(self) -> dict[int, Game]:
+        """Returns a dictionary mapping game Pks to Game objects."""
+        return {game.gamePk: game for date in self.dates for game in date.final_games}
+
+    @cached_property
+    def games_by_date(self) -> dict[str, list[Game]]:
+        """Returns a dictionary mapping dates to lists of Game objects."""
+        return {date.date: date.final_games for date in self.dates}
+    
+    @cached_property
+    def games(self) -> list[Game]:
+        """Returns a flat list of all Game objects."""
+        return [game for date in self.dates for game in date.final_games]
+        
+    @cached_property
+    def plays(self) -> Plays:
+        return Plays(self.game_pks)
+
+    @cached_property
+    def games_by_team(self) -> dict[int, list[Game]]:
+        """Returns a dictionary mapping team IDs to lists of Game objects."""
+        team_games = {}
+        for date in self.dates:
+            for game in date.final_games:
+                team_id = game.teams.away.team.id
+                if team_id not in team_games:
+                    team_games[team_id] = []
+                team_games[team_id].append(game)
+                team_id = game.teams.home.team.id
+                if team_id not in team_games:
+                    team_games[team_id] = []
+                team_games[team_id].append(game)
+        return team_games  
+    
+    def iter_games(self) -> Iterator[Game]:
+        """Returns an iterator over all Game objects."""
+        return iter(self.games)
+
+    def __len__(self) -> int:
+        """Returns the total number of games."""
+        return len(self.games)  
+    
+    def __add__(self, other: Games) -> Games:
+        return Games(
+            totalGames=self.totalGames + other.totalGames,
+            totalGamesInProgress=self.totalGamesInProgress + other.totalGamesInProgress,
+            dates=self.dates + other.dates
+        )
+
+    @staticmethod
+    async def get_games(date: Date) -> Games:
+        url = f'https://statsapi.mlb.com/api/v1/schedule?startDate={date.start_date}&endDate={date.end_date}&sportId=1'
+
+        return await fetch_model_from_url(url, Games)
+
+    @staticmethod
+    async def get_games_by_team(team: Team, date: Date) -> Games:
+        """Fetches games for a specific team within a date range."""
+        url = f'https://statsapi.mlb.com/api/v1/schedule?startDate={date.start_date}&endDate={date.end_date}&sportId=1&teamId={team.value}'
+
+        return await fetch_model_from_url(url, Games)