datafc 2.9.0__tar.gz → 2.10.0__tar.gz

{datafc-2.9.0 → datafc-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.9.0
+Version: 2.10.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -25,7 +25,7 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.9.0
+# datafc v2.10.0
 
 Football data from **Sofascore**, **ClubElo**, **eloratings.net** (Elo since 1872) and **tff.org** (Turkish federation) as pandas DataFrames. 60 functions total, each with an async mirror under `datafc.aio`, optional `DiskCache`.
 
@@ -138,8 +138,8 @@ Süper Lig, 1. Lig, 2. Lig, 3. Lig.
 ### Discovery / league
 | Function | Purpose |
 | --- | --- |
-| `fixtures_data(page_id, week=None, group=None, playoff=False, round=None)` | weekly fixtures or play-off bracket |
-| `standings_data(page_id, week, group=None)` | league table (`group` required for 2. Lig / 3. Lig) |
+| `fixtures_data(page_id, week=None, group=None, playoff=False, round=None, stage=None)` | weekly fixtures or play-off bracket (`stage` picks a stage group, e.g. Süper Lig 2011/12 Süper Final) |
+| `standings_data(page_id, week, group=None, stage=None)` | league table (`group` required for 2. Lig / 3. Lig; `stage` picks a play-off table, e.g. Süper Lig 2011/12) |
 | `team_data(club_id)` | club profile |
 
 ### From `match_id`

{datafc-2.9.0 → datafc-2.10.0}/README.md

@@ -1,166 +1,166 @@
-# datafc v2.9.0
-
-Football data from **Sofascore**, **ClubElo**, **eloratings.net** (Elo since 1872) and **tff.org** (Turkish federation) as pandas DataFrames. 60 functions total, each with an async mirror under `datafc.aio`, optional `DiskCache`.
-
-```bash
-pip install datafc
-```
-
----
-
-## Sofascore — `from datafc import ...`
-
-Grouped by the argument each function needs. Chain them: id → root frame → derived frame.
-
-### Discovery
-| Function | Purpose |
-| --- | --- |
-| `search_data(query, entity_type=None)` | search teams, players, tournaments, managers |
-| `seasons_data(tournament_id)` | every season of a tournament |
-| `season_rounds_data(tournament_id, season_id)` | defined matchweeks |
-
-### Root (id-driven)
-| Function | Purpose |
-| --- | --- |
-| `standings_data(tournament_id, season_id)` | Total / Home / Away table |
-| `match_data(tournament_id, season_id, week_number=None, tournament_type=None, tournament_stage=None)` | fixtures + scores |
-| `past_matches_data(...)` | same signature; H2H history per pair |
-| `team_match_history_data(team_id)` | full match history for one team |
-| `league_player_stats_data(tournament_id, season_id, order='-rating', accumulation='total', fields=None, position=None, max_players=100)` | wide-format player leaderboard |
-| `referee_stats_data(referee_id)` | per-tournament career stats |
-
-`tournament_type` ∈ `{"uefa", "world_cup", "league_playoff"}` with matching `tournament_stage` (`group_stage_week`, `round_of_16`, `quarterfinals`, `semifinals`, `final`, …).
-
-### From `standings_df`
-| Function | Purpose |
-| --- | --- |
-| `team_data(standings_df)` | profile, kits, manager, venue |
-| `team_stats_data(standings_df, tournament_id, season_id, season=None)` | season team stats (long) |
-| `team_transfers_data(standings_df)` | team transfer log |
-| `player_stats_data(standings_df, tournament_id, season_id)` | top players per team |
-| `squad_data(standings_df)` | full roster |
-| `upcoming_matches_data(standings_df)` | upcoming fixtures |
-
-### From `match_df`
-| Function | Purpose |
-| --- | --- |
-| `match_details_data` | referee + venue |
-| `formations_data` | formation strings |
-| `match_stats_data` | team stats per match |
-| `match_odds_data` | 1/X/2 odds |
-| `match_h2h_data` | head-to-head record |
-| `momentum_data` | minute-by-minute momentum |
-| `pregame_form_data` | last-5 form, rating, position, market value |
-| `shots_data` | every shot (xG, xGOT, body part, situation) |
-| `lineups_data` | XI + subs + per-match player stats |
-| `substitutions_data` | substitutions |
-| `incidents_data` | goals, cards, VAR |
-| `average_positions_data` | average pitch position (X/Y) |
-| `goal_networks_data` | coordinates for every action in a goal sequence |
-
-### From `lineups_df`
-| Function | Purpose |
-| --- | --- |
-| `coordinates_data(lineups_df)` | touch heatmap per player |
-| `rating_breakdown_data(lineups_df)` | every pass / dribble / defensive action / ball-carry with start-end coordinates and outcome flags |
-
-### From `squad_df`
-| Function | Purpose |
-| --- | --- |
-| `player_data` | profile |
-| `player_attribute_overviews_data` | radar attributes + baselines |
-| `player_transfers_data` | transfer history |
-| `player_career_stats_data` | season-by-season career stats |
-| `player_national_team_data` | international career |
-| `player_match_log_data` | match-by-match in-game stats (wide) |
-
----
-
-## ClubElo — `from datafc import clubelo`
-
-Club names use ClubElo spelling (`Man City`, `Real Madrid`, `Paris SG`).
-
-| Function | Purpose |
-| --- | --- |
-| `daily_ranking_data(date)` | full ranking on a calendar day (`"YYYY-MM-DD"` or `date`) |
-| `club_history_data(club)` | Elo history for one club (pre-1960 values are provisional) |
-| `fixtures_data()` | probability grid for upcoming matches |
-
----
-
-## EloRatings — `from datafc import eloratings`
-
-Country arguments are page slugs (`Czech_Republic`, `United_States`).
-
-| Function | Purpose |
-| --- | --- |
-| `world_ranking_data()` | current national-team ranking |
-| `country_matches_data(country)` | full international match history |
-| `country_codes_data()` | code → country |
-| `tournament_codes_data()` | code → tournament |
-| `tournament_editions_data()` | edition list with dates + slugs |
-| `tournament_groups_data()` | subcode → group code (e.g. WC qualifiers → `WQT`) |
-| `teams_data()` | legacy country code → ISO |
-
----
-
-## TFF — `from datafc import tff`
-
-Süper Lig, 1. Lig, 2. Lig, 3. Lig.
-
-### Discovery / league
-| Function | Purpose |
-| --- | --- |
-| `fixtures_data(page_id, week=None, group=None, playoff=False, round=None)` | weekly fixtures or play-off bracket |
-| `standings_data(page_id, week, group=None)` | league table (`group` required for 2. Lig / 3. Lig) |
-| `team_data(club_id)` | club profile |
-
-### From `match_id`
-| Function | Purpose |
-| --- | --- |
-| `match_details_data` | teams, score, officials |
-| `match_lineups_data` | XI + bench |
-| `match_staff_data` | head coaches |
-| `match_goals_data` | goals with type (`F`/`H`/`P`/`K`/`KG`) |
-| `match_cards_data` | bookings (yellow / red / second_yellow) |
-
-### From `player_id`
-| Function | Purpose |
-| --- | --- |
-| `player_data` | profile (licence, current club) |
-| `player_career_data` | licence history |
-| `player_national_matches_data` | national-team appearances |
-| `player_goals_data` | every recorded goal |
-| `player_matches_data(player_id, season)` | club matches in a season (`"2025-2026"`) |
-| `player_cards_data(player_id, season)` | bookings in a season |
-
----
-
-## Async
-
-Every function has a mirror in `datafc.aio` with the same signature:
-
-```python
-import asyncio
-from datafc import aio
-
-async def main():
-    tasks = [aio.match_data(52, 63814, week_number=w) for w in range(1, 39)]
-    return await asyncio.gather(*tasks, return_exceptions=True)
-
-asyncio.run(main())
-```
-
-## Cache
-
-```python
-from datafc import DiskCache
-
-cache = DiskCache(cache_dir=".datafc_cache", ttl_hours=24)
-```
-
-Pass `cache=cache` to any function. `ttl_hours=0` disables expiry; `cache.clear()` empties it.
-
-## Exceptions
-
-`DataFCError` (base), `InvalidParameterError`, `APIError`, `RateLimitError`, `ServerError`, `DataNotAvailableError`.
+# datafc v2.10.0
+
+Football data from **Sofascore**, **ClubElo**, **eloratings.net** (Elo since 1872) and **tff.org** (Turkish federation) as pandas DataFrames. 60 functions total, each with an async mirror under `datafc.aio`, optional `DiskCache`.
+
+```bash
+pip install datafc
+```
+
+---
+
+## Sofascore — `from datafc import ...`
+
+Grouped by the argument each function needs. Chain them: id → root frame → derived frame.
+
+### Discovery
+| Function | Purpose |
+| --- | --- |
+| `search_data(query, entity_type=None)` | search teams, players, tournaments, managers |
+| `seasons_data(tournament_id)` | every season of a tournament |
+| `season_rounds_data(tournament_id, season_id)` | defined matchweeks |
+
+### Root (id-driven)
+| Function | Purpose |
+| --- | --- |
+| `standings_data(tournament_id, season_id)` | Total / Home / Away table |
+| `match_data(tournament_id, season_id, week_number=None, tournament_type=None, tournament_stage=None)` | fixtures + scores |
+| `past_matches_data(...)` | same signature; H2H history per pair |
+| `team_match_history_data(team_id)` | full match history for one team |
+| `league_player_stats_data(tournament_id, season_id, order='-rating', accumulation='total', fields=None, position=None, max_players=100)` | wide-format player leaderboard |
+| `referee_stats_data(referee_id)` | per-tournament career stats |
+
+`tournament_type` ∈ `{"uefa", "world_cup", "league_playoff"}` with matching `tournament_stage` (`group_stage_week`, `round_of_16`, `quarterfinals`, `semifinals`, `final`, …).
+
+### From `standings_df`
+| Function | Purpose |
+| --- | --- |
+| `team_data(standings_df)` | profile, kits, manager, venue |
+| `team_stats_data(standings_df, tournament_id, season_id, season=None)` | season team stats (long) |
+| `team_transfers_data(standings_df)` | team transfer log |
+| `player_stats_data(standings_df, tournament_id, season_id)` | top players per team |
+| `squad_data(standings_df)` | full roster |
+| `upcoming_matches_data(standings_df)` | upcoming fixtures |
+
+### From `match_df`
+| Function | Purpose |
+| --- | --- |
+| `match_details_data` | referee + venue |
+| `formations_data` | formation strings |
+| `match_stats_data` | team stats per match |
+| `match_odds_data` | 1/X/2 odds |
+| `match_h2h_data` | head-to-head record |
+| `momentum_data` | minute-by-minute momentum |
+| `pregame_form_data` | last-5 form, rating, position, market value |
+| `shots_data` | every shot (xG, xGOT, body part, situation) |
+| `lineups_data` | XI + subs + per-match player stats |
+| `substitutions_data` | substitutions |
+| `incidents_data` | goals, cards, VAR |
+| `average_positions_data` | average pitch position (X/Y) |
+| `goal_networks_data` | coordinates for every action in a goal sequence |
+
+### From `lineups_df`
+| Function | Purpose |
+| --- | --- |
+| `coordinates_data(lineups_df)` | touch heatmap per player |
+| `rating_breakdown_data(lineups_df)` | every pass / dribble / defensive action / ball-carry with start-end coordinates and outcome flags |
+
+### From `squad_df`
+| Function | Purpose |
+| --- | --- |
+| `player_data` | profile |
+| `player_attribute_overviews_data` | radar attributes + baselines |
+| `player_transfers_data` | transfer history |
+| `player_career_stats_data` | season-by-season career stats |
+| `player_national_team_data` | international career |
+| `player_match_log_data` | match-by-match in-game stats (wide) |
+
+---
+
+## ClubElo — `from datafc import clubelo`
+
+Club names use ClubElo spelling (`Man City`, `Real Madrid`, `Paris SG`).
+
+| Function | Purpose |
+| --- | --- |
+| `daily_ranking_data(date)` | full ranking on a calendar day (`"YYYY-MM-DD"` or `date`) |
+| `club_history_data(club)` | Elo history for one club (pre-1960 values are provisional) |
+| `fixtures_data()` | probability grid for upcoming matches |
+
+---
+
+## EloRatings — `from datafc import eloratings`
+
+Country arguments are page slugs (`Czech_Republic`, `United_States`).
+
+| Function | Purpose |
+| --- | --- |
+| `world_ranking_data()` | current national-team ranking |
+| `country_matches_data(country)` | full international match history |
+| `country_codes_data()` | code → country |
+| `tournament_codes_data()` | code → tournament |
+| `tournament_editions_data()` | edition list with dates + slugs |
+| `tournament_groups_data()` | subcode → group code (e.g. WC qualifiers → `WQT`) |
+| `teams_data()` | legacy country code → ISO |
+
+---
+
+## TFF — `from datafc import tff`
+
+Süper Lig, 1. Lig, 2. Lig, 3. Lig.
+
+### Discovery / league
+| Function | Purpose |
+| --- | --- |
+| `fixtures_data(page_id, week=None, group=None, playoff=False, round=None, stage=None)` | weekly fixtures or play-off bracket (`stage` picks a stage group, e.g. Süper Lig 2011/12 Süper Final) |
+| `standings_data(page_id, week, group=None, stage=None)` | league table (`group` required for 2. Lig / 3. Lig; `stage` picks a play-off table, e.g. Süper Lig 2011/12) |
+| `team_data(club_id)` | club profile |
+
+### From `match_id`
+| Function | Purpose |
+| --- | --- |
+| `match_details_data` | teams, score, officials |
+| `match_lineups_data` | XI + bench |
+| `match_staff_data` | head coaches |
+| `match_goals_data` | goals with type (`F`/`H`/`P`/`K`/`KG`) |
+| `match_cards_data` | bookings (yellow / red / second_yellow) |
+
+### From `player_id`
+| Function | Purpose |
+| --- | --- |
+| `player_data` | profile (licence, current club) |
+| `player_career_data` | licence history |
+| `player_national_matches_data` | national-team appearances |
+| `player_goals_data` | every recorded goal |
+| `player_matches_data(player_id, season)` | club matches in a season (`"2025-2026"`) |
+| `player_cards_data(player_id, season)` | bookings in a season |
+
+---
+
+## Async
+
+Every function has a mirror in `datafc.aio` with the same signature:
+
+```python
+import asyncio
+from datafc import aio
+
+async def main():
+    tasks = [aio.match_data(52, 63814, week_number=w) for w in range(1, 39)]
+    return await asyncio.gather(*tasks, return_exceptions=True)
+
+asyncio.run(main())
+```
+
+## Cache
+
+```python
+from datafc import DiskCache
+
+cache = DiskCache(cache_dir=".datafc_cache", ttl_hours=24)
+```
+
+Pass `cache=cache` to any function. `ttl_hours=0` disables expiry; `cache.clear()` empties it.
+
+## Exceptions
+
+`DataFCError` (base), `InvalidParameterError`, `APIError`, `RateLimitError`, `ServerError`, `DataNotAvailableError`.

{datafc-2.9.0 → datafc-2.10.0}/datafc/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.9.0"
+__version__ = "2.10.0"
 
 from .sofascore import *
 from . import clubelo

{datafc-2.9.0 → datafc-2.10.0}/datafc/sofascore/fetch_rating_breakdown_data.py

@@ -1,66 +1,66 @@
-from typing import TYPE_CHECKING, Optional
-import pandas as pd
-from datafc.utils._client import SofascoreClient
-from datafc.utils._config import API_URLS
-from datafc.utils._validate import validate_source, validate_df
-from datafc.sofascore._core import rating_breakdown_records, export_df
-from datafc.exceptions import APIError, DataNotAvailableError, InvalidParameterError
-
-if TYPE_CHECKING:
-    from datafc.utils._cache import DiskCache
-
-
-def rating_breakdown_data(
-    lineups_df: pd.DataFrame,
-    data_source: str = "sofascore",
-    rate_limit: float = 2.0,
-    cache: Optional["DiskCache"] = None,
-    enable_json_export: bool = False,
-    enable_excel_export: bool = False,
-    output_dir: str = ".",
-) -> pd.DataFrame:
-    """Fetches rating-breakdown action data for each player in the provided lineup dataset.
-
-    The endpoint returns four buckets — passes, dribbles, defensive actions and
-    ball carries — each with start (and optionally end) coordinates plus outcome
-    flags (``outcome``, ``keypass``, ``isAssist``, ``isLongBall``). Rows are
-    flattened so each action becomes a single record tagged with ``category``.
-
-    Players with no rating breakdown data (404/403) are silently skipped.
-    """
-    validate_source(data_source)
-    validate_df(lineups_df, "lineups_df")
-
-    unique_players = lineups_df[[
-        "country", "tournament", "season", "week", "game_id", "team", "player_id", "player_name"
-    ]].drop_duplicates()
-
-    if unique_players.empty:
-        raise InvalidParameterError("No unique players found in lineups_df.")
-
-    records = []
-    with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
-        for _, row in unique_players.iterrows():
-            url = (
-                f"{API_URLS[data_source]}/api/v1/event/{row['game_id']}"
-                f"/player/{row['player_id']}/rating-breakdown"
-            )
-            try:
-                data = client.get(url)
-            except APIError as exc:
-                if exc.status_code in (404, 403):
-                    continue
-                raise
-            records.extend(rating_breakdown_records(data, row))
-
-    result_df = pd.DataFrame(records)
-    if result_df.empty:
-        raise DataNotAvailableError("No rating breakdown data found for the specified players.")
-
-    export_df(
-        result_df, fn_name="rating_breakdown_data", data_source=data_source,
-        output_dir=output_dir,
-        first_row=lineups_df.iloc[0],
-        enable_json_export=enable_json_export, enable_excel_export=enable_excel_export,
-    )
-    return result_df
+from typing import TYPE_CHECKING, Optional
+import pandas as pd
+from datafc.utils._client import SofascoreClient
+from datafc.utils._config import API_URLS
+from datafc.utils._validate import validate_source, validate_df
+from datafc.sofascore._core import rating_breakdown_records, export_df
+from datafc.exceptions import APIError, DataNotAvailableError, InvalidParameterError
+
+if TYPE_CHECKING:
+    from datafc.utils._cache import DiskCache
+
+
+def rating_breakdown_data(
+    lineups_df: pd.DataFrame,
+    data_source: str = "sofascore",
+    rate_limit: float = 2.0,
+    cache: Optional["DiskCache"] = None,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False,
+    output_dir: str = ".",
+) -> pd.DataFrame:
+    """Fetches rating-breakdown action data for each player in the provided lineup dataset.
+
+    The endpoint returns four buckets — passes, dribbles, defensive actions and
+    ball carries — each with start (and optionally end) coordinates plus outcome
+    flags (``outcome``, ``keypass``, ``isAssist``, ``isLongBall``). Rows are
+    flattened so each action becomes a single record tagged with ``category``.
+
+    Players with no rating breakdown data (404/403) are silently skipped.
+    """
+    validate_source(data_source)
+    validate_df(lineups_df, "lineups_df")
+
+    unique_players = lineups_df[[
+        "country", "tournament", "season", "week", "game_id", "team", "player_id", "player_name"
+    ]].drop_duplicates()
+
+    if unique_players.empty:
+        raise InvalidParameterError("No unique players found in lineups_df.")
+
+    records = []
+    with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+        for _, row in unique_players.iterrows():
+            url = (
+                f"{API_URLS[data_source]}/api/v1/event/{row['game_id']}"
+                f"/player/{row['player_id']}/rating-breakdown"
+            )
+            try:
+                data = client.get(url)
+            except APIError as exc:
+                if exc.status_code in (404, 403):
+                    continue
+                raise
+            records.extend(rating_breakdown_records(data, row))
+
+    result_df = pd.DataFrame(records)
+    if result_df.empty:
+        raise DataNotAvailableError("No rating breakdown data found for the specified players.")
+
+    export_df(
+        result_df, fn_name="rating_breakdown_data", data_source=data_source,
+        output_dir=output_dir,
+        first_row=lineups_df.iloc[0],
+        enable_json_export=enable_json_export, enable_excel_export=enable_excel_export,
+    )
+    return result_df