mlb-cli-py 0.1.0__py3-none-any.whl

app/config.py

@@ -0,0 +1,26 @@
+"""
+Configuration module for the MLB CLI application.
+Centralizes all constants and environment-specific settings.
+"""
+
+# TUI Settings
+STATIC_WIDTH = 80
+INITIAL_HEIGHT = 36
+
+# Redis Settings
+REDIS_HOST = 'localhost'
+REDIS_PORT = 6379
+REDIS_DB = 0
+
+# Data Service Settings
+LIVE_DATA_TTL = 300  # 5 minutes
+
+# Division name mapping
+DIVISION_NAMES = {
+    200: "AL West",
+    201: "AL East",
+    202: "AL Central",
+    203: "NL West",
+    204: "NL East",
+    205: "NL Central"
+}

app/exceptions.py

@@ -0,0 +1,6 @@
+"""
+Custom exceptions for the MLB CLI application.
+"""
+
+class APIError(Exception):
+    """Raised when an error occurs while fetching data from the MLB API."""

app/logger.py

@@ -0,0 +1,29 @@
+"""
+Logging configuration for the MLB CLI application.
+Provides a standard logger that writes to a local log file.
+"""
+import os
+import logging
+from logging.handlers import RotatingFileHandler
+
+# Ensure log directory exists
+LOG_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+LOG_FILE = os.path.join(LOG_DIR, "mlb_cli.log")
+
+def get_logger(name):
+    """
+    Configures and returns a logger instance.
+    """
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        logger.setLevel(logging.DEBUG)
+
+        # Rotating file handler (5MB per file, keeps 2 backups)
+        handler = RotatingFileHandler(LOG_FILE, maxBytes=5*1024*1024, backupCount=2)
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    return logger

app/mlb_cli.py

@@ -0,0 +1,332 @@
+"""
+Main entry point for the MLB CLI application.
+This module initializes the Terminal UI and manages the primary window and global keybindings.
+"""
+from datetime import datetime, timedelta
+import pytermgui as ptg
+from .models.data_service import (
+    fetch_teams,
+    format_date
+)
+from .screens import (
+    ScheduleScreen,
+    StandingsScreen,
+    CalendarScreen,
+    ErrorScreen
+)
+from .widgets import CalendarWidget, slide_transition
+from .config import STATIC_WIDTH, INITIAL_HEIGHT
+from .state import ApplicationState
+from .exceptions import APIError
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class MLBApp:
+    """
+    TUI Manager class for the MLB CLI application.
+    Handles window management, screen transitions, and global keybindings.
+    """
+    # pylint: disable=too-many-instance-attributes
+
+    def __init__(self):
+        """Initializes the application UI and logic state."""
+        fetch_teams()
+        self.manager = ptg.WindowManager()
+        self.state = ApplicationState()
+        self.static_width = STATIC_WIDTH
+        self.static_height = 0  # Will be set in run()
+        self.main_window = None
+        self.is_initialized = False
+
+    def set_window_data(self, widgets, title, page_name, on_finish=None):
+        """Sets content for the main window, using animation if already initialized."""
+        if self.state.active_page == page_name:
+            if on_finish:
+                on_finish()
+            return
+
+        # Calculate required height based on content
+        max_height = self.manager.terminal.height - 2
+        temp_window = ptg.Window(*widgets, width=self.static_width)
+        temp_window.set_title(title)
+        target_height = min(max_height, temp_window.height)
+
+        self.state.set_active_page(page_name)
+        if not self.is_initialized:
+            self.is_initialized = True
+            self.main_window.set_widgets(widgets)
+            self.main_window.set_title(title)
+            self.main_window.width = self.static_width
+            self.main_window.height = target_height
+            self.main_window.styles.border = "green"
+            self.main_window.styles.corner = "green"
+            self.main_window.center()
+            if on_finish:
+                on_finish()
+            return
+
+        slide_transition(
+            self.main_window,
+            self.manager,
+            widgets,
+            title,
+            on_finish=on_finish,
+            new_height=target_height
+        )
+
+    @staticmethod
+    def handle_errors(func):
+        """Decorator to handle errors during screen transitions."""
+        def wrapper(self, *args, **kwargs):
+            try:
+                return func(self, *args, **kwargs)
+            except (APIError, Exception) as e:  # pylint: disable=broad-exception-caught
+                logger.error("Error in %s: %s", func.__name__, e, exc_info=True)
+                # Provide a user-friendly message for generic exceptions
+                msg = str(e) if isinstance(e, APIError) else "An unexpected error occurred"
+                widgets, title = ErrorScreen.get_widgets(msg)
+                self.set_window_data(widgets, title, "error")
+                return False
+        return wrapper
+
+    @handle_errors
+    def update_to_schedule(self, *_args, **_kwargs):
+        """Transitions the main window to show the schedule for current_date."""
+        date_str = format_date(self.state.current_date)
+        widgets, title = ScheduleScreen.get_widgets(date_str)
+        self.set_window_data(widgets, title, f"schedule:{date_str}")
+        return True
+
+    def go_to_previous_day(self, *_args, **_kwargs):
+        """Decrements the current date or page."""
+        if self.state.on_calendar_screen:
+            return self.go_to_previous_page()
+
+        if self.state.decrement_date():
+            return self.update_to_schedule()
+        return True
+
+    def go_to_next_day(self, *_args, **_kwargs):
+        """Increments the current date or page."""
+        if self.state.on_calendar_screen:
+            return self.go_to_next_page()
+
+        if self.state.increment_date():
+            return self.update_to_schedule()
+        return True
+
+    @handle_errors
+    def toggle_standings(self, *_args, **_kwargs):
+        """Toggles between standings and schedule/calendar."""
+        if self.state.on_standings_screen:
+            return self.update_to_schedule()
+
+        widgets, title = StandingsScreen.get_widgets()
+        self.set_window_data(widgets, title, "standings")
+        return True
+
+    @handle_errors
+    def update_to_calendar(self, *_args, sync_page=True, focus_target=None, **_kwargs):
+        """Transitions to the calendar view."""
+        if self.state.on_standings_screen:
+            self.state.reset_to_today()
+
+        if sync_page:
+            # Ensure calendar_page matches current_date
+            self.state.determine_initial_calendar_page()
+
+        pages = [
+            [3, 4, 5],
+            [6, 7, 8],
+            [9, 10]
+        ]
+        months = pages[self.state.calendar_page]
+        widgets, title = CalendarScreen.get_widgets(
+            2026,
+            months,
+            self.on_calendar_date_selected,
+            selected_date=self.state.current_date
+        )
+        self.set_window_data(
+            widgets,
+            title,
+            f"calendar:{self.state.calendar_page}",
+            on_finish=lambda: self._focus_current_date_in_calendar(target=focus_target)
+        )
+        return True
+
+    def _focus_current_date_in_calendar(self, target=None):
+        # pylint: disable=too-many-branches
+        """
+        Helper to find and focus a date in the calendar view.
+        If target is None, focuses current_date.
+        If target is 'first', focuses first date of first month.
+        If target is 'last', focuses last date of last month.
+        """
+        calendar_widgets = []
+        for widget in self.main_window:
+            if not isinstance(widget, ptg.Container):
+                continue
+            for sub in widget:
+                if isinstance(sub, CalendarWidget):
+                    calendar_widgets.append(sub)
+
+        if not calendar_widgets:
+            return False
+
+        target_btn = None
+        if target == "first":
+            sub = calendar_widgets[0]
+            first_day = min(sub.day_to_button.keys())
+            target_btn = sub.day_to_button[first_day]
+        elif target == "last":
+            sub = calendar_widgets[-1]
+            last_day = max(sub.day_to_button.keys())
+            target_btn = sub.day_to_button[last_day]
+        else:
+            # Default: focus current_date
+            for sub in calendar_widgets:
+                if sub.month == self.state.current_date.month:
+                    day = self.state.current_date.day
+                    if day in sub.day_to_button:
+                        target_btn = sub.day_to_button[day]
+                        break
+
+        if target_btn:
+            for i, (selectable, _) in enumerate(self.main_window.selectables):
+                if selectable is target_btn:
+                    self.main_window.select(i)
+                    self.manager.focused = target_btn
+                    return True
+        return False
+
+    def on_calendar_date_selected(self, year, month, day):
+        """Callback for when a date is selected in the calendar."""
+        self.state.current_date = datetime(year, month, day)
+        return self.update_to_schedule()
+
+    def _navigate_calendar(self, direction):
+        # pylint: disable=too-many-branches
+        """
+        Global WASD navigation for the calendar.
+        Moves focus between buttons based on date logic.
+        """
+        if not self.state.on_calendar_screen:
+            return False
+
+        focused = self.manager.focused
+        if focused is None:
+            return False
+
+        # Find which CalendarWidget the focused button belongs to
+        target_widget = None
+        for widget in self.main_window:
+            if not isinstance(widget, ptg.Container):
+                continue
+            for sub in widget:
+                if isinstance(sub, CalendarWidget) and focused in sub.button_to_day:
+                    target_widget = sub
+                    break
+            if target_widget:
+                break
+
+        if not target_widget:
+            return False
+
+        day = target_widget.button_to_day[focused]
+        current_date = datetime(target_widget.year, target_widget.month, day)
+
+        delta = {
+            "w": timedelta(days=-7),
+            "a": timedelta(days=-1),
+            "s": timedelta(days=7),
+            "d": timedelta(days=1),
+        }.get(direction)
+
+        if not delta:
+            return False
+
+        target_date = current_date + delta
+
+        # Look for the target date in any CalendarWidget in the main window
+        for widget in self.main_window:
+            if not isinstance(widget, ptg.Container):
+                continue
+            for sub in widget:
+                if not (isinstance(sub, CalendarWidget) and
+                        sub.year == target_date.year and
+                        sub.month == target_date.month):
+                    continue
+
+                if target_date.day in sub.day_to_button:
+                    target_btn = sub.day_to_button[target_date.day]
+                    # Find and select the button index in the window
+                    for i, (selectable, _) in enumerate(self.main_window.selectables):
+                        if selectable is target_btn:
+                            self.main_window.select(i)
+                            self.manager.focused = target_btn
+                            return True
+        return False
+
+    def go_to_previous_page(self, *_args, **_kwargs):
+        """Moves calendar view to the previous page with wrapping."""
+        self.state.prev_calendar_page()
+        return self.update_to_calendar(sync_page=False, focus_target="last")
+
+    def go_to_next_page(self, *_args, **_kwargs):
+        """Moves calendar view to the next page with wrapping."""
+        self.state.next_calendar_page()
+        return self.update_to_calendar(sync_page=False, focus_target="first")
+
+    def go_to_today(self, *_args, **_kwargs):
+        """Resets the current date to today and updates the view."""
+        self.state.reset_to_today()
+        return self.update_to_schedule()
+
+    def exit_app(self, *_args, **_kwargs):
+        """Stops the WindowManager and exits the application."""
+        self.manager.stop()
+        return True
+
+    def run(self):
+        """Starts the application main loop."""
+        with self.manager:
+            self.static_height = min(INITIAL_HEIGHT, self.manager.terminal.height - 2)
+
+            self.main_window = ptg.Window(
+                width=self.static_width,
+                height=self.static_height,
+                is_static=True,
+                is_noresize=True)
+            self.manager.add(self.main_window)
+
+            # Initial content: Calendar
+            self.update_to_calendar()
+
+            # Global bindings
+            self.manager.bind("[", self.go_to_previous_day)
+            self.manager.bind("]", self.go_to_next_day)
+            self.manager.bind("t", self.go_to_today)
+            self.manager.bind("c", self.update_to_calendar)
+            self.manager.bind("x", self.toggle_standings)
+            self.manager.bind(ptg.keys.ESC, self.exit_app)
+
+            # WASD for Calendar Navigation
+            self.manager.bind("w", lambda *_: self._navigate_calendar("w"))
+            self.manager.bind("a", lambda *_: self._navigate_calendar("a"))
+            self.manager.bind("s", lambda *_: self._navigate_calendar("s"))
+            self.manager.bind("d", lambda *_: self._navigate_calendar("d"))
+
+            self.manager.run()
+
+
+def main():
+    """Entry point for the application."""
+    app = MLBApp()
+    app.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

app/models/base_data_source.py

@@ -0,0 +1,28 @@
+"""
+Base module for data source abstractions.
+Provides the interface for fetching MLB data.
+"""
+from abc import ABC, abstractmethod
+
+
+class BaseDataSource(ABC):
+    """
+    Abstract base class for all MLB data sources.
+    Defines the contract for fetching team info, schedules, and standings.
+    """
+
+    @abstractmethod
+    def fetch_teams(self):
+        """Fetches all MLB teams and returns a mapping of ID to abbreviation."""
+
+    @abstractmethod
+    def fetch_schedule(self, date_str):
+        """Fetches the MLB schedule for a specific date."""
+
+    @abstractmethod
+    def fetch_standings(self):
+        """Fetches current MLB standings."""
+
+    @abstractmethod
+    def fetch_wild_card(self, league_id):
+        """Fetches wild card standings for a league."""

app/models/cache_service.py

@@ -0,0 +1,58 @@
+"""
+Caching service module for the MLB CLI application.
+Uses Redis to store API responses with specific TTL policies.
+"""
+import json
+import redis
+
+from app.config import REDIS_HOST, REDIS_PORT, REDIS_DB
+
+try:
+    # pylint: disable=invalid-name
+    _redis_client = redis.Redis(
+        host=REDIS_HOST, port=REDIS_PORT, db=REDIS_DB, decode_responses=True
+    )
+except Exception:  # pylint: disable=broad-exception-caught
+    _redis_client = None
+
+
+def get_cached_data(key):
+    """
+    Retrieves data from the cache.
+
+    Args:
+        key (str): The cache key.
+
+    Returns:
+        dict/list/None: The cached data if found and valid, else None.
+    """
+    if _redis_client is None:
+        return None
+
+    try:
+        data = _redis_client.get(key)
+        return json.loads(data) if data else None
+    except (redis.RedisError, json.JSONDecodeError):
+        return None
+
+
+def set_cached_data(key, data, ttl=None):
+    """
+    Stores data in the cache.
+
+    Args:
+        key (str): The cache key.
+        data (dict/list): The data to cache.
+        ttl (int, optional): Time-to-live in seconds.
+    """
+    if _redis_client is None:
+        return
+
+    try:
+        json_data = json.dumps(data)
+        if ttl:
+            _redis_client.setex(key, ttl, json_data)
+        else:
+            _redis_client.set(key, json_data)
+    except Exception:  # pylint: disable=broad-exception-caught
+        pass

app/models/data_service.py

@@ -0,0 +1,190 @@
+"""
+Data service module for fetching MLB data.
+Delegates to a BaseDataSource implementation (defaulting to StatsApiDataSource).
+"""
+from datetime import datetime, timedelta
+from app.config import LIVE_DATA_TTL
+from app.models.cache_service import get_cached_data, set_cached_data
+from .statsapi_source import StatsApiDataSource
+
+# Global cache for team abbreviations
+TEAMS = {}
+
+# Default data source
+_data_source = StatsApiDataSource()
+
+
+def fetch_teams():
+    """
+    Fetches all MLB teams and populates the global TEAMS cache with abbreviations.
+    """
+    TEAMS.clear()
+    TEAMS.update(_data_source.fetch_teams())
+
+
+def get_team_abbr(team_id):
+    """
+    Retrieves the abbreviation for a given team ID.
+    Populates the TEAMS cache if it is empty.
+    """
+    if not TEAMS:
+        fetch_teams()
+    return TEAMS.get(team_id, str(team_id))
+
+
+def fetch_schedule(date_str):
+    """
+    Fetches the MLB schedule for a specific date.
+
+    Args:
+        date_str (str): The date string in MM/DD/YYYY format.
+
+    Returns:
+        list: A list of game dictionaries.
+    """
+    cache_key = f"schedule:{date_str}"
+    cached = get_cached_data(cache_key)
+    if cached is not None:
+        return cached
+
+    data = _data_source.fetch_schedule(date_str)
+
+    # Policy: Today has TTL, other dates don't
+    ttl = LIVE_DATA_TTL if date_str == get_today_date() else None
+    set_cached_data(cache_key, data, ttl=ttl)
+
+    return data
+
+
+def format_date(dt):
+    """Formats a datetime object to MM/DD/YYYY."""
+    return dt.strftime('%m/%d/%Y')
+
+
+def parse_date(date_str):
+    """Parses a MM/DD/YYYY string into a datetime object."""
+    return datetime.strptime(date_str, '%m/%d/%Y')
+
+
+def get_yesterday_date():
+    """
+    Returns yesterday's date as a formatted string.
+
+    Returns:
+        str: Date in MM/DD/YYYY format.
+    """
+    return (datetime.now() - timedelta(days=1)).strftime('%m/%d/%Y')
+
+
+def get_today_date():
+    """
+    Returns today's date as a formatted string.
+
+    Returns:
+        str: Date in MM/DD/YYYY format.
+    """
+    return datetime.now().strftime('%m/%d/%Y')
+
+
+def _parse_team_record(tr, is_wild_card=False):
+    """Parses a team record from the API into a simplified dictionary."""
+    # Find last 10 record
+    l10 = "-"
+    if 'records' in tr and 'splitRecords' in tr['records']:
+        for split in tr['records']['splitRecords']:
+            if split['type'] == 'lastTen':
+                l10 = f"{split['wins']}-{split['losses']}"
+                break
+
+    # Format winning percentage (e.g., .500 -> 50.0%)
+    pct_val = tr.get('winningPercentage', '0')
+    try:
+        pct_float = float(pct_val) * 100
+        pct_str = f"{pct_float:.1f}%"
+    except (ValueError, TypeError):
+        pct_str = "-"
+
+    # Prioritize wildCardGamesBack for wild card view, else use gamesBack
+    if is_wild_card:
+        gb = tr.get('wildCardGamesBack', tr.get('gamesBack', '-'))
+    else:
+        gb = tr.get('gamesBack', '-')
+
+    return {
+        'team_id': tr['team']['id'],
+        'w': tr['wins'],
+        'l': tr['losses'],
+        'gb': gb,
+        'pct': pct_str,
+        'l10': l10
+    }
+
+
+def fetch_wild_card(league_id):
+    """
+    Fetches the wild card standings for a specific league.
+
+    Args:
+        league_id (int): The ID of the league (103 for AL, 104 for NL).
+
+    Returns:
+        dict: Wild card standings data.
+    """
+    cache_key = f"wildcard:{league_id}"
+    cached = get_cached_data(cache_key)
+    if cached is not None:
+        return cached
+
+    record = _data_source.fetch_wild_card(league_id)
+    if not record:
+        return None
+
+    teams = [_parse_team_record(tr, is_wild_card=True) for tr in record.get('teamRecords', [])]
+
+    league_name = "AL" if league_id == 103 else "NL"
+    result = {
+        'div_name': f"{league_name} Wild Card",
+        'teams': teams[:7]
+    }
+    set_cached_data(cache_key, result, ttl=LIVE_DATA_TTL)
+    return result
+
+
+def fetch_standings():
+    """
+    Fetches the current MLB standings for the American and National Leagues,
+    including divisions and wild card.
+
+    Returns:
+        tuple: (al_divs, nl_divs, al_wc, nl_wc)
+    """
+    cache_key = "standings:full"
+    cached = get_cached_data(cache_key)
+    if cached is not None:
+        return tuple(cached)
+
+    div_results = _data_source.fetch_standings()
+    if not div_results:
+        return [], [], None, None
+
+    div_map = {}
+    for div in div_results:
+        div_map[div['id']] = {
+            'div_name': div['name'],
+            'teams': [
+                _parse_team_record(tr, is_wild_card=False)
+                for tr in div['teams']
+            ]
+        }
+
+    # AL IDs: East(201), Central(202), West(200)
+    # NL IDs: East(204), Central(205), West(203)
+    al_divs = [div_map.get(201), div_map.get(202), div_map.get(200)]
+    nl_divs = [div_map.get(204), div_map.get(205), div_map.get(203)]
+
+    al_wc = fetch_wild_card(103)
+    nl_wc = fetch_wild_card(104)
+
+    result = (al_divs, nl_divs, al_wc, nl_wc)
+    set_cached_data(cache_key, result, ttl=LIVE_DATA_TTL)
+    return result