datafc 1.3.0__tar.gz → 1.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datafc
-Version: 1.3.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.3.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.3.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`
@@ -164,15 +179,52 @@ match_df = match_data(
 )
 
 print(match_df)
+
+uefa_match_df = match_data(
+    tournament_id=7,
+    season_id=61644,
+    week_number=5,
+    tournament_type="uefa",
+    tournament_stage="round_of_16",
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_match_df)
 ```
 
 Parameters:
 
 * `tournament_id` (int): The unique identifier for the tournament.
 * `season_id` (int): The unique identifier for the season.
-* `week_number` (int): The matchweek number within the season.
+* `week_number` (int): The matchweek number within the season. The applicable week numbers depend on the tournament and stage, as outlined below for the 2024/25 season:
+  * UCL, UEL, UECL, and UNL:
+    * `qualification_round`: 1, 2, 3
+    * `qualification_playoff`: 636
+    * `group_stage_week`: 1, 2, 3, ..., 8 (for UNL, up to 6)
+    * `playoff_round`: 636
+    * `round_of_16`: 5
+    * `quarterfinals`: 27
+    * `semifinals`: 28
+    * `final`: 29
+  * Domestic Leagues:
+    * Use the corresponding matchweek number (e.g., for the 10th week of the season, enter `week_number=10`).
+* `tournament_type` (str, optional): The tournament type (`uefa`). If `None`, assumes league format.
+* `tournament_stage` (str, optional): The specific stage of the tournament. Available options for UEFA tournaments:
+  * `preliminary_final`
+  * `preliminary_final`
+  * `qualification_round`
+  * `qualification_playoff`
+  * `group_stage_week`
+  * `playoff_round`
+  * `round_of_16`
+  * `quarterfinals`
+  * `semifinals`
+  * `match_for_3rd_place`
+  * `final`
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -223,13 +275,22 @@ match_odds_df = match_odds_data(
 )
 
 print(match_odds_df)
+
+uefa_match_odds_df = match_odds_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_match_odds_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -270,13 +331,22 @@ match_stats_df = match_stats_data(
 )
 
 print(match_stats_df)
+
+uefa_match_stats_df = match_stats_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_match_stats_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -314,13 +384,22 @@ momentum_df = momentum_data(
 )
 
 print(momentum_df)
+
+uefa_momentum_df = momentum_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_momentum_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -357,15 +436,52 @@ past_matches_df = past_matches_data(
 )
 
 print(past_matches_df)
+
+uefa_past_matches_df = past_matches_data(
+    tournament_id=7,
+    season_id=61644,
+    week_number=5,
+    tournament_type="uefa",
+    tournament_stage="round_of_16",
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_past_matches_df)
 ```
 
 Parameters:
 
 * `tournament_id` (int): The unique identifier for the tournament.
 * `season_id` (int): The unique identifier for the season.
-* `week_number` (int): The matchweek number within the season.
+* `week_number` (int): The matchweek number within the season. The applicable week numbers depend on the tournament and stage, as outlined below for the 2024/25 season:
+  * UCL, UEL, UECL, and UNL:
+    * `qualification_round`: 1, 2, 3
+    * `qualification_playoff`: 636
+    * `group_stage_week`: 1, 2, 3, ..., 8 (for UNL, up to 6)
+    * `playoff_round`: 636
+    * `round_of_16`: 5
+    * `quarterfinals`: 27
+    * `semifinals`: 28
+    * `final`: 29
+  * Domestic Leagues:
+    * Use the corresponding matchweek number (e.g., for the 10th week of the season, enter `week_number=10`).
+* `tournament_type` (str, optional): The tournament type (`uefa`). If `None`, assumes league format.
+* `tournament_stage` (str, optional): The specific stage of the tournament. Available options for UEFA tournaments:
+  * `preliminary_final`
+  * `preliminary_final`
+  * `qualification_round`
+  * `qualification_playoff`
+  * `group_stage_week`
+  * `playoff_round`
+  * `round_of_16`
+  * `quarterfinals`
+  * `semifinals`
+  * `match_for_3rd_place`
+  * `final`
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -418,13 +534,22 @@ lineups_df = lineups_data(
 )
 
 print(lineups_df)
+
+uefa_lineups_df = lineups_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_lineups_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -462,13 +587,22 @@ coordinates_df = coordinates_data(
 )
 
 print(coordinates_df)
+
+uefa_coordinates_df = coordinates_data(
+    lineups_df=uefa_lineups_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_coordinates_df)
 ```
 
 Parameters:
 
 * `lineups_df` (pd.DataFrame): A DataFrame containing player and match metadata, which should be generated by the `lineups_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -506,13 +640,22 @@ substitutions_df = substitutions_data(
 )
 
 print(substitutions_df)
+
+uefa_substitutions_df = substitutions_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_substitutions_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -552,13 +695,22 @@ goal_networks_df = goal_networks_data(
 )
 
 print(goal_networks_df)
+
+uefa_goal_networks_df = goal_networks_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_goal_networks_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -608,13 +760,22 @@ shots_df = shots_data(
 )
 
 print(shots_df)
+
+uefa_shots_df = shots_data(
+    match_df=uefa_match_df,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_shots_df)
 ```
 
 Parameters:
 
 * `match_df` (pd.DataFrame): A DataFrame containing match metadata, which should be generated by the `match_data` function.
 * `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.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -675,6 +836,16 @@ standings_df = standings_data(
 )
 
 print(standings_df)
+
+uefa_standings_df = standings_data(
+    tournament_id=7,
+    season_id=61644,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(uefa_standings_df)
 ```
 
 Parameters:
@@ -682,7 +853,7 @@ Parameters:
 * `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): The maximum time (in seconds) to wait for the API response. Defaults to 10.
+* `element_load_timeout` (int): The maximum time (in seconds) to wait for the API response. Defaults to `10`.
 * `enable_json_export` (bool): If `True`, exports the fetched data as a JSON file. Defaults to `False`.
 * `enable_excel_export` (bool): If `True`, exports the fetched data as an Excel file. Defaults to `False`.
 
@@ -708,8 +879,186 @@ 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.
+
 * v1.3.0
   * Added `past_matches_data` function to fetch historical match data.