feat: add shared HTTP sessions and configurable timeouts

mlbstatsapi/mlb_api.py

@@ -3,6 +3,8 @@
 
 from typing import List, Union
 
+import requests
+
 from mlbstatsapi.models.people import Person, Player, Coach
 from mlbstatsapi.models.teams import Team
 from mlbstatsapi.models.sports import Sport
@@ -20,7 +22,7 @@
 from mlbstatsapi.models.homerunderby import HomeRunDerby
 from mlbstatsapi.models.standings import Standings
 
-from .mlb_dataadapter import MlbDataAdapter
+from .mlb_dataadapter import DEFAULT_TIMEOUT, MlbDataAdapter, TimeoutType
 # from .exceptions import TheMlbStatsApiException
 from . import mlb_module
 
@@ -38,12 +40,51 @@ class Mlb:
     logger: logging.Loger
         logger
     """
-    def __init__(self, hostname: str = 'statsapi.mlb.com', logger: logging.Logger = None):
-        self._mlb_adapter_v1 = MlbDataAdapter(hostname, 'v1', logger)
-        self._mlb_adapter_v1_1 = MlbDataAdapter(hostname, 'v1.1', logger)
+    def __init__(
+        self,
+        hostname: str = 'statsapi.mlb.com',
+        logger: logging.Logger | None = None,
+        timeout: TimeoutType = DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ):
+        # One session is shared by the v1 and v1.1 adapters. The library closes
+        # only sessions it creates; caller-injected sessions remain caller-owned.
+        self._owns_session = session is None
+        self._session = session if session is not None else requests.Session()
+        self._closed = False
+        self._timeout = timeout
+        self._mlb_adapter_v1 = MlbDataAdapter(
+            hostname,
+            'v1',
+            logger,
+            timeout=timeout,
+            session=self._session,
+        )
+        self._mlb_adapter_v1_1 = MlbDataAdapter(
+            hostname,
+            'v1.1',
+            logger,
+            timeout=timeout,
+            session=self._session,
+        )
         self._logger = logger or logging.getLogger(__name__)
         self._logger.setLevel(logging.DEBUG)
 
+    def close(self) -> None:
+        """Close the HTTP session when this client owns it.
+
+        Safe to call more than once. Caller-injected sessions are left alone.
+        """
+        if self._owns_session and not self._closed:
+            self._session.close()
+            self._closed = True
+
+    def __enter__(self) -> "Mlb":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close()
+
     def get_people(self, sport_id: int = 1, **params) -> List[Person]:
         """
         return the all players for sportid

mlbstatsapi/mlb_dataadapter.py

@@ -1,9 +1,15 @@
 from typing import Dict
+
 from .exceptions import TheMlbStatsApiException
 import requests
 import logging
 
 
+# Connect timeout, then read timeout. Callers may override with a scalar or tuple.
+DEFAULT_TIMEOUT = (3.05, 30.0)
+TimeoutType = int | float | tuple[float, float]
+
+
 class MlbResult:
     """
     A class that holds data, status_code, and message returned from statsapi.mlb.com
@@ -46,9 +52,20 @@ class MlbDataAdapter:
         instance of logger class
     """
 
-    def __init__(self, hostname: str = 'statsapi.mlb.com', ver: str = 'v1', logger: logging.Logger = None):
+    def __init__(
+        self,
+        hostname: str = 'statsapi.mlb.com',
+        ver: str = 'v1',
+        logger: logging.Logger | None = None,
+        timeout: TimeoutType = DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ):
         self.url = f'https://{hostname}/api/{ver}/'
         self._logger = logger or logging.getLogger(__name__)
+        self._timeout = timeout
+        self._owns_session = session is None
+        self._session = session if session is not None else requests.Session()
+        self._closed = False
 
     def get(self, endpoint: str, ep_params: Dict = None, data: Dict = None) -> MlbResult:
         """
@@ -74,7 +91,11 @@ def get(self, endpoint: str, ep_params: Dict = None, data: Dict = None) -> MlbRe
 
         try:
             self._logger.debug(logline_post)
-            response = requests.get(url=full_url, params=ep_params)
+            response = self._session.get(
+                url=full_url,
+                params=ep_params,
+                timeout=self._timeout,
+            )
 
         except requests.exceptions.RequestException as e:
             self._logger.error(msg=(str(e)))
@@ -134,3 +155,12 @@ def get(self, endpoint: str, ep_params: Dict = None, data: Dict = None) -> MlbRe
             message=response.reason,
             data=response_data,
         )
+
+    def close(self) -> None:
+        """Close the HTTP session when this adapter owns it.
+
+        Safe to call more than once. Caller-injected sessions are left alone.
+        """
+        if self._owns_session and not self._closed:
+            self._session.close()
+            self._closed = True