datafc 2.5.0__tar.gz → 2.7.0__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.5.0
+Version: 2.7.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/urazakgul/datafc
 Project-URL: Repository, https://github.com/urazakgul/datafc
 Project-URL: Issues, https://github.com/urazakgul/datafc/issues
-Keywords: football,soccer,data,analytics,sofascore
+Keywords: football,soccer,data,analytics,sofascore,clubelo,eloratings,elo
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -24,16 +24,27 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.5.0
+# datafc v2.7.0
 
 ## Overview
 
-`datafc` fetches, processes, and exports structured football data. It provides **33 functions** covering tournament metadata, standings, squad rosters, match fixtures, shots, lineups, player heatmaps, odds, and more — all returning clean `pandas` DataFrames ready for analysis. Sofascore is currently the only supported data source.
+`datafc` fetches, processes, and exports structured football data. It provides **45 functions** covering tournament metadata, standings, squad rosters, match fixtures, shots, lineups, player heatmaps, odds, club & national-team Elo ratings, and more — all returning clean `pandas` DataFrames ready for analysis. Sofascore, ClubElo, and eloratings.net are the supported data sources.
 
 > **Finding IDs:** `tournament_id` and `season_id` can be discovered two ways:
 > - **From the URL:** navigating to a league page on Sofascore (e.g. `sofascore.com/.../trendyol-super-lig/52#id:63814`) shows `tournament_id=52` and `season_id=63814`.
 > - **Programmatically:** use `search_data("super lig", entity_type="tournament")` to find the tournament ID, then `seasons_data(tournament_id)` to list all available seasons.
 
+---
+
+<p align="center">
+  If you find <strong>datafc</strong> useful, consider supporting the project ☕<br><br>
+  <a href="https://buymeacoffee.com/urazdev">
+    <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-urazdev-%23FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
+  </a>
+</p>
+
+---
+
 ## What Data Can You Access?
 
 ### Discovery
@@ -69,6 +80,7 @@ Dynamic: license-file
 |---|---|
 | `match_data` | Fixtures for a matchweek: score, status, home/away teams |
 | `match_details_data` | Referee info (name, cards, games) and venue details per match |
+| `formations_data` | Home and away formation for each match |
 | `match_stats_data` | Aggregate team stats per match (possession, shots, fouls, …) |
 | `match_odds_data` | Pre-match 1/X/2 betting odds |
 | `match_h2h_data` | All-time H2H record between the two teams |
@@ -100,6 +112,26 @@ Dynamic: license-file
 |---|---|
 | `referee_stats_data` | Career stats for a referee: games, cards, and per-game averages |
 
+### ClubElo
+
+| Function | What it returns |
+|---|---|
+| `clubelo.daily_ranking_data` | Full ClubElo ranking for a given calendar day (since 1939) |
+| `clubelo.club_history_data` | Complete Elo rating history for a single club |
+| `clubelo.fixtures_data` | Per-goal-difference and exact-result probabilities for upcoming matches |
+
+### EloRatings (national teams)
+
+| Function | What it returns |
+|---|---|
+| `eloratings.world_ranking_data` | Current global Elo ranking for all national teams |
+| `eloratings.country_matches_data` | Complete international match history for a national team |
+| `eloratings.country_codes_data` | Country code → English country name reference |
+| `eloratings.tournament_codes_data` | Tournament code → English tournament name reference |
+| `eloratings.tournament_editions_data` | Every tournament edition with start/end dates and page slug |
+| `eloratings.tournament_groups_data` | Specific tournament code → broader group code (e.g. all WC qualifier variants → `WQT`) |
+| `eloratings.teams_data` | Legacy/historical country code → ISO code mapping |
+
 > **Coverage:** Any league and season available on Sofascore. For Turkey Super Lig, every season from 1980/81 to the present is accessible.
 
 ## Installation
@@ -580,6 +612,22 @@ Dependencies: `match_data`
 
 ---
 
+#### `formations_data`
+
+Fetch home and away formation for each match.
+
+```python
+from datafc import formations_data
+
+df = formations_data(match_df=match_df)
+```
+
+Columns: `country`, `tournament`, `season`, `week`, `game_id`, `team` (`home` / `away`), `formation`.
+
+Dependencies: `match_data`
+
+---
+
 #### `match_stats_data`
 
 Fetch aggregate team statistics (possession, shots, passes, etc.) for each match.
@@ -933,8 +981,106 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ---
 
+### ClubElo
+
+ClubElo (<https://clubelo.com>) maintains daily Elo ratings for European clubs going back to 1939. Three functions wrap the public API; all return `pandas` DataFrames.
+
+```python
+from datafc import clubelo
+
+# Full ranking on a given day
+df = clubelo.daily_ranking_data("2026-06-10")
+
+# A single club's full Elo history (use the spelling shown in daily_ranking_data)
+hist = clubelo.club_history_data("Man City")
+
+# Upcoming matches with per-goal-difference and exact-result probabilities
+fix = clubelo.fixtures_data()
+```
+
+Common parameters: `rate_limit` (default `2.0` req/s) and `cache` (any `DiskCache` instance, shared with the Sofascore functions).
+
+> **Notes:**
+> - Club names must match ClubElo's spelling exactly (e.g. `"Man City"`, `"Real Madrid"`, `"Paris SG"`). Run `daily_ranking_data` first and check the `club` column.
+> - Values before 1960 are considered provisional by ClubElo.
+> - Dates accept either `"YYYY-MM-DD"` strings or `datetime.date` objects.
+
+If the default `https://api.clubelo.com` is unreachable from your network (some corporate firewalls block port 443 to this host while leaving port 80 open), override the base URL once at startup:
+
+```python
+from datafc import clubelo
+clubelo.set_clubelo_base_url("http://api.clubelo.com")
+```
+
+`clubelo.reset_clubelo_base_url()` restores the default.
+
+---
+
+### EloRatings (national teams)
+
+[eloratings.net](https://www.eloratings.net) maintains daily Elo ratings for national teams going back to 1872. Seven functions wrap the site's underlying `.tsv` data files; all return `pandas` DataFrames.
+
+```python
+from datafc import eloratings
+
+# Current global ranking of all national teams (30 columns)
+df = eloratings.world_ranking_data()
+
+# Full match history for a single national team
+matches = eloratings.country_matches_data("Spain")
+
+# Code reference tables (handy for joining onto the above)
+countries = eloratings.country_codes_data()         # country_code → country_name
+tournaments = eloratings.tournament_codes_data()    # tournament_code → tournament_name
+groups = eloratings.tournament_groups_data()        # specific code → group code (long format)
+editions = eloratings.tournament_editions_data()    # every tournament edition + dates + slug
+
+# Legacy/historical country code → ISO code mapping
+teams = eloratings.teams_data()
+
+# Example: enrich Spain's matches with full tournament names
+spain = (
+    eloratings.country_matches_data("Spain")
+    .merge(tournaments, left_on="tournament", right_on="tournament_code", how="left")
+)
+
+# Example: every World Cup final tournament (filter editions on the WC group)
+wc_finals = editions[(editions["code"] == "WC") & editions["start_date"].notna()]
+```
+
+Common parameters: `rate_limit` (default `2.0` req/s) and `cache` (same `DiskCache` instance as Sofascore/ClubElo).
+
+> **Column names are verified against the site's JavaScript source.**
+> eloratings.net does not publish a documented API; the `.tsv` files have no header row. Column names in `world_ranking_data` are derived from index→field assignments in `scripts/ratings.js`; the remaining files are cross-checked against the live site's display. The ``WORLD_COLUMNS`` / ``COUNTRY_MATCH_COLUMNS`` lists in `datafc/eloratings/_parsers.py` document each position. If the site changes its layout, columns may be silently mis-labelled — please open an issue if you spot a discrepancy.
+
+> **Country argument is a page slug, not an ISO code.**
+> `country_matches_data("Spain")` calls `https://www.eloratings.net/Spain.tsv`. Use the same capitalisation and spelling shown in the URL of the country page on eloratings.net (e.g. `"Czech_Republic"`, `"United_States"`).
+
+Override the base URL the same way as ClubElo if needed:
+
+```python
+from datafc import eloratings
+eloratings.set_eloratings_base_url("http://www.eloratings.net")
+```
+
+---
+
 ## What's new
 
+### 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`.
+- **National-team Elo ratings via eloratings.net.** Pull the current global ranking of every national team, a country's full international match history (back to 1872), and the site's reference tables for resolving the two-letter country codes and tournament codes into full names. Seven functions under `datafc.eloratings`, including `world_ranking_data`, `country_matches_data`, `country_codes_data`, and `tournament_codes_data`.
+- **Shared caching across all sources.** ClubElo and eloratings.net responses use the same `DiskCache` you already pass to the Sofascore functions, so a single cache directory keeps every fetch persistent across sessions.
+
+---
+
+### v2.6.0
+
+- **New function: `formations_data`** — fetches home and away formation for each match. Returns two rows per match (`team`: `home` / `away`) with the formation string (e.g. `4-3-3`).
+
+---
+
 ### v2.5.0
 
 - **`player_data` now returns `position_detailed`.** New column containing Sofascore's detailed position list (e.g. `["AM", "MC", "RW"]`) alongside the existing single `position` field.

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

@@ -1,13 +1,24 @@
-# datafc v2.5.0
+# datafc v2.7.0
 
 ## Overview
 
-`datafc` fetches, processes, and exports structured football data. It provides **33 functions** covering tournament metadata, standings, squad rosters, match fixtures, shots, lineups, player heatmaps, odds, and more — all returning clean `pandas` DataFrames ready for analysis. Sofascore is currently the only supported data source.
+`datafc` fetches, processes, and exports structured football data. It provides **45 functions** covering tournament metadata, standings, squad rosters, match fixtures, shots, lineups, player heatmaps, odds, club & national-team Elo ratings, and more — all returning clean `pandas` DataFrames ready for analysis. Sofascore, ClubElo, and eloratings.net are the supported data sources.
 
 > **Finding IDs:** `tournament_id` and `season_id` can be discovered two ways:
 > - **From the URL:** navigating to a league page on Sofascore (e.g. `sofascore.com/.../trendyol-super-lig/52#id:63814`) shows `tournament_id=52` and `season_id=63814`.
 > - **Programmatically:** use `search_data("super lig", entity_type="tournament")` to find the tournament ID, then `seasons_data(tournament_id)` to list all available seasons.
 
+---
+
+<p align="center">
+  If you find <strong>datafc</strong> useful, consider supporting the project ☕<br><br>
+  <a href="https://buymeacoffee.com/urazdev">
+    <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-urazdev-%23FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
+  </a>
+</p>
+
+---
+
 ## What Data Can You Access?
 
 ### Discovery
@@ -43,6 +54,7 @@
 |---|---|
 | `match_data` | Fixtures for a matchweek: score, status, home/away teams |
 | `match_details_data` | Referee info (name, cards, games) and venue details per match |
+| `formations_data` | Home and away formation for each match |
 | `match_stats_data` | Aggregate team stats per match (possession, shots, fouls, …) |
 | `match_odds_data` | Pre-match 1/X/2 betting odds |
 | `match_h2h_data` | All-time H2H record between the two teams |
@@ -74,6 +86,26 @@
 |---|---|
 | `referee_stats_data` | Career stats for a referee: games, cards, and per-game averages |
 
+### ClubElo
+
+| Function | What it returns |
+|---|---|
+| `clubelo.daily_ranking_data` | Full ClubElo ranking for a given calendar day (since 1939) |
+| `clubelo.club_history_data` | Complete Elo rating history for a single club |
+| `clubelo.fixtures_data` | Per-goal-difference and exact-result probabilities for upcoming matches |
+
+### EloRatings (national teams)
+
+| Function | What it returns |
+|---|---|
+| `eloratings.world_ranking_data` | Current global Elo ranking for all national teams |
+| `eloratings.country_matches_data` | Complete international match history for a national team |
+| `eloratings.country_codes_data` | Country code → English country name reference |
+| `eloratings.tournament_codes_data` | Tournament code → English tournament name reference |
+| `eloratings.tournament_editions_data` | Every tournament edition with start/end dates and page slug |
+| `eloratings.tournament_groups_data` | Specific tournament code → broader group code (e.g. all WC qualifier variants → `WQT`) |
+| `eloratings.teams_data` | Legacy/historical country code → ISO code mapping |
+
 > **Coverage:** Any league and season available on Sofascore. For Turkey Super Lig, every season from 1980/81 to the present is accessible.
 
 ## Installation
@@ -554,6 +586,22 @@ Dependencies: `match_data`
 
 ---
 
+#### `formations_data`
+
+Fetch home and away formation for each match.
+
+```python
+from datafc import formations_data
+
+df = formations_data(match_df=match_df)
+```
+
+Columns: `country`, `tournament`, `season`, `week`, `game_id`, `team` (`home` / `away`), `formation`.
+
+Dependencies: `match_data`
+
+---
+
 #### `match_stats_data`
 
 Fetch aggregate team statistics (possession, shots, passes, etc.) for each match.
@@ -907,8 +955,106 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ---
 
+### ClubElo
+
+ClubElo (<https://clubelo.com>) maintains daily Elo ratings for European clubs going back to 1939. Three functions wrap the public API; all return `pandas` DataFrames.
+
+```python
+from datafc import clubelo
+
+# Full ranking on a given day
+df = clubelo.daily_ranking_data("2026-06-10")
+
+# A single club's full Elo history (use the spelling shown in daily_ranking_data)
+hist = clubelo.club_history_data("Man City")
+
+# Upcoming matches with per-goal-difference and exact-result probabilities
+fix = clubelo.fixtures_data()
+```
+
+Common parameters: `rate_limit` (default `2.0` req/s) and `cache` (any `DiskCache` instance, shared with the Sofascore functions).
+
+> **Notes:**
+> - Club names must match ClubElo's spelling exactly (e.g. `"Man City"`, `"Real Madrid"`, `"Paris SG"`). Run `daily_ranking_data` first and check the `club` column.
+> - Values before 1960 are considered provisional by ClubElo.
+> - Dates accept either `"YYYY-MM-DD"` strings or `datetime.date` objects.
+
+If the default `https://api.clubelo.com` is unreachable from your network (some corporate firewalls block port 443 to this host while leaving port 80 open), override the base URL once at startup:
+
+```python
+from datafc import clubelo
+clubelo.set_clubelo_base_url("http://api.clubelo.com")
+```
+
+`clubelo.reset_clubelo_base_url()` restores the default.
+
+---
+
+### EloRatings (national teams)
+
+[eloratings.net](https://www.eloratings.net) maintains daily Elo ratings for national teams going back to 1872. Seven functions wrap the site's underlying `.tsv` data files; all return `pandas` DataFrames.
+
+```python
+from datafc import eloratings
+
+# Current global ranking of all national teams (30 columns)
+df = eloratings.world_ranking_data()
+
+# Full match history for a single national team
+matches = eloratings.country_matches_data("Spain")
+
+# Code reference tables (handy for joining onto the above)
+countries = eloratings.country_codes_data()         # country_code → country_name
+tournaments = eloratings.tournament_codes_data()    # tournament_code → tournament_name
+groups = eloratings.tournament_groups_data()        # specific code → group code (long format)
+editions = eloratings.tournament_editions_data()    # every tournament edition + dates + slug
+
+# Legacy/historical country code → ISO code mapping
+teams = eloratings.teams_data()
+
+# Example: enrich Spain's matches with full tournament names
+spain = (
+    eloratings.country_matches_data("Spain")
+    .merge(tournaments, left_on="tournament", right_on="tournament_code", how="left")
+)
+
+# Example: every World Cup final tournament (filter editions on the WC group)
+wc_finals = editions[(editions["code"] == "WC") & editions["start_date"].notna()]
+```
+
+Common parameters: `rate_limit` (default `2.0` req/s) and `cache` (same `DiskCache` instance as Sofascore/ClubElo).
+
+> **Column names are verified against the site's JavaScript source.**
+> eloratings.net does not publish a documented API; the `.tsv` files have no header row. Column names in `world_ranking_data` are derived from index→field assignments in `scripts/ratings.js`; the remaining files are cross-checked against the live site's display. The ``WORLD_COLUMNS`` / ``COUNTRY_MATCH_COLUMNS`` lists in `datafc/eloratings/_parsers.py` document each position. If the site changes its layout, columns may be silently mis-labelled — please open an issue if you spot a discrepancy.
+
+> **Country argument is a page slug, not an ISO code.**
+> `country_matches_data("Spain")` calls `https://www.eloratings.net/Spain.tsv`. Use the same capitalisation and spelling shown in the URL of the country page on eloratings.net (e.g. `"Czech_Republic"`, `"United_States"`).
+
+Override the base URL the same way as ClubElo if needed:
+
+```python
+from datafc import eloratings
+eloratings.set_eloratings_base_url("http://www.eloratings.net")
+```
+
+---
+
 ## What's new
 
+### 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`.
+- **National-team Elo ratings via eloratings.net.** Pull the current global ranking of every national team, a country's full international match history (back to 1872), and the site's reference tables for resolving the two-letter country codes and tournament codes into full names. Seven functions under `datafc.eloratings`, including `world_ranking_data`, `country_matches_data`, `country_codes_data`, and `tournament_codes_data`.
+- **Shared caching across all sources.** ClubElo and eloratings.net responses use the same `DiskCache` you already pass to the Sofascore functions, so a single cache directory keeps every fetch persistent across sessions.
+
+---
+
+### v2.6.0
+
+- **New function: `formations_data`** — fetches home and away formation for each match. Returns two rows per match (`team`: `home` / `away`) with the formation string (e.g. `4-3-3`).
+
+---
+
 ### v2.5.0
 
 - **`player_data` now returns `position_detailed`.** New column containing Sofascore's detailed position list (e.g. `["AM", "MC", "RW"]`) alongside the existing single `position` field.

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

@@ -1,6 +1,8 @@
-__version__ = "2.5.0"
+__version__ = "2.7.0"
 
 from .sofascore import *
+from . import clubelo
+from . import eloratings
 from .exceptions import (
     DataFCError,
     InvalidParameterError,
@@ -36,6 +38,7 @@ __all__ = [
     # Matchweek
     "match_data",
     "match_details_data",
+    "formations_data",
     "match_stats_data",
     "match_odds_data",
     "match_h2h_data",
@@ -60,6 +63,10 @@ __all__ = [
     "referee_stats_data",
     # Async API
     "aio",
+    # ClubElo subpackage
+    "clubelo",
+    # EloRatings subpackage
+    "eloratings",
     # Exceptions
     "DataFCError",
     "InvalidParameterError",

datafc-2.7.0/datafc/clubelo/__init__.py

@@ -0,0 +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",
+]

datafc-2.7.0/datafc/clubelo/_client.py

@@ -0,0 +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()

datafc-2.7.0/datafc/clubelo/_parsers.py

@@ -0,0 +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"))

datafc-2.7.0/datafc/clubelo/fetch_club_history_data.py

@@ -0,0 +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)