datafc 2.6.0__tar.gz → 2.7.1__tar.gz

{datafc-2.6.0 → datafc-2.7.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.6.0
+Version: 2.7.1
 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,11 +24,11 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.6.0
+# datafc v2.7.1
 
 ## Overview
 
-`datafc` fetches, processes, and exports structured football data. It provides **35 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`.
@@ -112,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
@@ -560,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: `quarterfinals`, `semifinals`, `final`.
 
 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`.
 
@@ -823,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`.
@@ -961,8 +992,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.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`.
+- **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`).

{datafc-2.6.0 → datafc-2.7.1}/README.md

@@ -1,8 +1,8 @@
-# datafc v2.6.0
+# datafc v2.7.1
 
 ## Overview
 
-`datafc` fetches, processes, and exports structured football data. It provides **35 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`.
@@ -86,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
@@ -534,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: `quarterfinals`, `semifinals`, `final`.
 
 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`.
 
@@ -797,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`.
@@ -935,8 +966,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.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`.
+- **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`).

{datafc-2.6.0 → datafc-2.7.1}/datafc/__init__.py

@@ -1,6 +1,8 @@
-__version__ = "2.6.0"
+__version__ = "2.7.1"
 
 from .sofascore import *
+from . import clubelo
+from . import eloratings
 from .exceptions import (
     DataFCError,
     InvalidParameterError,
@@ -61,6 +63,10 @@ __all__ = [
     "referee_stats_data",
     # Async API
     "aio",
+    # ClubElo subpackage
+    "clubelo",
+    # EloRatings subpackage
+    "eloratings",
     # Exceptions
     "DataFCError",
     "InvalidParameterError",

datafc-2.7.1/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.1/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.1/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.1/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)

datafc-2.7.1/datafc/clubelo/fetch_daily_ranking_data.py

@@ -0,0 +1,48 @@
+from datetime import date as _date_cls
+from typing import TYPE_CHECKING, Optional, Union
+
+import pandas as pd
+
+from datafc.clubelo._client import ClubEloClient
+from datafc.clubelo._parsers import parse_daily_ranking
+from datafc.exceptions import InvalidParameterError
+from datafc.utils._config import get_clubelo_base_url
+
+if TYPE_CHECKING:
+    from datafc.utils._cache import DiskCache
+
+
+def _coerce_date(value: Union[str, _date_cls]) -> str:
+    if isinstance(value, _date_cls):
+        return value.strftime("%Y-%m-%d")
+    if isinstance(value, str):
+        try:
+            return _date_cls.fromisoformat(value).strftime("%Y-%m-%d")
+        except ValueError as exc:
+            raise InvalidParameterError(
+                f"date must be 'YYYY-MM-DD' or a datetime.date; got {value!r}."
+            ) from exc
+    raise InvalidParameterError(
+        f"date must be a string or datetime.date; got {type(value).__name__}."
+    )
+
+
+def daily_ranking_data(
+    date: Union[str, _date_cls],
+    rate_limit: float = 2.0,
+    cache: Optional["DiskCache"] = None,
+) -> pd.DataFrame:
+    """Fetches the full ClubElo ranking for the given calendar day.
+
+    Args:
+        date: 'YYYY-MM-DD' string or ``datetime.date``. Values before 1960 are
+            considered provisional by ClubElo.
+
+    Returns:
+        DataFrame with columns: ``query_date, rank, club, country, level, elo, from, to``.
+    """
+    date_str = _coerce_date(date)
+    url = f"{get_clubelo_base_url()}/{date_str}"
+    with ClubEloClient(rate_limit=rate_limit, cache=cache) as client:
+        text = client.get(url)
+    return parse_daily_ranking(text, date_str)