datafc 2.5.0__tar.gz → 2.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.5.0
+Version: 2.6.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -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.6.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 **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.
 
 > **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 |
@@ -580,6 +592,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.
@@ -935,6 +963,12 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## What's new
 
+### 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.6.0}/README.md

@@ -1,13 +1,24 @@
-# datafc v2.5.0
+# datafc v2.6.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 **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.
 
 > **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 |
@@ -554,6 +566,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.
@@ -909,6 +937,12 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## What's new
 
+### 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.6.0}/datafc/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.5.0"
+__version__ = "2.6.0"
 
 from .sofascore import *
 from .exceptions import (
@@ -36,6 +36,7 @@ __all__ = [
     # Matchweek
     "match_data",
     "match_details_data",
+    "formations_data",
     "match_stats_data",
     "match_odds_data",
     "match_h2h_data",

{datafc-2.5.0 → datafc-2.6.0}/datafc/sofascore/__init__.py

@@ -3,6 +3,7 @@ from .fetch_match_stats_data import match_stats_data
 from .fetch_standings_data import standings_data
 from .fetch_shots_data import shots_data
 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_substitutions_data import substitutions_data
@@ -47,6 +48,7 @@ __all__ = [
     "substitutions_data",
     "incidents_data",
     "match_details_data",
+    "formations_data",
     "upcoming_matches_data",
     "team_match_history_data",
     "goal_networks_data",

{datafc-2.5.0 → datafc-2.6.0}/datafc/sofascore/_parsers.py

@@ -162,6 +162,24 @@ def parse_momentum_records(
     ]
 
 
+def parse_formations_records(
+    data: dict, country: str, tournament: str, season, week, game_id
+) -> list:
+    """Extract home and away formation records from a single event's lineups response."""
+    records = []
+    for team_key in ("home", "away"):
+        team_data = data.get(team_key, {})
+        formation = team_data.get("formation")
+        if formation is not None:
+            records.append({
+                "country": country, "tournament": tournament,
+                "season": season, "week": week, "game_id": game_id,
+                "team": team_key,
+                "formation": formation,
+            })
+    return records
+
+
 def parse_lineups_records(
     data: dict, country: str, tournament: str, season, week, game_id
 ) -> list:

{datafc-2.5.0 → datafc-2.6.0}/datafc/sofascore/aio.py

@@ -57,6 +57,7 @@ from datafc.sofascore._core import (
 )
 from datafc.sofascore._parsers import (
     parse_average_positions_records,
+    parse_formations_records,
     parse_incidents_records,
     parse_league_player_stats_records,
     parse_lineups_records,
@@ -236,6 +237,28 @@ async def momentum_data(
     )
 
 
+async def formations_data(
+    match_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 formations_data()."""
+    return await _per_match_simple(
+        match_df, data_source, rate_limit, cache,
+        endpoint="{base}/api/v1/event/{game_id}/lineups",
+        parser=parse_formations_records,
+        log_label="formations",
+        fn_name="formations_data",
+        error_msg="No formation data found.",
+        enable_json_export=enable_json_export, enable_excel_export=enable_excel_export,
+        output_dir=output_dir,
+    )
+
+
 async def lineups_data(
     match_df: pd.DataFrame,
     data_source: str = "sofascore",

datafc-2.6.0/datafc/sofascore/fetch_formations_data.py

@@ -0,0 +1,44 @@
+from typing import TYPE_CHECKING, Optional
+import pandas as pd
+from datafc.utils._client import SofascoreClient
+from datafc.utils._validate import validate_source, validate_df
+from datafc.sofascore._parsers import parse_formations_records
+from datafc.sofascore._core import iter_per_match_sync, export_df
+from datafc.exceptions import DataNotAvailableError
+
+if TYPE_CHECKING:
+    from datafc.utils._cache import DiskCache
+
+
+def formations_data(
+    match_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 home and away formation for each match. Two rows per match."""
+    validate_source(data_source)
+    validate_df(match_df, "match_df")
+
+    with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+        records = iter_per_match_sync(
+            match_df, client,
+            data_source=data_source,
+            endpoint="{base}/api/v1/event/{game_id}/lineups",
+            parser=parse_formations_records,
+            log_label="formations",
+        )
+
+    result_df = pd.DataFrame(records)
+    if result_df.empty:
+        raise DataNotAvailableError("No formation data found for the specified parameters.")
+
+    export_df(
+        result_df, fn_name="formations_data", data_source=data_source,
+        output_dir=output_dir,
+        enable_json_export=enable_json_export, enable_excel_export=enable_excel_export,
+    )
+    return result_df

{datafc-2.5.0 → datafc-2.6.0}/datafc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.5.0
+Version: 2.6.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -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.6.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 **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.
 
 > **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 |
@@ -580,6 +592,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.
@@ -935,6 +963,12 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## What's new
 
+### 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.6.0}/datafc.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ datafc/sofascore/_parsers.py
 datafc/sofascore/aio.py
 datafc/sofascore/fetch_average_positions_data.py
 datafc/sofascore/fetch_coordinates_data.py
+datafc/sofascore/fetch_formations_data.py
 datafc/sofascore/fetch_goal_networks_data.py
 datafc/sofascore/fetch_incidents_data.py
 datafc/sofascore/fetch_league_player_stats_data.py

{datafc-2.5.0 → datafc-2.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datafc"
-version = "2.5.0"
+version = "2.6.0"
 description = "Fetch, process, and export structured football data."
 readme = "README.md"
 license = { text = "MIT" }