datafc 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datafc
-Version: 1.2.0
+Version: 1.3.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.2.0
+# datafc v1.3.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.2.0
+pip install datafc==1.3.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -105,6 +105,7 @@ from datafc.sofascore import (
     match_odds_data,
     match_stats_data,
     momentum_data,
+    past_matches_data,
     lineups_data,
     coordinates_data,
     substitutions_data,
@@ -140,20 +141,19 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
-Exception: `standings_data`
+Exception: `standings_data` and `past_matches_data`
 
-Unlike the other functions, `standings_data` does not require `match_data` or `lineups_data`. It can be executed independently using only `tournament_id` and `season_id`.
+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`.
 
 ### Match Data
 
 #### `match_data`
 
-The `match_data` function fetches match data for a specified tournament, season, and matchweek. It returns a DataFrame containing details such as country, tournament name, season, week number, game ID, home team, home team ID, away team, away team ID, added injury times for both halves, start timestamp, match status, and score-related information.
+The `match_data` function fetches match data for a specified tournament, season, and matchweek.
 
 Example Usage:
 
 ```python
-# Fetch match data for a specific tournament, season, and week
 match_df = match_data(
     tournament_id=52,
     season_id=63814,
@@ -210,12 +210,11 @@ Dependencies:
 
 #### `match_odds_data`
 
-The `match_odds_data` function fetches betting odds data for each match in the provided match dataset. It returns a DataFrame containing match odds details, including market names, odds values, and whether the odds changed.
+The `match_odds_data` function fetches betting odds data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match odds data
 match_odds_df = match_odds_data(
     match_df=match_df,
     data_source="sofascore",
@@ -258,12 +257,11 @@ Dependencies:
 
 #### `match_stats_data`
 
-The `match_stats_data` function fetches statistical data for each match in the provided match dataset. It returns a DataFrame containing key match statistics, including team performance metrics.
+The `match_stats_data` function fetches statistical data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match statistics data
 match_stats_df = match_stats_data(
     match_df=match_df,
     data_source="sofascore",
@@ -303,12 +301,11 @@ Dependencies:
 
 #### `momentum_data`
 
-The `momentum_data` function fetches momentum data for each match in the provided match dataset. It returns a DataFrame containing match momentum values over time.
+The `momentum_data` function fetches momentum data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch momentum data
 momentum_df = momentum_data(
     match_df=match_df,
     data_source="sofascore",
@@ -343,16 +340,76 @@ Dependencies:
 
 * Requires `match_data` output as `match_df`.
 
+#### `past_matches_data`
+
+The `past_matches_data` function fetches past match data for a specified tournament, season, and week number.
+
+Example Usage:
+
+```python
+past_matches_df = past_matches_data(
+    tournament_id=52,
+    season_id=63814,
+    week_number=21,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(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.
+* `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`, 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`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `season`: The season year.
+* `week`: The matchweek number.
+* `game_id`: The unique identifier for the match.
+* `home_team`: The name of the home team.
+* `home_team_id`: The unique identifier for the home team.
+* `away_team`: The name of the away team.
+* `away_team_id`: The unique identifier for the away team.
+* `injury_time_1`: Added injury time in the first half.
+* `injury_time_2`: Added injury time in the second half.
+* `start_timestamp`: The start time of the match.
+* `status`: The current status of the match.
+* `home_score_current`: The latest recorded score for the home team.
+* `home_score_display`: The displayed score of the home team.
+* `home_score_period1`: The home team's score at the end of the first half.
+* `home_score_period2`: The home team's goals scored in the second half.
+* `home_score_normaltime`: The home team's final score at the end of normal time (90 minutes).
+* `away_score_current`: The latest recorded score for the away team.
+* `away_score_display`: The displayed score of the away team.
+* `away_score_period1`: The away team's score at the end of the first half.
+* `away_score_period2`: The away team's goals scored in the second half.
+* `away_score_normaltime`: The away team's final score at the end of normal time (90 minutes).
+
+Dependencies:
+
+* No prior function dependency required.
+
 ### Player Data
 
 #### `lineups_data`
 
-The `lineups_data` function fetches lineup data for each match in the provided match dataset. It returns a DataFrame containing lineup details such as country, tournament name, season, week number, game ID, team, player name, player ID, statistic name, and statistic value.
+The `lineups_data` function fetches lineup data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch lineups data based on match data
 lineups_df = lineups_data(
     match_df=match_df,
     data_source="sofascore",
@@ -392,12 +449,11 @@ Dependencies:
 
 #### `coordinates_data`
 
-The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset. It returns a DataFrame containing coordinate details such as country, tournament name, season, week number, game ID, team, player ID, player name, and x-y coordinates.
+The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset.
 
 Example Usage:
 
 ```python
-# Fetch coordinates data
 coordinates_df = coordinates_data(
     lineups_df=lineups_df,
     data_source="sofascore",
@@ -437,12 +493,11 @@ Dependencies:
 
 #### `substitutions_data`
 
-The `substitutions_data` function fetches substitution data for each match in the provided match dataset. It returns a DataFrame containing details of player substitutions, including the players involved and the time of the substitution.
+The `substitutions_data` function fetches substitution data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch substitution data
 substitutions_df = substitutions_data(
     match_df=match_df,
     data_source="sofascore",
@@ -484,12 +539,11 @@ Dependencies:
 
 #### `goal_networks_data`
 
-The `goal_networks_data` function fetches goal network data for each match in the provided match dataset. It returns a DataFrame containing goal-related events, including passing networks and shot locations.
+The `goal_networks_data` function fetches goal network data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch goal networks data
 goal_networks_df = goal_networks_data(
     match_df=match_df,
     data_source="sofascore",
@@ -541,12 +595,11 @@ Dependencies:
 
 #### `shots_data`
 
-The `shots_data` function fetches shot data for each match in the provided match dataset. It returns a DataFrame containing detailed shot-related information, including player coordinates, xG values, shot types, and goal mouth locations.
+The `shots_data` function fetches shot data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch shot data
 shots_df = shots_data(
     match_df=match_df,
     data_source="sofascore",
@@ -608,12 +661,11 @@ Dependencies:
 
 #### `standings_data`
 
-The `standings_data` function fetches league standings for a specific tournament and season. It returns a DataFrame containing team rankings, match results, and points.
+The `standings_data` function fetches league standings for a specific tournament and season.
 
 Example Usage:
 
 ```python
-# Fetch league standings
 standings_df = standings_data(
     tournament_id=52,
     season_id=63814,
@@ -658,6 +710,9 @@ Dependencies:
 
 ## Changelog
 
+* v1.3.0
+  * Added `past_matches_data` function to fetch historical match data.
+
 * v1.2.0
   * Added match score columns to `match_data`
 

{datafc-1.2.0 → datafc-1.3.0}/README.md

@@ -1,4 +1,4 @@
-# datafc v1.2.0
+# datafc v1.3.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.2.0
+pip install datafc==1.3.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -89,6 +89,7 @@ from datafc.sofascore import (
     match_odds_data,
     match_stats_data,
     momentum_data,
+    past_matches_data,
     lineups_data,
     coordinates_data,
     substitutions_data,
@@ -124,20 +125,19 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
-Exception: `standings_data`
+Exception: `standings_data` and `past_matches_data`
 
-Unlike the other functions, `standings_data` does not require `match_data` or `lineups_data`. It can be executed independently using only `tournament_id` and `season_id`.
+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`.
 
 ### Match Data
 
 #### `match_data`
 
-The `match_data` function fetches match data for a specified tournament, season, and matchweek. It returns a DataFrame containing details such as country, tournament name, season, week number, game ID, home team, home team ID, away team, away team ID, added injury times for both halves, start timestamp, match status, and score-related information.
+The `match_data` function fetches match data for a specified tournament, season, and matchweek.
 
 Example Usage:
 
 ```python
-# Fetch match data for a specific tournament, season, and week
 match_df = match_data(
     tournament_id=52,
     season_id=63814,
@@ -194,12 +194,11 @@ Dependencies:
 
 #### `match_odds_data`
 
-The `match_odds_data` function fetches betting odds data for each match in the provided match dataset. It returns a DataFrame containing match odds details, including market names, odds values, and whether the odds changed.
+The `match_odds_data` function fetches betting odds data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match odds data
 match_odds_df = match_odds_data(
     match_df=match_df,
     data_source="sofascore",
@@ -242,12 +241,11 @@ Dependencies:
 
 #### `match_stats_data`
 
-The `match_stats_data` function fetches statistical data for each match in the provided match dataset. It returns a DataFrame containing key match statistics, including team performance metrics.
+The `match_stats_data` function fetches statistical data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match statistics data
 match_stats_df = match_stats_data(
     match_df=match_df,
     data_source="sofascore",
@@ -287,12 +285,11 @@ Dependencies:
 
 #### `momentum_data`
 
-The `momentum_data` function fetches momentum data for each match in the provided match dataset. It returns a DataFrame containing match momentum values over time.
+The `momentum_data` function fetches momentum data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch momentum data
 momentum_df = momentum_data(
     match_df=match_df,
     data_source="sofascore",
@@ -327,16 +324,76 @@ Dependencies:
 
 * Requires `match_data` output as `match_df`.
 
+#### `past_matches_data`
+
+The `past_matches_data` function fetches past match data for a specified tournament, season, and week number.
+
+Example Usage:
+
+```python
+past_matches_df = past_matches_data(
+    tournament_id=52,
+    season_id=63814,
+    week_number=21,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(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.
+* `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`, 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`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `season`: The season year.
+* `week`: The matchweek number.
+* `game_id`: The unique identifier for the match.
+* `home_team`: The name of the home team.
+* `home_team_id`: The unique identifier for the home team.
+* `away_team`: The name of the away team.
+* `away_team_id`: The unique identifier for the away team.
+* `injury_time_1`: Added injury time in the first half.
+* `injury_time_2`: Added injury time in the second half.
+* `start_timestamp`: The start time of the match.
+* `status`: The current status of the match.
+* `home_score_current`: The latest recorded score for the home team.
+* `home_score_display`: The displayed score of the home team.
+* `home_score_period1`: The home team's score at the end of the first half.
+* `home_score_period2`: The home team's goals scored in the second half.
+* `home_score_normaltime`: The home team's final score at the end of normal time (90 minutes).
+* `away_score_current`: The latest recorded score for the away team.
+* `away_score_display`: The displayed score of the away team.
+* `away_score_period1`: The away team's score at the end of the first half.
+* `away_score_period2`: The away team's goals scored in the second half.
+* `away_score_normaltime`: The away team's final score at the end of normal time (90 minutes).
+
+Dependencies:
+
+* No prior function dependency required.
+
 ### Player Data
 
 #### `lineups_data`
 
-The `lineups_data` function fetches lineup data for each match in the provided match dataset. It returns a DataFrame containing lineup details such as country, tournament name, season, week number, game ID, team, player name, player ID, statistic name, and statistic value.
+The `lineups_data` function fetches lineup data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch lineups data based on match data
 lineups_df = lineups_data(
     match_df=match_df,
     data_source="sofascore",
@@ -376,12 +433,11 @@ Dependencies:
 
 #### `coordinates_data`
 
-The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset. It returns a DataFrame containing coordinate details such as country, tournament name, season, week number, game ID, team, player ID, player name, and x-y coordinates.
+The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset.
 
 Example Usage:
 
 ```python
-# Fetch coordinates data
 coordinates_df = coordinates_data(
     lineups_df=lineups_df,
     data_source="sofascore",
@@ -421,12 +477,11 @@ Dependencies:
 
 #### `substitutions_data`
 
-The `substitutions_data` function fetches substitution data for each match in the provided match dataset. It returns a DataFrame containing details of player substitutions, including the players involved and the time of the substitution.
+The `substitutions_data` function fetches substitution data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch substitution data
 substitutions_df = substitutions_data(
     match_df=match_df,
     data_source="sofascore",
@@ -468,12 +523,11 @@ Dependencies:
 
 #### `goal_networks_data`
 
-The `goal_networks_data` function fetches goal network data for each match in the provided match dataset. It returns a DataFrame containing goal-related events, including passing networks and shot locations.
+The `goal_networks_data` function fetches goal network data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch goal networks data
 goal_networks_df = goal_networks_data(
     match_df=match_df,
     data_source="sofascore",
@@ -525,12 +579,11 @@ Dependencies:
 
 #### `shots_data`
 
-The `shots_data` function fetches shot data for each match in the provided match dataset. It returns a DataFrame containing detailed shot-related information, including player coordinates, xG values, shot types, and goal mouth locations.
+The `shots_data` function fetches shot data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch shot data
 shots_df = shots_data(
     match_df=match_df,
     data_source="sofascore",
@@ -592,12 +645,11 @@ Dependencies:
 
 #### `standings_data`
 
-The `standings_data` function fetches league standings for a specific tournament and season. It returns a DataFrame containing team rankings, match results, and points.
+The `standings_data` function fetches league standings for a specific tournament and season.
 
 Example Usage:
 
 ```python
-# Fetch league standings
 standings_df = standings_data(
     tournament_id=52,
     season_id=63814,
@@ -642,6 +694,9 @@ Dependencies:
 
 ## Changelog
 
+* v1.3.0
+  * Added `past_matches_data` function to fetch historical match data.
+
 * v1.2.0
   * Added match score columns to `match_data`
 

{datafc-1.2.0 → datafc-1.3.0}/datafc/sofascore/__init__.py

@@ -8,6 +8,7 @@ from .fetch_coordinates_data import coordinates_data
 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
 
 __all__ = [
     "match_data",
@@ -19,5 +20,6 @@ __all__ = [
     "coordinates_data",
     "substitutions_data",
     "match_odds_data",
-    "momentum_data"
+    "momentum_data",
+    "past_matches_data"
 ]

datafc-1.3.0/datafc/sofascore/fetch_past_matches_data.py

@@ -0,0 +1,142 @@
+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 past_matches_data(
+    tournament_id: int,
+    season_id: int,
+    week_number: int,
+    data_source: str = "sofascore",
+    element_load_timeout: int = 10,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False
+) -> pd.DataFrame:
+    """
+    Fetches past match data for a specified tournament, season, and week number.
+
+    Args:
+        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.
+        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`, 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`.
+    """
+    if data_source not in ALLOWED_SOURCES:
+        raise ValueError(f"Invalid data source: {data_source}. Must be one of {ALLOWED_SOURCES}")
+
+    api_request_url = f"{API_BASE_URLS[data_source]}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}"
+
+    try:
+        webdriver_instance = setup_webdriver()
+        webdriver_instance.get(api_request_url)
+
+        response_element = WebDriverWait(webdriver_instance, element_load_timeout).until(
+            EC.visibility_of_element_located((By.TAG_NAME, "pre"))
+        )
+        response_text = response_element.text.strip()
+        if not response_text:
+            raise RuntimeError("API response is empty.")
+
+        api_response_data = json.loads(response_text)
+        if "events" not in api_response_data or not isinstance(api_response_data["events"], list):
+            raise ValueError("Invalid API response format: 'events' key is missing or not a list.")
+
+        events_df = pd.DataFrame(api_response_data.get("events", []))
+        if events_df.empty:
+            raise ValueError("No match data found for the specified parameters.")
+
+        fn_country = events_df.iloc[0]["tournament"].get("category", {}).get("name", "")
+        fn_tournament = events_df.iloc[0]["tournament"].get("name", "")
+        fn_season = events_df.iloc[0]["season"].get("year", "")
+        fn_week = week_number
+
+        custom_ids = events_df["customId"].tolist()
+        all_matches_data = []
+
+        for custom_id in custom_ids:
+            h2h_url = f"{API_BASE_URLS[data_source + '2']}/api/v1/event/{custom_id}/h2h/events"
+            webdriver_instance.get(h2h_url)
+            h2h_response_element = WebDriverWait(webdriver_instance, element_load_timeout).until(
+                EC.visibility_of_element_located((By.TAG_NAME, "pre"))
+            )
+            h2h_response_text = h2h_response_element.text.strip()
+            if not h2h_response_text:
+                continue
+
+            h2h_data = json.loads(h2h_response_text)
+            if "events" not in h2h_data or not isinstance(h2h_data["events"], list):
+                continue
+
+            for event in h2h_data["events"]:
+                match_info = {
+                    "country": event["tournament"].get("category", {}).get("name", ""),
+                    "tournament": event["tournament"].get("name", ""),
+                    "season": event["season"].get("year", ""),
+                    "week": event.get("roundInfo", {}).get("round", ""),
+                    "game_id": event.get("id", ""),
+                    "home_team": event["homeTeam"].get("name", ""),
+                    "home_team_id": event["homeTeam"].get("id", ""),
+                    "away_team": event["awayTeam"].get("name", ""),
+                    "away_team_id": event["awayTeam"].get("id", ""),
+                    "injury_time_1": event.get("time", {}).get("injuryTime1", ""),
+                    "injury_time_2": event.get("time", {}).get("injuryTime2", ""),
+                    "start_timestamp": event.get("startTimestamp", ""),
+                    "status": event["status"].get("description", ""),
+                    "home_score_current": event["homeScore"].get("current", ""),
+                    "home_score_display": event["homeScore"].get("display", ""),
+                    "home_score_period1": event["homeScore"].get("period1", ""),
+                    "home_score_period2": event["homeScore"].get("period2", ""),
+                    "home_score_normaltime": event["homeScore"].get("normaltime", ""),
+                    "away_score_current": event["awayScore"].get("current", ""),
+                    "away_score_display": event["awayScore"].get("display", ""),
+                    "away_score_period1": event["awayScore"].get("period1", ""),
+                    "away_score_period2": event["awayScore"].get("period2", ""),
+                    "away_score_normaltime": event["awayScore"].get("normaltime", "")
+                }
+                all_matches_data.append(match_info)
+
+        detailed_matches_df = pd.DataFrame(all_matches_data)
+
+        if enable_json_export or enable_excel_export:
+            if enable_json_export:
+                save_json(
+                    data=detailed_matches_df,
+                    data_source=data_source,
+                    country=fn_country,
+                    tournament=fn_tournament,
+                    season=fn_season,
+                    week_number=fn_week
+                )
+
+            if enable_excel_export:
+                save_excel(
+                    data=detailed_matches_df,
+                    data_source=data_source,
+                    country=fn_country,
+                    tournament=fn_tournament,
+                    season=fn_season,
+                    week_number=fn_week
+                )
+
+        return detailed_matches_df
+
+    except TimeoutException:
+        raise RuntimeError("Timeout occurred while waiting for the page or API response.")
+    except WebDriverException as e:
+        raise RuntimeError(f"Selenium WebDriver error: {str(e)}")
+    except json.JSONDecodeError:
+        raise RuntimeError("Failed to decode API response as JSON.")
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error while fetching past matches data: {e.__class__.__name__} - {e}")
+
+    finally:
+        if webdriver_instance:
+            webdriver_instance.quit()

datafc-1.3.0/datafc/utils/_config.py

@@ -0,0 +1,8 @@
+ALLOWED_SOURCES = {"sofavpn", "sofascore"}
+
+API_BASE_URLS = {
+    "sofavpn": "https://api.sofavpn.com",
+    "sofascore": "https://api.sofascore.com",
+    "sofavpn2": "https://www.sofavpn.com",
+    "sofascore2": "https://www.sofascore.com"
+}

{datafc-1.2.0 → datafc-1.3.0}/datafc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datafc
-Version: 1.2.0
+Version: 1.3.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.2.0
+# datafc v1.3.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.2.0
+pip install datafc==1.3.0
 ```
 
 If you already have `datafc` installed and want to upgrade to the latest version, run:
@@ -105,6 +105,7 @@ from datafc.sofascore import (
     match_odds_data,
     match_stats_data,
     momentum_data,
+    past_matches_data,
     lineups_data,
     coordinates_data,
     substitutions_data,
@@ -140,20 +141,19 @@ The `lineups_data` function fetches player lineup details for each match and is
 
 Without `lineups_data`, these dependent functions will not work as expected.
 
-Exception: `standings_data`
+Exception: `standings_data` and `past_matches_data`
 
-Unlike the other functions, `standings_data` does not require `match_data` or `lineups_data`. It can be executed independently using only `tournament_id` and `season_id`.
+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`.
 
 ### Match Data
 
 #### `match_data`
 
-The `match_data` function fetches match data for a specified tournament, season, and matchweek. It returns a DataFrame containing details such as country, tournament name, season, week number, game ID, home team, home team ID, away team, away team ID, added injury times for both halves, start timestamp, match status, and score-related information.
+The `match_data` function fetches match data for a specified tournament, season, and matchweek.
 
 Example Usage:
 
 ```python
-# Fetch match data for a specific tournament, season, and week
 match_df = match_data(
     tournament_id=52,
     season_id=63814,
@@ -210,12 +210,11 @@ Dependencies:
 
 #### `match_odds_data`
 
-The `match_odds_data` function fetches betting odds data for each match in the provided match dataset. It returns a DataFrame containing match odds details, including market names, odds values, and whether the odds changed.
+The `match_odds_data` function fetches betting odds data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match odds data
 match_odds_df = match_odds_data(
     match_df=match_df,
     data_source="sofascore",
@@ -258,12 +257,11 @@ Dependencies:
 
 #### `match_stats_data`
 
-The `match_stats_data` function fetches statistical data for each match in the provided match dataset. It returns a DataFrame containing key match statistics, including team performance metrics.
+The `match_stats_data` function fetches statistical data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch match statistics data
 match_stats_df = match_stats_data(
     match_df=match_df,
     data_source="sofascore",
@@ -303,12 +301,11 @@ Dependencies:
 
 #### `momentum_data`
 
-The `momentum_data` function fetches momentum data for each match in the provided match dataset. It returns a DataFrame containing match momentum values over time.
+The `momentum_data` function fetches momentum data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch momentum data
 momentum_df = momentum_data(
     match_df=match_df,
     data_source="sofascore",
@@ -343,16 +340,76 @@ Dependencies:
 
 * Requires `match_data` output as `match_df`.
 
+#### `past_matches_data`
+
+The `past_matches_data` function fetches past match data for a specified tournament, season, and week number.
+
+Example Usage:
+
+```python
+past_matches_df = past_matches_data(
+    tournament_id=52,
+    season_id=63814,
+    week_number=21,
+    data_source="sofascore",
+    enable_json_export=True,
+    enable_excel_export=True
+)
+
+print(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.
+* `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`, 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`.
+
+Data Structure:
+
+The returned DataFrame includes the following columns:
+
+* `country`: The country where the tournament is held.
+* `tournament`: The name of the tournament.
+* `season`: The season year.
+* `week`: The matchweek number.
+* `game_id`: The unique identifier for the match.
+* `home_team`: The name of the home team.
+* `home_team_id`: The unique identifier for the home team.
+* `away_team`: The name of the away team.
+* `away_team_id`: The unique identifier for the away team.
+* `injury_time_1`: Added injury time in the first half.
+* `injury_time_2`: Added injury time in the second half.
+* `start_timestamp`: The start time of the match.
+* `status`: The current status of the match.
+* `home_score_current`: The latest recorded score for the home team.
+* `home_score_display`: The displayed score of the home team.
+* `home_score_period1`: The home team's score at the end of the first half.
+* `home_score_period2`: The home team's goals scored in the second half.
+* `home_score_normaltime`: The home team's final score at the end of normal time (90 minutes).
+* `away_score_current`: The latest recorded score for the away team.
+* `away_score_display`: The displayed score of the away team.
+* `away_score_period1`: The away team's score at the end of the first half.
+* `away_score_period2`: The away team's goals scored in the second half.
+* `away_score_normaltime`: The away team's final score at the end of normal time (90 minutes).
+
+Dependencies:
+
+* No prior function dependency required.
+
 ### Player Data
 
 #### `lineups_data`
 
-The `lineups_data` function fetches lineup data for each match in the provided match dataset. It returns a DataFrame containing lineup details such as country, tournament name, season, week number, game ID, team, player name, player ID, statistic name, and statistic value.
+The `lineups_data` function fetches lineup data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch lineups data based on match data
 lineups_df = lineups_data(
     match_df=match_df,
     data_source="sofascore",
@@ -392,12 +449,11 @@ Dependencies:
 
 #### `coordinates_data`
 
-The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset. It returns a DataFrame containing coordinate details such as country, tournament name, season, week number, game ID, team, player ID, player name, and x-y coordinates.
+The `coordinates_data` function fetches coordinate data for each player in the provided lineup dataset.
 
 Example Usage:
 
 ```python
-# Fetch coordinates data
 coordinates_df = coordinates_data(
     lineups_df=lineups_df,
     data_source="sofascore",
@@ -437,12 +493,11 @@ Dependencies:
 
 #### `substitutions_data`
 
-The `substitutions_data` function fetches substitution data for each match in the provided match dataset. It returns a DataFrame containing details of player substitutions, including the players involved and the time of the substitution.
+The `substitutions_data` function fetches substitution data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch substitution data
 substitutions_df = substitutions_data(
     match_df=match_df,
     data_source="sofascore",
@@ -484,12 +539,11 @@ Dependencies:
 
 #### `goal_networks_data`
 
-The `goal_networks_data` function fetches goal network data for each match in the provided match dataset. It returns a DataFrame containing goal-related events, including passing networks and shot locations.
+The `goal_networks_data` function fetches goal network data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch goal networks data
 goal_networks_df = goal_networks_data(
     match_df=match_df,
     data_source="sofascore",
@@ -541,12 +595,11 @@ Dependencies:
 
 #### `shots_data`
 
-The `shots_data` function fetches shot data for each match in the provided match dataset. It returns a DataFrame containing detailed shot-related information, including player coordinates, xG values, shot types, and goal mouth locations.
+The `shots_data` function fetches shot data for each match in the provided match dataset.
 
 Example Usage:
 
 ```python
-# Fetch shot data
 shots_df = shots_data(
     match_df=match_df,
     data_source="sofascore",
@@ -608,12 +661,11 @@ Dependencies:
 
 #### `standings_data`
 
-The `standings_data` function fetches league standings for a specific tournament and season. It returns a DataFrame containing team rankings, match results, and points.
+The `standings_data` function fetches league standings for a specific tournament and season.
 
 Example Usage:
 
 ```python
-# Fetch league standings
 standings_df = standings_data(
     tournament_id=52,
     season_id=63814,
@@ -658,6 +710,9 @@ Dependencies:
 
 ## Changelog
 
+* v1.3.0
+  * Added `past_matches_data` function to fetch historical match data.
+
 * v1.2.0
   * Added match score columns to `match_data`
 

{datafc-1.2.0 → datafc-1.3.0}/datafc.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ datafc/sofascore/fetch_match_data.py
 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_shots_data.py
 datafc/sofascore/fetch_standings_data.py
 datafc/sofascore/fetch_substitutions_data.py

{datafc-1.2.0 → datafc-1.3.0}/setup.py

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

datafc-1.2.0/datafc/utils/_config.py

@@ -1,6 +0,0 @@
-ALLOWED_SOURCES = {"sofavpn", "sofascore"}
-
-API_BASE_URLS = {
-    "sofavpn": "https://api.sofavpn.com",
-    "sofascore": "https://api.sofascore.com"
-}