datafc 1.4.0__tar.gz → 1.5.0__tar.gz

{datafc-1.4.0 → datafc-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datafc
-Version: 1.4.0
+Version: 1.5.0
 Summary: A scalable Python library for fetching, processing, and exporting structured football match data.
 Home-page: https://github.com/urazakgul/datafc
 Author: Uraz Akgül
@@ -14,7 +14,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# datafc v1.4.0
+# datafc v1.5.0
 
 ## Overview
 
@@ -53,7 +53,7 @@ pip install git+https://github.com/urazakgul/datafc.git
 To install a specific version of `datafc`, use:
 
 ```bash
-pip install datafc==1.4.0
+pip install datafc==1.5.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -111,7 +111,10 @@ from datafc.sofascore import (
     substitutions_data,
     goal_networks_data,
     shots_data,
-    standings_data
+    standings_data,
+    team_stats_data,
+    player_stats_data,
+    squad_data
 )
 ```
 
@@ -141,10 +144,22 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
+### `standings_data`: A Foundation for Team and Player-Level Functions
+
 Exception: `standings_data` and `past_matches_data`
 
 Unlike other functions, `standings_data` and `past_matches_data` do not require `match_data` or `lineups_data`. They can be executed independently using only `tournament_id` and `season_id`. Additionally, `past_matches_data` includes an extra field: `week_number`.
 
+However, `standings_data` serves as a critical dependency for the following functions:
+
+* `team_stats_data`
+* `player_stats_data`
+* `squad_data`
+
+These functions rely on team-level metadata (such as `team_id`) provided by `standings_data` to fetch more granular data. Ensure that `standings_data` is successfully executed and includes teams with `category == 'Total'` before calling any of the above functions.
+
+`past_matches_data` also works independently and includes an extra field: `week_number`.
+
 ### Match Data
 
 #### `match_data`
@@ -864,8 +879,182 @@ Dependencies:
 
 * No prior function dependency required.
 
+### Team Statistics Data
+
+#### `team_stats_data`
+
+The `team_stats_data` function fetches detailed statistical data for each team in a given tournament and season, based on the team list provided by `standings_data`.
+
+Note: This function requires the output of `standings_data` and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+team_stats_df = team_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(team_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on each team, typically returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `stat`: The name of the statistic.
+* `value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Player Statistics Data
+
+#### `player_stats_data`
+
+The `player_stats_data` function fetches top player statistics for each team in the given standings dataset. It processes player-level metrics like goals, assists, duels won, and more.
+
+Note: This function requires the output of `standings_data`, and filters for rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+player_stats_df = player_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(player_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on teams, returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `position`: The player’s position.
+* `stat_name`: The name of the statistic.
+* `stat_value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Squad Data
+
+#### `squad_data`
+
+The `squad_data` function fetches detailed squad (roster) information for each team listed in the provided standings dataset. It includes player bio data such as age, height, position, market value, and contract info.
+
+Note: This function requires the output of `standings_data`, and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+squad_df = squad_data(
+    standings_df=standings_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(squad_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with team metadata, returned by standings_data.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `age`: The date of birth timestamp (UNIX format).
+* `height`: The height of the player.
+* `player_country`: The nationality of the player.
+* `position`: The position of the player.
+* `preferred_foot`: The preferred foot of the player.
+* `contract_until`: The contract end date (UNIX timestamp).
+* `market_value`: The market value of the player.
+* `market_currency`: The currency used for the market value.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
 ## Changelog
 
+* v1.5.0
+  * Added `team_stats_data` function to retrieve detailed per-team statistics using `standings_data`.
+  * Added `player_stats_data` function to retrieve player-level top stats per team.
+  * Added `squad_data` function to fetch full squad information including bio and market value.
+
 * v1.4.0
   * Added `tournament_type` and `tournament_stage` parameters to `match_data` and `past_matches_data` functions.
   * Extended support for UEFA tournaments, including UEFA Champions League (UCL), UEFA Europa League (UEL), UEFA Europa Conference League (UECL), and UEFA Nations League (UNL), allowing seamless data fetching across multiple competitions.

{datafc-1.4.0 → datafc-1.5.0}/README.md

@@ -1,4 +1,4 @@
-# datafc v1.4.0
+# datafc v1.5.0
 
 ## Overview
 
@@ -37,7 +37,7 @@ pip install git+https://github.com/urazakgul/datafc.git
 To install a specific version of `datafc`, use:
 
 ```bash
-pip install datafc==1.4.0
+pip install datafc==1.5.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -95,7 +95,10 @@ from datafc.sofascore import (
     substitutions_data,
     goal_networks_data,
     shots_data,
-    standings_data
+    standings_data,
+    team_stats_data,
+    player_stats_data,
+    squad_data
 )
 ```
 
@@ -125,10 +128,22 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
+### `standings_data`: A Foundation for Team and Player-Level Functions
+
 Exception: `standings_data` and `past_matches_data`
 
 Unlike other functions, `standings_data` and `past_matches_data` do not require `match_data` or `lineups_data`. They can be executed independently using only `tournament_id` and `season_id`. Additionally, `past_matches_data` includes an extra field: `week_number`.
 
+However, `standings_data` serves as a critical dependency for the following functions:
+
+* `team_stats_data`
+* `player_stats_data`
+* `squad_data`
+
+These functions rely on team-level metadata (such as `team_id`) provided by `standings_data` to fetch more granular data. Ensure that `standings_data` is successfully executed and includes teams with `category == 'Total'` before calling any of the above functions.
+
+`past_matches_data` also works independently and includes an extra field: `week_number`.
+
 ### Match Data
 
 #### `match_data`
@@ -848,8 +863,182 @@ Dependencies:
 
 * No prior function dependency required.
 
+### Team Statistics Data
+
+#### `team_stats_data`
+
+The `team_stats_data` function fetches detailed statistical data for each team in a given tournament and season, based on the team list provided by `standings_data`.
+
+Note: This function requires the output of `standings_data` and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+team_stats_df = team_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(team_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on each team, typically returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `stat`: The name of the statistic.
+* `value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Player Statistics Data
+
+#### `player_stats_data`
+
+The `player_stats_data` function fetches top player statistics for each team in the given standings dataset. It processes player-level metrics like goals, assists, duels won, and more.
+
+Note: This function requires the output of `standings_data`, and filters for rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+player_stats_df = player_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(player_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on teams, returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `position`: The player’s position.
+* `stat_name`: The name of the statistic.
+* `stat_value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Squad Data
+
+#### `squad_data`
+
+The `squad_data` function fetches detailed squad (roster) information for each team listed in the provided standings dataset. It includes player bio data such as age, height, position, market value, and contract info.
+
+Note: This function requires the output of `standings_data`, and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+squad_df = squad_data(
+    standings_df=standings_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(squad_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with team metadata, returned by standings_data.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `age`: The date of birth timestamp (UNIX format).
+* `height`: The height of the player.
+* `player_country`: The nationality of the player.
+* `position`: The position of the player.
+* `preferred_foot`: The preferred foot of the player.
+* `contract_until`: The contract end date (UNIX timestamp).
+* `market_value`: The market value of the player.
+* `market_currency`: The currency used for the market value.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
 ## Changelog
 
+* v1.5.0
+  * Added `team_stats_data` function to retrieve detailed per-team statistics using `standings_data`.
+  * Added `player_stats_data` function to retrieve player-level top stats per team.
+  * Added `squad_data` function to fetch full squad information including bio and market value.
+
 * v1.4.0
   * Added `tournament_type` and `tournament_stage` parameters to `match_data` and `past_matches_data` functions.
   * Extended support for UEFA tournaments, including UEFA Champions League (UCL), UEFA Europa League (UEL), UEFA Europa Conference League (UECL), and UEFA Nations League (UNL), allowing seamless data fetching across multiple competitions.

{datafc-1.4.0 → datafc-1.5.0}/datafc/sofascore/__init__.py

@@ -9,6 +9,9 @@ from .fetch_substitutions_data import substitutions_data
 from .fetch_match_odds_data import match_odds_data
 from .fetch_momentum_data import momentum_data
 from .fetch_past_matches_data import past_matches_data
+from .fetch_team_stats_data import team_stats_data
+from .fetch_player_stats_data import player_stats_data
+from .fetch_squad_data import squad_data
 
 __all__ = [
     "match_data",
@@ -21,5 +24,8 @@ __all__ = [
     "substitutions_data",
     "match_odds_data",
     "momentum_data",
-    "past_matches_data"
+    "past_matches_data",
+    "team_stats_data",
+    "player_stats_data",
+    "squad_data"
 ]

datafc-1.5.0/datafc/sofascore/fetch_player_stats_data.py

@@ -0,0 +1,132 @@
+import json
+import pandas as pd
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.common.exceptions import TimeoutException, WebDriverException
+from datafc.utils._setup_webdriver import setup_webdriver
+from datafc.utils._save_files import save_json, save_excel
+from datafc.utils._config import ALLOWED_SOURCES, API_BASE_URLS
+
+def player_stats_data(
+    standings_df: pd.DataFrame,
+    tournament_id: int,
+    season_id: int,
+    data_source: str = "sofascore",
+    element_load_timeout: int = 10,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False
+) -> pd.DataFrame:
+    """
+    Fetches player statistics data for each team in the provided standings dataset.
+
+    Args:
+        standings_df (pd.DataFrame): A DataFrame containing team metadata, including team_id.
+        tournament_id (int): The unique identifier for the tournament.
+        season_id (int): The unique identifier for the season.
+        data_source (str): The data source ('sofascore'). Defaults to 'sofascore'.
+        element_load_timeout (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
+        enable_json_export (bool): If `True`, saves the fetched data as a JSON file. Defaults to `False`.
+        enable_excel_export (bool): If `True`, saves the fetched data as an Excel file. Defaults to `False`.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing statistical information for each player.
+    """
+    if data_source not in ALLOWED_SOURCES:
+        raise ValueError(f"Invalid data source: {data_source}. Must be one of {ALLOWED_SOURCES}")
+
+    if standings_df is None or standings_df.empty:
+        raise ValueError("Standings dataframe must be provided and cannot be empty.")
+
+    webdriver_instance = None
+    try:
+        webdriver_instance = setup_webdriver()
+        stats_data_list = []
+
+        standings_df = standings_df[standings_df["category"] == "Total"]
+        for _, row in standings_df.iterrows():
+            country = row["country"]
+            tournament = row["tournament"]
+            team_name = row["team_name"]
+            team_id = row["team_id"]
+
+            url = f"{API_BASE_URLS[data_source + '2']}/api/v1/team/{team_id}/unique-tournament/{tournament_id}/season/{season_id}/top-players/overall"
+            webdriver_instance.get(url)
+
+            try:
+                pre_tag = WebDriverWait(webdriver_instance, element_load_timeout).until(
+                    EC.visibility_of_element_located((By.TAG_NAME, "pre"))
+                )
+
+                stats_json = json.loads(pre_tag.text)
+                top_players = stats_json.get("topPlayers", {})
+
+                for category, players in top_players.items():
+                    for player_data in players:
+                        player = player_data.get("player", {})
+                        player_id = player.get("id")
+                        statistics = player_data.get("statistics", {})
+
+                        for stat, value in statistics.items():
+                            if stat in ["id", "type"]:
+                                continue
+
+                            log_entry = {
+                                "country": country,
+                                "tournament": tournament,
+                                "team_name": team_name,
+                                "team_id": team_id,
+                                "player_name": player.get("name"),
+                                "player_id": player_id,
+                                "position": player.get("position"),
+                                "stat_name": stat,
+                                "stat_value": value
+                            }
+                            if log_entry not in stats_data_list:
+                                stats_data_list.append(log_entry)
+            except TimeoutException:
+                print(f"Timeout while fetching player stats data for team_id {team_id}.")
+            except json.JSONDecodeError:
+                print(f"Failed to decode player stats data for team_id {team_id}.")
+            except WebDriverException as e:
+                print(f"Selenium WebDriver error while fetching player stats data for team_id {team_id}: {str(e)}")
+            except Exception as e:
+                print(f"Unexpected error while fetching player stats data for team_id {team_id}: {e.__class__.__name__} - {e}")
+
+        stats_data_df = pd.DataFrame(stats_data_list).drop_duplicates()
+
+        if stats_data_df.empty:
+            raise ValueError("No player statistics data found for the specified teams.")
+
+        if enable_json_export or enable_excel_export:
+            first_row = stats_data_df.iloc[0]
+
+            if enable_json_export:
+                save_json(
+                    data=stats_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+            if enable_excel_export:
+                save_excel(
+                    data=stats_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+        return stats_data_df
+
+    except WebDriverException as e:
+        raise RuntimeError(f"Selenium WebDriver error: {str(e)}")
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error while fetching player stats data: {e.__class__.__name__} - {e}")
+    finally:
+        if webdriver_instance:
+            webdriver_instance.quit()

datafc-1.5.0/datafc/sofascore/fetch_squad_data.py

@@ -0,0 +1,123 @@
+import json
+import pandas as pd
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.common.exceptions import TimeoutException, WebDriverException
+from datafc.utils._setup_webdriver import setup_webdriver
+from datafc.utils._save_files import save_json, save_excel
+from datafc.utils._config import ALLOWED_SOURCES, API_BASE_URLS
+
+def squad_data(
+    standings_df: pd.DataFrame,
+    data_source: str = "sofascore",
+    element_load_timeout: int = 10,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False
+) -> pd.DataFrame:
+    """
+    Fetches squad data for each team in the provided standings dataset.
+
+    Args:
+        standings_df (pd.DataFrame): A DataFrame containing team metadata, including team_id.
+        data_source (str): The data source ('sofavpn' or 'sofascore'). Defaults to 'sofascore'.
+        element_load_timeout (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
+        enable_json_export (bool): If `True`, saves the fetched data as a JSON file. Defaults to `False`.
+        enable_excel_export (bool): If `True`, saves the fetched data as an Excel file. Defaults to `False`.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing squad information for each team.
+    """
+    if data_source not in ALLOWED_SOURCES:
+        raise ValueError(f"Invalid data source: {data_source}. Must be one of {ALLOWED_SOURCES}")
+
+    if standings_df is None or standings_df.empty:
+        raise ValueError("Standings dataframe must be provided and cannot be empty.")
+
+    webdriver_instance = None
+    try:
+        webdriver_instance = setup_webdriver()
+        squads_data_list = []
+
+        standings_df = standings_df[standings_df["category"] == "Total"]
+        for _, row in standings_df.iterrows():
+            country = row["country"]
+            tournament = row["tournament"]
+            team_name = row["team_name"]
+            team_id = row["team_id"]
+
+            url = f"{API_BASE_URLS[data_source]}/api/v1/team/{team_id}/players"
+            webdriver_instance.get(url)
+
+            try:
+                pre_tag = WebDriverWait(webdriver_instance, element_load_timeout).until(
+                    EC.visibility_of_element_located((By.TAG_NAME, "pre"))
+                )
+
+                squad_json = json.loads(pre_tag.text)
+
+                for player_info in squad_json.get("players", []):
+                    player = player_info["player"]
+                    squads_data_list.append({
+                        "country": country,
+                        "tournament": tournament,
+                        "team_name": team_name,
+                        "team_id": team_id,
+                        "player_name": player.get("name"),
+                        "player_id": player.get("id"),
+                        "age": player.get("dateOfBirthTimestamp"),
+                        "height": player.get("height"),
+                        "player_country": player.get("country", {}).get("name"),
+                        "position": player.get("position"),
+                        "preferred_foot": player.get("preferredFoot"),
+                        "contract_until": player.get("contractUntilTimestamp"),
+                        "market_value": player.get("proposedMarketValueRaw", {}).get("value"),
+                        "market_currency": player.get("proposedMarketValueRaw", {}).get("currency")
+                    })
+            except TimeoutException:
+                print(f"Timeout while fetching squad data for team_id {team_id}.")
+            except json.JSONDecodeError:
+                print(f"Failed to decode squad data for team_id {team_id}.")
+            except WebDriverException as e:
+                print(f"Selenium WebDriver error while fetching squad data for team_id {team_id}: {str(e)}")
+            except Exception as e:
+                print(f"Unexpected error while fetching squad data for team_id {team_id}: {e.__class__.__name__} - {e}")
+
+        squads_data_df = pd.DataFrame(squads_data_list)
+
+        if squads_data_df.empty:
+            raise ValueError("No squad data found for the specified teams.")
+
+        if enable_json_export or enable_excel_export:
+            first_row = squads_data_df.iloc[0]
+
+            if enable_json_export:
+                save_json(
+                    data=squads_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+            if enable_excel_export:
+                save_excel(
+                    data=squads_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+        return squads_data_df
+
+    except WebDriverException as e:
+        raise RuntimeError(f"Selenium WebDriver error: {str(e)}")
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error while fetching squad data: {e.__class__.__name__} - {e}")
+
+    finally:
+        if webdriver_instance:
+            webdriver_instance.quit()

datafc-1.5.0/datafc/sofascore/fetch_team_stats_data.py

@@ -0,0 +1,114 @@
+import json
+import pandas as pd
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.common.exceptions import TimeoutException, WebDriverException
+from datafc.utils._setup_webdriver import setup_webdriver
+from datafc.utils._save_files import save_json, save_excel
+from datafc.utils._config import ALLOWED_SOURCES, API_BASE_URLS
+
+def team_stats_data(
+    standings_df: pd.DataFrame,
+    tournament_id: int,
+    season_id: int,
+    data_source: str = "sofascore",
+    element_load_timeout: int = 10,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False
+) -> pd.DataFrame:
+    """
+    Fetches team statistics data for each team in the provided standings dataset.
+
+    Args:
+        standings_df (pd.DataFrame): A DataFrame containing team metadata, including team_id.
+        tournament_id (int): The unique identifier for the tournament.
+        season_id (int): The unique identifier for the season.
+        data_source (str): The data source ('sofascore'). Defaults to 'sofascore'.
+        element_load_timeout (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
+        enable_json_export (bool): If `True`, saves the fetched data as a JSON file. Defaults to `False`.
+        enable_excel_export (bool): If `True`, saves the fetched data as an Excel file. Defaults to `False`.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing statistical information for each team.
+    """
+    if data_source not in ALLOWED_SOURCES:
+        raise ValueError(f"Invalid data source: {data_source}. Must be one of {ALLOWED_SOURCES}")
+
+    if standings_df is None or standings_df.empty:
+        raise ValueError("Standings dataframe must be provided and cannot be empty.")
+
+    webdriver_instance = None
+    try:
+        webdriver_instance = setup_webdriver()
+        stats_data_list = []
+
+        standings_df = standings_df[standings_df["category"] == "Total"]
+        for _, row in standings_df.iterrows():
+            country = row["country"]
+            tournament = row["tournament"]
+            team_name = row["team_name"]
+            team_id = row["team_id"]
+
+            url = f"{API_BASE_URLS[data_source + '2']}/api/v1/team/{team_id}/unique-tournament/{tournament_id}/season/{season_id}/statistics/overall"
+            webdriver_instance.get(url)
+
+            try:
+                pre_tag = WebDriverWait(webdriver_instance, element_load_timeout).until(
+                    EC.visibility_of_element_located((By.TAG_NAME, "pre"))
+                )
+
+                stats_json = json.loads(pre_tag.text)
+                statistics = stats_json.get("statistics", {})
+                log_entries = [
+                    {"country": country, "tournament": tournament, "team_name": team_name, "team_id": team_id, "stat": stat, "value": value}
+                    for stat, value in statistics.items()
+                    if stat not in {"country", "tournament", "team_name", "team_id"}
+                ]
+                stats_data_list.extend(log_entries)
+            except TimeoutException:
+                print(f"Timeout while fetching team stats data for team_id {team_id}.")
+            except json.JSONDecodeError:
+                print(f"Failed to decode team stats data for team_id {team_id}.")
+            except WebDriverException as e:
+                print(f"Selenium WebDriver error while fetching team stats data for team_id {team_id}: {str(e)}")
+            except Exception as e:
+                print(f"Unexpected error while fetching team stats data for team_id {team_id}: {e.__class__.__name__} - {e}")
+
+        stats_data_df = pd.DataFrame(stats_data_list)
+
+        if stats_data_df.empty:
+            raise ValueError("No team statistics data found for the specified teams.")
+
+        if enable_json_export or enable_excel_export:
+            first_row = stats_data_df.iloc[0]
+
+            if enable_json_export:
+                save_json(
+                    data=stats_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+            if enable_excel_export:
+                save_excel(
+                    data=stats_data_df,
+                    data_source=data_source,
+                    country=first_row["country"],
+                    tournament=first_row["tournament"],
+                    season=None,
+                    week_number=None
+                )
+
+        return stats_data_df
+
+    except WebDriverException as e:
+        raise RuntimeError(f"Selenium WebDriver error: {str(e)}")
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error while fetching team stats data: {e.__class__.__name__} - {e}")
+    finally:
+        if webdriver_instance:
+            webdriver_instance.quit()

{datafc-1.4.0 → datafc-1.5.0}/datafc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datafc
-Version: 1.4.0
+Version: 1.5.0
 Summary: A scalable Python library for fetching, processing, and exporting structured football match data.
 Home-page: https://github.com/urazakgul/datafc
 Author: Uraz Akgül
@@ -14,7 +14,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# datafc v1.4.0
+# datafc v1.5.0
 
 ## Overview
 
@@ -53,7 +53,7 @@ pip install git+https://github.com/urazakgul/datafc.git
 To install a specific version of `datafc`, use:
 
 ```bash
-pip install datafc==1.4.0
+pip install datafc==1.5.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -111,7 +111,10 @@ from datafc.sofascore import (
     substitutions_data,
     goal_networks_data,
     shots_data,
-    standings_data
+    standings_data,
+    team_stats_data,
+    player_stats_data,
+    squad_data
 )
 ```
 
@@ -141,10 +144,22 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
+### `standings_data`: A Foundation for Team and Player-Level Functions
+
 Exception: `standings_data` and `past_matches_data`
 
 Unlike other functions, `standings_data` and `past_matches_data` do not require `match_data` or `lineups_data`. They can be executed independently using only `tournament_id` and `season_id`. Additionally, `past_matches_data` includes an extra field: `week_number`.
 
+However, `standings_data` serves as a critical dependency for the following functions:
+
+* `team_stats_data`
+* `player_stats_data`
+* `squad_data`
+
+These functions rely on team-level metadata (such as `team_id`) provided by `standings_data` to fetch more granular data. Ensure that `standings_data` is successfully executed and includes teams with `category == 'Total'` before calling any of the above functions.
+
+`past_matches_data` also works independently and includes an extra field: `week_number`.
+
 ### Match Data
 
 #### `match_data`
@@ -864,8 +879,182 @@ Dependencies:
 
 * No prior function dependency required.
 
+### Team Statistics Data
+
+#### `team_stats_data`
+
+The `team_stats_data` function fetches detailed statistical data for each team in a given tournament and season, based on the team list provided by `standings_data`.
+
+Note: This function requires the output of `standings_data` and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+team_stats_df = team_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(team_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on each team, typically returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `stat`: The name of the statistic.
+* `value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Player Statistics Data
+
+#### `player_stats_data`
+
+The `player_stats_data` function fetches top player statistics for each team in the given standings dataset. It processes player-level metrics like goals, assists, duels won, and more.
+
+Note: This function requires the output of `standings_data`, and filters for rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+player_stats_df = player_stats_data(
+    standings_df=standings_df,
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(player_stats_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with metadata on teams, returned by standings_data.
+* `tournament_id` (int): The unique identifier for the tournament.
+* `season_id` (int): The unique identifier for the season.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `position`: The player’s position.
+* `stat_name`: The name of the statistic.
+* `stat_value`: The value of the statistic.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
+### Squad Data
+
+#### `squad_data`
+
+The `squad_data` function fetches detailed squad (roster) information for each team listed in the provided standings dataset. It includes player bio data such as age, height, position, market value, and contract info.
+
+Note: This function requires the output of `standings_data`, and only processes rows where `category == 'Total'`.
+
+Example Usage:
+
+```python
+standings_df = standings_data(
+    tournament_id=52,
+    season_id=63814,
+    data_source="sofascore"
+)
+
+squad_df = squad_data(
+    standings_df=standings_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(squad_df)
+```
+
+Parameters:
+
+* `standings_df` (pd.DataFrame): A DataFrame with team metadata, returned by standings_data.
+* `data_source` (str): The data source (`sofavpn` or `sofascore`). Defaults to `"sofascore"`.
+* `element_load_timeout` (int): Maximum time (in seconds) to wait for the API response. Defaults to `10`.
+* `enable_json_export` (bool): If `True`, exports the data as a JSON file. Defaults to `False`.
+* `enable_excel_export` (bool): If `True`, exports the data as an Excel file. Defaults to `False`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `team_name`: The name of the team.
+* `team_id`: The unique identifier of the team.
+* `player_name`: The name of the player.
+* `player_id`: The unique identifier of the player.
+* `age`: The date of birth timestamp (UNIX format).
+* `height`: The height of the player.
+* `player_country`: The nationality of the player.
+* `position`: The position of the player.
+* `preferred_foot`: The preferred foot of the player.
+* `contract_until`: The contract end date (UNIX timestamp).
+* `market_value`: The market value of the player.
+* `market_currency`: The currency used for the market value.
+
+Dependencies:
+
+* Requires `standings_data` output as `standings_df`.
+
 ## Changelog
 
+* v1.5.0
+  * Added `team_stats_data` function to retrieve detailed per-team statistics using `standings_data`.
+  * Added `player_stats_data` function to retrieve player-level top stats per team.
+  * Added `squad_data` function to fetch full squad information including bio and market value.
+
 * v1.4.0
   * Added `tournament_type` and `tournament_stage` parameters to `match_data` and `past_matches_data` functions.
   * Extended support for UEFA tournaments, including UEFA Champions League (UCL), UEFA Europa League (UEL), UEFA Europa Conference League (UECL), and UEFA Nations League (UNL), allowing seamless data fetching across multiple competitions.

{datafc-1.4.0 → datafc-1.5.0}/datafc.egg-info/SOURCES.txt

@@ -16,9 +16,12 @@ datafc/sofascore/fetch_match_odds_data.py
 datafc/sofascore/fetch_match_stats_data.py
 datafc/sofascore/fetch_momentum_data.py
 datafc/sofascore/fetch_past_matches_data.py
+datafc/sofascore/fetch_player_stats_data.py
 datafc/sofascore/fetch_shots_data.py
+datafc/sofascore/fetch_squad_data.py
 datafc/sofascore/fetch_standings_data.py
 datafc/sofascore/fetch_substitutions_data.py
+datafc/sofascore/fetch_team_stats_data.py
 datafc/utils/__init__.py
 datafc/utils/_config.py
 datafc/utils/_save_files.py

{datafc-1.4.0 → datafc-1.5.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="datafc",
-    version="1.4.0",
+    version="1.5.0",
     author="Uraz Akgül",
     author_email="urazdev@gmail.com",
     description="A scalable Python library for fetching, processing, and exporting structured football match data.",