datafc 2.7.2__tar.gz → 2.9.0__tar.gz

datafc-2.9.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: datafc
+Version: 2.9.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,clubelo,eloratings,elo
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: curl_cffi>=0.7
+Requires-Dist: openpyxl>=3.0
+Requires-Dist: beautifulsoup4>=4.11
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=12.0; extra == "parquet"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: pandas-stubs>=2.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Dynamic: license-file
+
+# 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-2.9.0/README.md

@@ -0,0 +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-2.7.2 → datafc-2.9.0}/datafc/__init__.py

@@ -1,8 +1,9 @@
-__version__ = "2.7.2"
+__version__ = "2.9.0"
 
 from .sofascore import *
 from . import clubelo
 from . import eloratings
+from . import tff
 from .exceptions import (
     DataFCError,
     InvalidParameterError,
@@ -50,6 +51,7 @@ __all__ = [
     "incidents_data",
     "average_positions_data",
     "coordinates_data",
+    "rating_breakdown_data",
     "goal_networks_data",
     "past_matches_data",
     # Player
@@ -67,6 +69,8 @@ __all__ = [
     "clubelo",
     # EloRatings subpackage
     "eloratings",
+    # TFF subpackage
+    "tff",
     # Exceptions
     "DataFCError",
     "InvalidParameterError",

{datafc-2.7.2 → datafc-2.9.0}/datafc/sofascore/__init__.py

@@ -6,6 +6,7 @@ from .fetch_goal_networks_data import goal_networks_data
 from .fetch_formations_data import formations_data
 from .fetch_lineups_data import lineups_data
 from .fetch_coordinates_data import coordinates_data
+from .fetch_rating_breakdown_data import rating_breakdown_data
 from .fetch_substitutions_data import substitutions_data
 from .fetch_incidents_data import incidents_data
 from .fetch_match_details_data import match_details_data
@@ -59,6 +60,7 @@ __all__ = [
     # Player-level
     "lineups_data",
     "coordinates_data",
+    "rating_breakdown_data",
     "player_career_stats_data",
     "player_transfers_data",
     # League / season-level

{datafc-2.7.2 → datafc-2.9.0}/datafc/sofascore/_core.py

@@ -815,3 +815,45 @@ def heatmap_records(data: dict, row: pd.Series) -> list:
         for point in data.get("heatmap", [])
         if isinstance(point, dict) and "x" in point and "y" in point
     ]
+
+
+_RATING_BREAKDOWN_CATEGORIES = ("passes", "dribbles", "defensive", "ball-carries")
+
+
+def rating_breakdown_records(data: dict, row: pd.Series) -> list:
+    """rating_breakdown_data per-player action parser.
+
+    Flattens the four action buckets returned by the endpoint
+    (``passes``, ``dribbles``, ``defensive``, ``ball-carries``) into one row
+    per action, carrying start/end coordinates and outcome flags.
+    """
+    out = []
+    for category in _RATING_BREAKDOWN_CATEGORIES:
+        actions = data.get(category) or []
+        for action in actions:
+            if not isinstance(action, dict):
+                continue
+            player_coords = action.get("playerCoordinates") or {}
+            pass_end = action.get("passEndCoordinates") or {}
+            out.append({
+                "country": row["country"],
+                "tournament": row["tournament"],
+                "season": row["season"],
+                "week": row["week"],
+                "game_id": row["game_id"],
+                "team": row["team"],
+                "player_id": row["player_id"],
+                "player_name": row["player_name"],
+                "category": category,
+                "event_action_type": action.get("eventActionType"),
+                "is_home": action.get("isHome"),
+                "outcome": action.get("outcome"),
+                "keypass": action.get("keypass"),
+                "is_assist": action.get("isAssist"),
+                "is_long_ball": action.get("isLongBall"),
+                "player_x": player_coords.get("x"),
+                "player_y": player_coords.get("y"),
+                "pass_end_x": pass_end.get("x"),
+                "pass_end_y": pass_end.get("y"),
+            })
+    return out

{datafc-2.7.2 → datafc-2.9.0}/datafc/sofascore/aio.py

@@ -37,6 +37,7 @@ from datafc.sofascore._core import (
     goal_networks_post_process,
     heatmap_records,
     iter_per_match_async,
+    rating_breakdown_records,
     match_log_records_from_response,
     needs_world_cup_resolution,
     past_match_record_from_event,
@@ -513,6 +514,56 @@ async def coordinates_data(
     return result_df
 
 
+async 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:
+    """Async version of rating_breakdown_data(). Players with no data 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.")
+
+    sem = asyncio.Semaphore(1)
+    base = API_URLS[data_source]
+
+    async def _fetch(client, row):
+        url = f"{base}/api/v1/event/{row['game_id']}/player/{row['player_id']}/rating-breakdown"
+        async with sem:
+            try:
+                data = await client.get(url)
+            except APIError as exc:
+                if exc.status_code in (404, 403):
+                    return []
+                raise
+        return rating_breakdown_records(data, row)
+
+    async with AsyncSofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+        batches = await asyncio.gather(*[_fetch(client, row) for _, row in unique_players.iterrows()])
+
+    records = [rec for batch in batches for rec in batch]
+    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
+
+
 async def goal_networks_data(
     match_df: pd.DataFrame,
     data_source: str = "sofascore",

datafc-2.9.0/datafc/sofascore/fetch_rating_breakdown_data.py

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

datafc-2.9.0/datafc/tff/__init__.py

@@ -0,0 +1,40 @@
+from datafc.utils._config import (
+    get_tff_base_url,
+    reset_tff_base_url,
+    set_tff_base_url,
+)
+
+from .fetch_fixtures_data import fixtures_data
+from .fetch_match_cards_data import match_cards_data
+from .fetch_match_details_data import match_details_data
+from .fetch_match_goals_data import match_goals_data
+from .fetch_match_lineups_data import match_lineups_data
+from .fetch_match_staff_data import match_staff_data
+from .fetch_player_cards_data import player_cards_data
+from .fetch_player_career_data import player_career_data
+from .fetch_player_data import player_data
+from .fetch_player_goals_data import player_goals_data
+from .fetch_player_matches_data import player_matches_data
+from .fetch_player_national_matches_data import player_national_matches_data
+from .fetch_standings_data import standings_data
+from .fetch_team_data import team_data
+
+__all__ = [
+    "fixtures_data",
+    "standings_data",
+    "match_details_data",
+    "match_lineups_data",
+    "match_staff_data",
+    "match_goals_data",
+    "match_cards_data",
+    "player_data",
+    "player_career_data",
+    "player_national_matches_data",
+    "player_goals_data",
+    "player_matches_data",
+    "player_cards_data",
+    "team_data",
+    "get_tff_base_url",
+    "set_tff_base_url",
+    "reset_tff_base_url",
+]