datafc 2.7.0__tar.gz → 2.7.2__tar.gz

{datafc-2.7.0 → datafc-2.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.7.0
+Version: 2.7.2
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -24,7 +24,7 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.7.0
+# datafc v2.7.2
 
 ## Overview
 
@@ -580,17 +580,28 @@ wc_group_df = match_data(
     tournament_type="world_cup",
     tournament_stage="group_stage_week",
 )
+
+# Domestic league promotion playoff (e.g. TFF 1. Lig, EFL Championship):
+# use season_rounds_data to discover the round_number for each stage.
+playoff_df = match_data(
+    tournament_id=98,
+    season_id=<season_id>,
+    week_number=<round_number>,
+    tournament_type="league_playoff",
+    tournament_stage="final",
+)
 ```
 
 Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup. `None` assumes a domestic league.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, `world_cup` + `group_stage_week`, and all `league_playoff` stages. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup, `"league_playoff"` for domestic promotion playoffs. `None` assumes a domestic league.
 - `tournament_stage` (str, optional): Required when `tournament_type` is set.
   - `"uefa"` options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
   - `"world_cup"` options: `group_stage_week`, `round_of_32`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+  - `"league_playoff"` options: `qualification_round`, `quarterfinals`, `semifinals`, `final`. For `qualification_round`, `week_number` doubles as the round number in the slug (`1` → `qualification-round-1`, `2` → `qualification-round-2`).
 
 Columns: `country`, `tournament`, `season`, `week`, `game_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`, `injury_time_1`, `injury_time_2`, `start_timestamp`, `status`, `home_score_current`, `home_score_display`, `home_score_period1`, `home_score_period2`, `home_score_normaltime`, `away_score_current`, `away_score_display`, `away_score_period1`, `away_score_period2`, `away_score_normaltime`.
 
@@ -843,8 +854,8 @@ Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, `world_cup` + `group_stage_week`, and all `league_playoff` stages. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup, `"league_playoff"` for domestic promotion playoffs.
 - `tournament_stage` (str, optional): Required when `tournament_type` is set. Same options as `match_data`.
 
 Same columns as `match_data`.
@@ -1067,6 +1078,18 @@ eloratings.set_eloratings_base_url("http://www.eloratings.net")
 
 ## What's new
 
+### v2.7.2
+
+- **`league_playoff` gains `qualification_round`.** `match_data` and `past_matches_data` now cover the early elimination rounds of domestic promotion playoffs (e.g. TFF 1. Lig 1. and 2. eleme turu). `week_number` doubles as the round number in the slug (`1` → `qualification-round-1`, `2` → `qualification-round-2`), matching the existing UEFA `qualification_round` convention.
+
+---
+
+### v2.7.1
+
+- **New `tournament_type="league_playoff"`** for `match_data` and `past_matches_data`. Covers domestic promotion playoffs (e.g. TFF 1. Lig, EFL Championship) with `quarterfinals`, `semifinals`, and `final` stages. Use `season_rounds_data` to discover the `week_number` for each stage.
+
+---
+
 ### v2.7.0
 
 - **Club Elo ratings via ClubElo.** Pull daily Elo rankings of European clubs (going back to 1939), a single club's full rating history, and probability-based predictions for upcoming matches — all as `pandas` DataFrames. Three functions under `datafc.clubelo`: `daily_ranking_data`, `club_history_data`, `fixtures_data`.

{datafc-2.7.0 → datafc-2.7.2}/README.md

@@ -1,4 +1,4 @@
-# datafc v2.7.0
+# datafc v2.7.2
 
 ## Overview
 
@@ -554,17 +554,28 @@ wc_group_df = match_data(
     tournament_type="world_cup",
     tournament_stage="group_stage_week",
 )
+
+# Domestic league promotion playoff (e.g. TFF 1. Lig, EFL Championship):
+# use season_rounds_data to discover the round_number for each stage.
+playoff_df = match_data(
+    tournament_id=98,
+    season_id=<season_id>,
+    week_number=<round_number>,
+    tournament_type="league_playoff",
+    tournament_stage="final",
+)
 ```
 
 Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup. `None` assumes a domestic league.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, `world_cup` + `group_stage_week`, and all `league_playoff` stages. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup, `"league_playoff"` for domestic promotion playoffs. `None` assumes a domestic league.
 - `tournament_stage` (str, optional): Required when `tournament_type` is set.
   - `"uefa"` options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
   - `"world_cup"` options: `group_stage_week`, `round_of_32`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+  - `"league_playoff"` options: `qualification_round`, `quarterfinals`, `semifinals`, `final`. For `qualification_round`, `week_number` doubles as the round number in the slug (`1` → `qualification-round-1`, `2` → `qualification-round-2`).
 
 Columns: `country`, `tournament`, `season`, `week`, `game_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`, `injury_time_1`, `injury_time_2`, `start_timestamp`, `status`, `home_score_current`, `home_score_display`, `home_score_period1`, `home_score_period2`, `home_score_normaltime`, `away_score_current`, `away_score_display`, `away_score_period1`, `away_score_period2`, `away_score_normaltime`.
 
@@ -817,8 +828,8 @@ Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, `world_cup` + `group_stage_week`, and all `league_playoff` stages. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup, `"league_playoff"` for domestic promotion playoffs.
 - `tournament_stage` (str, optional): Required when `tournament_type` is set. Same options as `match_data`.
 
 Same columns as `match_data`.
@@ -1041,6 +1052,18 @@ eloratings.set_eloratings_base_url("http://www.eloratings.net")
 
 ## What's new
 
+### v2.7.2
+
+- **`league_playoff` gains `qualification_round`.** `match_data` and `past_matches_data` now cover the early elimination rounds of domestic promotion playoffs (e.g. TFF 1. Lig 1. and 2. eleme turu). `week_number` doubles as the round number in the slug (`1` → `qualification-round-1`, `2` → `qualification-round-2`), matching the existing UEFA `qualification_round` convention.
+
+---
+
+### v2.7.1
+
+- **New `tournament_type="league_playoff"`** for `match_data` and `past_matches_data`. Covers domestic promotion playoffs (e.g. TFF 1. Lig, EFL Championship) with `quarterfinals`, `semifinals`, and `final` stages. Use `season_rounds_data` to discover the `week_number` for each stage.
+
+---
+
 ### v2.7.0
 
 - **Club Elo ratings via ClubElo.** Pull daily Elo rankings of European clubs (going back to 1939), a single club's full rating history, and probability-based predictions for upcoming matches — all as `pandas` DataFrames. Three functions under `datafc.clubelo`: `daily_ranking_data`, `club_history_data`, `fixtures_data`.

{datafc-2.7.0 → datafc-2.7.2}/datafc/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.7.0"
+__version__ = "2.7.2"
 
 from .sofascore import *
 from . import clubelo

{datafc-2.7.0 → datafc-2.7.2}/datafc/clubelo/__init__.py

@@ -1,18 +1,18 @@
-from datafc.utils._config import (
-    get_clubelo_base_url,
-    reset_clubelo_base_url,
-    set_clubelo_base_url,
-)
-
-from .fetch_club_history_data import club_history_data
-from .fetch_daily_ranking_data import daily_ranking_data
-from .fetch_fixtures_data import fixtures_data
-
-__all__ = [
-    "daily_ranking_data",
-    "club_history_data",
-    "fixtures_data",
-    "get_clubelo_base_url",
-    "set_clubelo_base_url",
-    "reset_clubelo_base_url",
-]
+from datafc.utils._config import (
+    get_clubelo_base_url,
+    reset_clubelo_base_url,
+    set_clubelo_base_url,
+)
+
+from .fetch_club_history_data import club_history_data
+from .fetch_daily_ranking_data import daily_ranking_data
+from .fetch_fixtures_data import fixtures_data
+
+__all__ = [
+    "daily_ranking_data",
+    "club_history_data",
+    "fixtures_data",
+    "get_clubelo_base_url",
+    "set_clubelo_base_url",
+    "reset_clubelo_base_url",
+]

{datafc-2.7.0 → datafc-2.7.2}/datafc/clubelo/_client.py

@@ -1,112 +1,112 @@
-import logging
-import threading
-import time
-from typing import Optional
-
-from curl_cffi import requests as cf_requests
-
-from datafc.exceptions import APIError, RateLimitError, ServerError
-from datafc.utils._cache import get_default_cache
-
-logger = logging.getLogger(__name__)
-
-
-class ClubEloClient:
-    """
-    HTTP client for the ClubElo public API. Responses are CSV text.
-
-    Cached payloads are stored as ``{"csv": "<text>"}`` so they share the same
-    DiskCache backend used by SofascoreClient.
-
-    Args:
-        rate_limit: Maximum requests per second. Defaults to 2.0.
-        timeout: Request timeout in seconds. Defaults to 30.
-        retries: Number of retry attempts on transient errors. Defaults to 3.
-        cache: Optional DiskCache. Falls back to the module-level default cache.
-    """
-
-    _class_lock: threading.Lock = threading.Lock()
-    _class_last_request_time: float = 0.0
-
-    def __init__(
-        self,
-        rate_limit: float = 2.0,
-        timeout: int = 30,
-        retries: int = 3,
-        cache=None,
-    ) -> None:
-        self._min_interval = 1.0 / rate_limit if rate_limit > 0 else 0.0
-        self._timeout = timeout
-        self._retries = retries
-        self._cache = cache if cache is not None else get_default_cache()
-        self._session = cf_requests.Session(impersonate="chrome124")
-
-    def _rate_limit_wait(self) -> None:
-        with ClubEloClient._class_lock:
-            elapsed = time.monotonic() - ClubEloClient._class_last_request_time
-            if elapsed < self._min_interval:
-                time.sleep(self._min_interval - elapsed)
-            ClubEloClient._class_last_request_time = time.monotonic()
-
-    def get(self, url: str) -> str:
-        """Perform a GET, return the response body as CSV text."""
-        if self._cache is not None:
-            cached = self._cache.get(url)
-            if isinstance(cached, dict) and "csv" in cached:
-                logger.debug("Cache hit: %s", url)
-                return cached["csv"]
-
-        last_exc: Optional[Exception] = None
-
-        for attempt in range(1, self._retries + 1):
-            self._rate_limit_wait()
-            try:
-                response = self._session.get(url, timeout=self._timeout)
-
-                if response.status_code == 200:
-                    text = response.text
-                    if self._cache is not None:
-                        self._cache.set(url, {"csv": text})
-                    return text
-
-                if response.status_code == 429:
-                    wait = 2 ** attempt
-                    logger.warning(
-                        "Rate limited (429). Waiting %ds before retry %d/%d. URL: %s",
-                        wait, attempt, self._retries, url,
-                    )
-                    time.sleep(wait)
-                    last_exc = RateLimitError(429, url)
-                    continue
-
-                if response.status_code in (500, 502, 503, 504):
-                    wait = 2 ** attempt
-                    logger.warning(
-                        "Server error %d. Waiting %ds before retry %d/%d. URL: %s",
-                        response.status_code, wait, attempt, self._retries, url,
-                    )
-                    time.sleep(wait)
-                    last_exc = ServerError(response.status_code, url)
-                    continue
-
-                raise APIError(response.status_code, url)
-
-            except (APIError, RateLimitError, ServerError):
-                raise
-            except Exception as exc:
-                logger.warning("Request failed (attempt %d/%d): %s", attempt, self._retries, exc)
-                last_exc = exc
-                time.sleep(2 ** attempt)
-
-        if isinstance(last_exc, (RateLimitError, ServerError, APIError)):
-            raise last_exc
-        raise APIError(0, url, f"All {self._retries} attempts failed") from last_exc
-
-    def close(self) -> None:
-        self._session.close()
-
-    def __enter__(self) -> "ClubEloClient":
-        return self
-
-    def __exit__(self, *_) -> None:
-        self.close()
+import logging
+import threading
+import time
+from typing import Optional
+
+from curl_cffi import requests as cf_requests
+
+from datafc.exceptions import APIError, RateLimitError, ServerError
+from datafc.utils._cache import get_default_cache
+
+logger = logging.getLogger(__name__)
+
+
+class ClubEloClient:
+    """
+    HTTP client for the ClubElo public API. Responses are CSV text.
+
+    Cached payloads are stored as ``{"csv": "<text>"}`` so they share the same
+    DiskCache backend used by SofascoreClient.
+
+    Args:
+        rate_limit: Maximum requests per second. Defaults to 2.0.
+        timeout: Request timeout in seconds. Defaults to 30.
+        retries: Number of retry attempts on transient errors. Defaults to 3.
+        cache: Optional DiskCache. Falls back to the module-level default cache.
+    """
+
+    _class_lock: threading.Lock = threading.Lock()
+    _class_last_request_time: float = 0.0
+
+    def __init__(
+        self,
+        rate_limit: float = 2.0,
+        timeout: int = 30,
+        retries: int = 3,
+        cache=None,
+    ) -> None:
+        self._min_interval = 1.0 / rate_limit if rate_limit > 0 else 0.0
+        self._timeout = timeout
+        self._retries = retries
+        self._cache = cache if cache is not None else get_default_cache()
+        self._session = cf_requests.Session(impersonate="chrome124")
+
+    def _rate_limit_wait(self) -> None:
+        with ClubEloClient._class_lock:
+            elapsed = time.monotonic() - ClubEloClient._class_last_request_time
+            if elapsed < self._min_interval:
+                time.sleep(self._min_interval - elapsed)
+            ClubEloClient._class_last_request_time = time.monotonic()
+
+    def get(self, url: str) -> str:
+        """Perform a GET, return the response body as CSV text."""
+        if self._cache is not None:
+            cached = self._cache.get(url)
+            if isinstance(cached, dict) and "csv" in cached:
+                logger.debug("Cache hit: %s", url)
+                return cached["csv"]
+
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(1, self._retries + 1):
+            self._rate_limit_wait()
+            try:
+                response = self._session.get(url, timeout=self._timeout)
+
+                if response.status_code == 200:
+                    text = response.text
+                    if self._cache is not None:
+                        self._cache.set(url, {"csv": text})
+                    return text
+
+                if response.status_code == 429:
+                    wait = 2 ** attempt
+                    logger.warning(
+                        "Rate limited (429). Waiting %ds before retry %d/%d. URL: %s",
+                        wait, attempt, self._retries, url,
+                    )
+                    time.sleep(wait)
+                    last_exc = RateLimitError(429, url)
+                    continue
+
+                if response.status_code in (500, 502, 503, 504):
+                    wait = 2 ** attempt
+                    logger.warning(
+                        "Server error %d. Waiting %ds before retry %d/%d. URL: %s",
+                        response.status_code, wait, attempt, self._retries, url,
+                    )
+                    time.sleep(wait)
+                    last_exc = ServerError(response.status_code, url)
+                    continue
+
+                raise APIError(response.status_code, url)
+
+            except (APIError, RateLimitError, ServerError):
+                raise
+            except Exception as exc:
+                logger.warning("Request failed (attempt %d/%d): %s", attempt, self._retries, exc)
+                last_exc = exc
+                time.sleep(2 ** attempt)
+
+        if isinstance(last_exc, (RateLimitError, ServerError, APIError)):
+            raise last_exc
+        raise APIError(0, url, f"All {self._retries} attempts failed") from last_exc
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "ClubEloClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

{datafc-2.7.0 → datafc-2.7.2}/datafc/clubelo/_parsers.py

@@ -1,40 +1,40 @@
-from io import StringIO
-
-import pandas as pd
-
-from datafc.exceptions import DataNotAvailableError
-
-
-def _read_csv(text: str, *, context: str) -> pd.DataFrame:
-    if not text or not text.strip():
-        raise DataNotAvailableError(f"Empty response from ClubElo for {context}.")
-    df = pd.read_csv(StringIO(text))
-    if df.empty:
-        raise DataNotAvailableError(f"No rows returned from ClubElo for {context}.")
-    return df
-
-
-def _normalize_columns(df: pd.DataFrame) -> pd.DataFrame:
-    df.columns = [str(c).strip().lower() for c in df.columns]
-    return df
-
-
-def parse_daily_ranking(text: str, date: str) -> pd.DataFrame:
-    """Columns: rank, club, country, level, elo, from, to."""
-    df = _normalize_columns(_read_csv(text, context=f"date={date}"))
-    df.insert(0, "query_date", date)
-    return df
-
-
-def parse_club_history(text: str, club: str) -> pd.DataFrame:
-    """Columns: rank, club, country, level, elo, from, to (rank may be 'None')."""
-    df = _normalize_columns(_read_csv(text, context=f"club={club}"))
-    if "rank" in df.columns:
-        df["rank"] = pd.to_numeric(df["rank"], errors="coerce")
-    df.insert(0, "query_club", club)
-    return df
-
-
-def parse_fixtures(text: str) -> pd.DataFrame:
-    """Upcoming fixtures with per-goal-difference and exact-result probabilities."""
-    return _normalize_columns(_read_csv(text, context="fixtures"))
+from io import StringIO
+
+import pandas as pd
+
+from datafc.exceptions import DataNotAvailableError
+
+
+def _read_csv(text: str, *, context: str) -> pd.DataFrame:
+    if not text or not text.strip():
+        raise DataNotAvailableError(f"Empty response from ClubElo for {context}.")
+    df = pd.read_csv(StringIO(text))
+    if df.empty:
+        raise DataNotAvailableError(f"No rows returned from ClubElo for {context}.")
+    return df
+
+
+def _normalize_columns(df: pd.DataFrame) -> pd.DataFrame:
+    df.columns = [str(c).strip().lower() for c in df.columns]
+    return df
+
+
+def parse_daily_ranking(text: str, date: str) -> pd.DataFrame:
+    """Columns: rank, club, country, level, elo, from, to."""
+    df = _normalize_columns(_read_csv(text, context=f"date={date}"))
+    df.insert(0, "query_date", date)
+    return df
+
+
+def parse_club_history(text: str, club: str) -> pd.DataFrame:
+    """Columns: rank, club, country, level, elo, from, to (rank may be 'None')."""
+    df = _normalize_columns(_read_csv(text, context=f"club={club}"))
+    if "rank" in df.columns:
+        df["rank"] = pd.to_numeric(df["rank"], errors="coerce")
+    df.insert(0, "query_club", club)
+    return df
+
+
+def parse_fixtures(text: str) -> pd.DataFrame:
+    """Upcoming fixtures with per-goal-difference and exact-result probabilities."""
+    return _normalize_columns(_read_csv(text, context="fixtures"))

{datafc-2.7.0 → datafc-2.7.2}/datafc/clubelo/fetch_club_history_data.py

@@ -1,34 +1,34 @@
-from typing import TYPE_CHECKING, Optional
-
-import pandas as pd
-
-from datafc.clubelo._client import ClubEloClient
-from datafc.clubelo._parsers import parse_club_history
-from datafc.exceptions import InvalidParameterError
-from datafc.utils._config import get_clubelo_base_url
-
-if TYPE_CHECKING:
-    from datafc.utils._cache import DiskCache
-
-
-def club_history_data(
-    club: str,
-    rate_limit: float = 2.0,
-    cache: Optional["DiskCache"] = None,
-) -> pd.DataFrame:
-    """Fetches the full Elo rating history for one club.
-
-    Args:
-        club: Club name exactly as ClubElo spells it (use a daily ranking to
-            confirm the spelling, e.g. ``"Barcelona"``, ``"ManCity"``).
-
-    Returns:
-        DataFrame with columns: ``query_club, rank, club, country, level, elo, from, to``.
-    """
-    if not isinstance(club, str) or not club.strip():
-        raise InvalidParameterError("club must be a non-empty string.")
-    club_clean = club.strip()
-    url = f"{get_clubelo_base_url()}/{club_clean}"
-    with ClubEloClient(rate_limit=rate_limit, cache=cache) as client:
-        text = client.get(url)
-    return parse_club_history(text, club_clean)
+from typing import TYPE_CHECKING, Optional
+
+import pandas as pd
+
+from datafc.clubelo._client import ClubEloClient
+from datafc.clubelo._parsers import parse_club_history
+from datafc.exceptions import InvalidParameterError
+from datafc.utils._config import get_clubelo_base_url
+
+if TYPE_CHECKING:
+    from datafc.utils._cache import DiskCache
+
+
+def club_history_data(
+    club: str,
+    rate_limit: float = 2.0,
+    cache: Optional["DiskCache"] = None,
+) -> pd.DataFrame:
+    """Fetches the full Elo rating history for one club.
+
+    Args:
+        club: Club name exactly as ClubElo spells it (use a daily ranking to
+            confirm the spelling, e.g. ``"Barcelona"``, ``"ManCity"``).
+
+    Returns:
+        DataFrame with columns: ``query_club, rank, club, country, level, elo, from, to``.
+    """
+    if not isinstance(club, str) or not club.strip():
+        raise InvalidParameterError("club must be a non-empty string.")
+    club_clean = club.strip()
+    url = f"{get_clubelo_base_url()}/{club_clean}"
+    with ClubEloClient(rate_limit=rate_limit, cache=cache) as client:
+        text = client.get(url)
+    return parse_club_history(text, club_clean)