datafc 2.1.0__tar.gz → 2.3.0__tar.gz

{datafc-2.1.0 → datafc-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.1.0
+Version: 2.3.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -24,7 +24,7 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.1.0
+# datafc v2.3.0
 
 ## Overview
 
@@ -530,15 +530,34 @@ ucl_df = match_data(
     tournament_type="uefa",
     tournament_stage="round_of_16",
 )
+
+# World Cup knockout stages — week_number not needed:
+wc_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    tournament_type="world_cup",
+    tournament_stage="round_of_16",
+)
+
+# World Cup group stage — week_number required:
+wc_group_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    week_number=1,
+    tournament_type="world_cup",
+    tournament_stage="group_stage_week",
+)
 ```
 
 Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions. `None` assumes a domestic league.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup. `None` assumes a domestic league.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set.
+  - `"uefa"` options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+  - `"world_cup"` options: `group_stage_week`, `round_of_32`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
 
 Columns: `country`, `tournament`, `season`, `week`, `game_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`, `injury_time_1`, `injury_time_2`, `start_timestamp`, `status`, `home_score_current`, `home_score_display`, `home_score_period1`, `home_score_period2`, `home_score_normaltime`, `away_score_current`, `away_score_display`, `away_score_period1`, `away_score_period2`, `away_score_normaltime`.
 
@@ -775,9 +794,9 @@ Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Same options as `match_data`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set. Same options as `match_data`.
 
 Same columns as `match_data`.
 
@@ -897,6 +916,20 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## Changelog
 
+### v2.3.0
+
+- **Fixed `match_data` for World Cup knockout stages across all seasons.** Round numbers are now resolved automatically from the API instead of being hardcoded, so older seasons work correctly.
+- **Fixed `standings_data` for tournament-format competitions.** Calling this function for World Cup, Euro, or similar tournaments no longer raises an error. Only the available categories are returned.
+
+---
+
+### v2.2.0
+
+- Added `tournament_type="world_cup"` support to `match_data` and `past_matches_data` for FIFA World Cup competitions. Knockout stage rounds are fixed internally; only `group_stage_week` requires `week_number`.
+- `week_number` is now optional (`None` by default). It is required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Omitting it when required raises `InvalidParameterError`.
+
+---
+
 ### v2.1.0
 
 - Added `team_match_history_data`: fetches the complete match history for a single team across all competitions using `team_id` directly (no standings dependency).

{datafc-2.1.0 → datafc-2.3.0}/README.md

@@ -1,4 +1,4 @@
-# datafc v2.1.0
+# datafc v2.3.0
 
 ## Overview
 
@@ -504,15 +504,34 @@ ucl_df = match_data(
     tournament_type="uefa",
     tournament_stage="round_of_16",
 )
+
+# World Cup knockout stages — week_number not needed:
+wc_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    tournament_type="world_cup",
+    tournament_stage="round_of_16",
+)
+
+# World Cup group stage — week_number required:
+wc_group_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    week_number=1,
+    tournament_type="world_cup",
+    tournament_stage="group_stage_week",
+)
 ```
 
 Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions. `None` assumes a domestic league.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup. `None` assumes a domestic league.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set.
+  - `"uefa"` options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+  - `"world_cup"` options: `group_stage_week`, `round_of_32`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
 
 Columns: `country`, `tournament`, `season`, `week`, `game_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`, `injury_time_1`, `injury_time_2`, `start_timestamp`, `status`, `home_score_current`, `home_score_display`, `home_score_period1`, `home_score_period2`, `home_score_normaltime`, `away_score_current`, `away_score_display`, `away_score_period1`, `away_score_period2`, `away_score_normaltime`.
 
@@ -749,9 +768,9 @@ Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Same options as `match_data`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set. Same options as `match_data`.
 
 Same columns as `match_data`.
 
@@ -871,6 +890,20 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## Changelog
 
+### v2.3.0
+
+- **Fixed `match_data` for World Cup knockout stages across all seasons.** Round numbers are now resolved automatically from the API instead of being hardcoded, so older seasons work correctly.
+- **Fixed `standings_data` for tournament-format competitions.** Calling this function for World Cup, Euro, or similar tournaments no longer raises an error. Only the available categories are returned.
+
+---
+
+### v2.2.0
+
+- Added `tournament_type="world_cup"` support to `match_data` and `past_matches_data` for FIFA World Cup competitions. Knockout stage rounds are fixed internally; only `group_stage_week` requires `week_number`.
+- `week_number` is now optional (`None` by default). It is required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Omitting it when required raises `InvalidParameterError`.
+
+---
+
 ### v2.1.0
 
 - Added `team_match_history_data`: fetches the complete match history for a single team across all competitions using `team_id` directly (no standings dependency).

{datafc-2.1.0 → datafc-2.3.0}/datafc/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 from .sofascore import *
 from .exceptions import (

{datafc-2.1.0 → datafc-2.3.0}/datafc/sofascore/aio.py

@@ -35,7 +35,7 @@ import pandas as pd
 
 from datafc.utils._async_client import AsyncSofascoreClient
 from datafc.utils._cache import DiskCache
-from datafc.utils._config import API_URLS, WWW_URLS
+from datafc.utils._config import API_URLS, WWW_URLS, WORLD_CUP_KNOCKOUT_SLUGS
 from datafc.utils._validate import validate_source, validate_df, build_tournament_url
 from datafc.utils._save_files import save_json, save_excel
 from datafc.utils._tournament_info import resolve_tournament_season
@@ -77,7 +77,7 @@ logger = logging.getLogger(__name__)
 async def match_data(
     tournament_id: int,
     season_id: int,
-    week_number: int,
+    week_number: Optional[int] = None,
     tournament_type: Optional[str] = None,
     tournament_stage: Optional[str] = None,
     data_source: str = "sofascore",
@@ -89,6 +89,28 @@ async def match_data(
 ) -> pd.DataFrame:
     """Async version of match_data(). See sync docstring for full parameter docs."""
     validate_source(data_source)
+
+    if (
+        tournament_type == "world_cup"
+        and tournament_stage in WORLD_CUP_KNOCKOUT_SLUGS
+        and week_number is None
+    ):
+        target_slug = WORLD_CUP_KNOCKOUT_SLUGS[tournament_stage]
+        rounds_url = (
+            f"{API_URLS[data_source]}/api/v1/unique-tournament/{tournament_id}"
+            f"/season/{season_id}/rounds"
+        )
+        async with AsyncSofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+            rounds_data = await client.get(rounds_url)
+        rounds = rounds_data.get("rounds") or rounds_data.get("currentRounds") or []
+        matched = next((r for r in rounds if r.get("slug") == target_slug), None)
+        if matched is None:
+            raise DataNotAvailableError(
+                f"Could not find round with slug '{target_slug}' for "
+                f"tournament_id={tournament_id}, season_id={season_id}."
+            )
+        week_number = matched["round"]
+
     url = build_tournament_url(
         API_URLS[data_source], tournament_id, season_id, week_number,
         tournament_type, tournament_stage,
@@ -649,8 +671,11 @@ async def standings_data(
             f"{API_URLS[data_source]}/api/v1/unique-tournament/{tournament_id}"
             f"/season/{season_id}/standings/{category}"
         )
-        data = await client.get(url)
-        return parse_standings_rows(data, category, tournament_id, season_id)
+        try:
+            data = await client.get(url)
+            return parse_standings_rows(data, category, tournament_id, season_id)
+        except APIError:
+            return []
 
     async with AsyncSofascoreClient(rate_limit=rate_limit, cache=cache) as client:
         batches = await asyncio.gather(*[_fetch(client, cat) for cat in ("total", "home", "away")])
@@ -1173,7 +1198,7 @@ async def goal_networks_data(
 async def past_matches_data(
     tournament_id: int,
     season_id: int,
-    week_number: int,
+    week_number: Optional[int] = None,
     tournament_type: Optional[str] = None,
     tournament_stage: Optional[str] = None,
     data_source: str = "sofascore",

{datafc-2.1.0 → datafc-2.3.0}/datafc/sofascore/fetch_match_data.py

@@ -2,7 +2,7 @@ from typing import TYPE_CHECKING, Optional
 import pandas as pd
 from datafc.utils._client import SofascoreClient
 from datafc.utils._save_files import save_json, save_excel
-from datafc.utils._config import API_URLS
+from datafc.utils._config import API_URLS, WORLD_CUP_KNOCKOUT_SLUGS
 from datafc.utils._validate import validate_source, build_tournament_url
 from datafc.sofascore._parsers import parse_match_events
 from datafc.exceptions import DataNotAvailableError
@@ -14,7 +14,7 @@ if TYPE_CHECKING:
 def match_data(
     tournament_id: int,
     season_id: int,
-    week_number: int,
+    week_number: Optional[int] = None,
     tournament_type: Optional[str] = None,
     tournament_stage: Optional[str] = None,
     data_source: str = "sofascore",
@@ -31,7 +31,7 @@ def match_data(
         tournament_id: The unique identifier for the tournament.
         season_id: The unique identifier for the season.
         week_number: The matchweek number within the season.
-        tournament_type: The tournament type ('uefa'). If None, assumes league format.
+        tournament_type: The tournament type ('uefa', 'world_cup'). If None, assumes league format.
         tournament_stage: The specific stage of the tournament (e.g., 'group_stage_week', 'round_of_16').
         data_source: The data source ('sofavpn' or 'sofascore'). Defaults to 'sofascore'.
         rate_limit: Maximum requests per second. Defaults to 2.0.
@@ -49,6 +49,28 @@ def match_data(
         APIError: On HTTP errors from the Sofascore API.
     """
     validate_source(data_source)
+
+    if (
+        tournament_type == "world_cup"
+        and tournament_stage in WORLD_CUP_KNOCKOUT_SLUGS
+        and week_number is None
+    ):
+        target_slug = WORLD_CUP_KNOCKOUT_SLUGS[tournament_stage]
+        rounds_url = (
+            f"{API_URLS[data_source]}/api/v1/unique-tournament/{tournament_id}"
+            f"/season/{season_id}/rounds"
+        )
+        with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+            rounds_data = client.get(rounds_url)
+        rounds = rounds_data.get("rounds") or rounds_data.get("currentRounds") or []
+        matched = next((r for r in rounds if r.get("slug") == target_slug), None)
+        if matched is None:
+            raise DataNotAvailableError(
+                f"Could not find round with slug '{target_slug}' for "
+                f"tournament_id={tournament_id}, season_id={season_id}."
+            )
+        week_number = matched["round"]
+
     url = build_tournament_url(
         API_URLS[data_source], tournament_id, season_id, week_number,
         tournament_type, tournament_stage,

{datafc-2.1.0 → datafc-2.3.0}/datafc/sofascore/fetch_past_matches_data.py

@@ -13,7 +13,7 @@ if TYPE_CHECKING:
 def past_matches_data(
     tournament_id: int,
     season_id: int,
-    week_number: int,
+    week_number: Optional[int] = None,
     tournament_type: Optional[str] = None,
     tournament_stage: Optional[str] = None,
     data_source: str = "sofascore",
@@ -30,7 +30,7 @@ def past_matches_data(
         tournament_id: The unique identifier for the tournament.
         season_id: The unique identifier for the season.
         week_number: The matchweek number within the season.
-        tournament_type: The tournament type ('uefa'). If None, assumes league format.
+        tournament_type: The tournament type ('uefa', 'world_cup'). If None, assumes league format.
         tournament_stage: The specific stage of the tournament (e.g., 'group_stage_week', 'round_of_16').
         data_source: The data source ('sofavpn' or 'sofascore'). Defaults to 'sofascore'.
         rate_limit: Maximum requests per second. Defaults to 2.0.

{datafc-2.1.0 → datafc-2.3.0}/datafc/sofascore/fetch_standings_data.py

@@ -6,7 +6,7 @@ from datafc.utils._config import API_URLS
 from datafc.utils._validate import validate_source
 from datafc.utils._tournament_info import resolve_tournament_season
 from datafc.sofascore._parsers import parse_standings_rows
-from datafc.exceptions import DataNotAvailableError
+from datafc.exceptions import APIError, DataNotAvailableError
 
 if TYPE_CHECKING:
     from datafc.utils._cache import DiskCache
@@ -51,8 +51,11 @@ def standings_data(
                 f"{API_URLS[data_source]}/api/v1/unique-tournament/{tournament_id}"
                 f"/season/{season_id}/standings/{category}"
             )
-            data = client.get(url)
-            rows.extend(parse_standings_rows(data, category, tournament_id, season_id))
+            try:
+                data = client.get(url)
+                rows.extend(parse_standings_rows(data, category, tournament_id, season_id))
+            except APIError:
+                pass
 
     result_df = pd.DataFrame(rows)
     if result_df.empty:

{datafc-2.1.0 → datafc-2.3.0}/datafc/sofascore/fetch_team_match_history_data.py

@@ -1,108 +1,108 @@
-import logging
-from typing import TYPE_CHECKING, Optional
-import pandas as pd
-from datafc.utils._client import SofascoreClient
-from datafc.utils._save_files import save_json, save_excel
-from datafc.utils._config import API_URLS
-from datafc.utils._validate import validate_source
-from datafc.utils._helpers import _cast_int_cols
-from datafc.sofascore._parsers import parse_team_match_history_records
-from datafc.exceptions import APIError, DataNotAvailableError
-
-if TYPE_CHECKING:
-    from datafc.utils._cache import DiskCache
-
-logger = logging.getLogger(__name__)
-
-
-def team_match_history_data(
-    team_id: int,
-    data_source: str = "sofascore",
-    rate_limit: float = 2.0,
-    cache: Optional["DiskCache"] = None,
-    enable_json_export: bool = False,
-    enable_excel_export: bool = False,
-    output_dir: str = ".",
-) -> pd.DataFrame:
-    """
-    Fetches the complete match history for a single team across all competitions.
-
-    Paginates through all available history pages until no further pages exist.
-    The team_id can be obtained from standings_data(), squad_data(), or search_data().
-
-    Args:
-        team_id: The unique Sofascore identifier for the team.
-        data_source: The data source ('sofavpn' or 'sofascore'). Defaults to 'sofascore'.
-        rate_limit: Maximum requests per second. Defaults to 2.0.
-        cache: Optional DiskCache instance. Cached responses skip the API call.
-        enable_json_export: If True, saves output as JSON. Defaults to False.
-        enable_excel_export: If True, saves output as Excel. Defaults to False.
-        output_dir: Directory for exported files. Defaults to current directory.
-
-    Returns:
-        Past matches with country, tournament, season, week, home/away team names,
-        IDs, scores, start timestamp and status; sorted by start_timestamp ascending.
-
-    Raises:
-        InvalidParameterError: If an invalid data_source is given.
-        DataNotAvailableError: If no historical match data is found for the team.
-        APIError: On HTTP errors from the Sofascore API.
-    """
-    validate_source(data_source)
-
-    seen_game_ids: set = set()
-    records = []
-    page = 0
-
-    with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
-        while True:
-            url = f"{API_URLS[data_source]}/api/v1/team/{team_id}/events/last/{page}"
-            try:
-                data = client.get(url)
-            except APIError as exc:
-                logger.warning(
-                    "Failed to fetch match history for team_id=%s page=%s: %s",
-                    team_id, page, exc,
-                )
-                break
-
-            batch = parse_team_match_history_records(data, seen_game_ids)
-            records.extend(batch)
-
-            if not data.get("hasNextPage", False):
-                break
-            page += 1
-
-    result_df = pd.DataFrame(records)
-    if result_df.empty:
-        raise DataNotAvailableError(
-            f"No historical match data found for team_id={team_id}."
-        )
-
-    result_df = result_df.sort_values("start_timestamp").reset_index(drop=True)
-    result_df = _cast_int_cols(
-        result_df,
-        "week",
-        "home_team_id", "away_team_id",
-        "home_score_period1", "home_score_period2", "home_score_normaltime",
-        "home_score_display", "home_score_current",
-        "away_score_period1", "away_score_period2", "away_score_normaltime",
-        "away_score_display", "away_score_current",
-        "start_timestamp",
-    )
-
-    if enable_json_export or enable_excel_export:
-        first = result_df.iloc[0]
-        kwargs = dict(
-            fn_name="team_match_history_data",
-            data_source=data_source,
-            country=first.get("country", ""),
-            tournament=first.get("tournament", ""),
-            season=first.get("season"),
-        )
-        if enable_json_export:
-            save_json(data=result_df, **kwargs, output_dir=output_dir)
-        if enable_excel_export:
-            save_excel(data=result_df, **kwargs, output_dir=output_dir)
-
-    return result_df
+import logging
+from typing import TYPE_CHECKING, Optional
+import pandas as pd
+from datafc.utils._client import SofascoreClient
+from datafc.utils._save_files import save_json, save_excel
+from datafc.utils._config import API_URLS
+from datafc.utils._validate import validate_source
+from datafc.utils._helpers import _cast_int_cols
+from datafc.sofascore._parsers import parse_team_match_history_records
+from datafc.exceptions import APIError, DataNotAvailableError
+
+if TYPE_CHECKING:
+    from datafc.utils._cache import DiskCache
+
+logger = logging.getLogger(__name__)
+
+
+def team_match_history_data(
+    team_id: int,
+    data_source: str = "sofascore",
+    rate_limit: float = 2.0,
+    cache: Optional["DiskCache"] = None,
+    enable_json_export: bool = False,
+    enable_excel_export: bool = False,
+    output_dir: str = ".",
+) -> pd.DataFrame:
+    """
+    Fetches the complete match history for a single team across all competitions.
+
+    Paginates through all available history pages until no further pages exist.
+    The team_id can be obtained from standings_data(), squad_data(), or search_data().
+
+    Args:
+        team_id: The unique Sofascore identifier for the team.
+        data_source: The data source ('sofavpn' or 'sofascore'). Defaults to 'sofascore'.
+        rate_limit: Maximum requests per second. Defaults to 2.0.
+        cache: Optional DiskCache instance. Cached responses skip the API call.
+        enable_json_export: If True, saves output as JSON. Defaults to False.
+        enable_excel_export: If True, saves output as Excel. Defaults to False.
+        output_dir: Directory for exported files. Defaults to current directory.
+
+    Returns:
+        Past matches with country, tournament, season, week, home/away team names,
+        IDs, scores, start timestamp and status; sorted by start_timestamp ascending.
+
+    Raises:
+        InvalidParameterError: If an invalid data_source is given.
+        DataNotAvailableError: If no historical match data is found for the team.
+        APIError: On HTTP errors from the Sofascore API.
+    """
+    validate_source(data_source)
+
+    seen_game_ids: set = set()
+    records = []
+    page = 0
+
+    with SofascoreClient(rate_limit=rate_limit, cache=cache) as client:
+        while True:
+            url = f"{API_URLS[data_source]}/api/v1/team/{team_id}/events/last/{page}"
+            try:
+                data = client.get(url)
+            except APIError as exc:
+                logger.warning(
+                    "Failed to fetch match history for team_id=%s page=%s: %s",
+                    team_id, page, exc,
+                )
+                break
+
+            batch = parse_team_match_history_records(data, seen_game_ids)
+            records.extend(batch)
+
+            if not data.get("hasNextPage", False):
+                break
+            page += 1
+
+    result_df = pd.DataFrame(records)
+    if result_df.empty:
+        raise DataNotAvailableError(
+            f"No historical match data found for team_id={team_id}."
+        )
+
+    result_df = result_df.sort_values("start_timestamp").reset_index(drop=True)
+    result_df = _cast_int_cols(
+        result_df,
+        "week",
+        "home_team_id", "away_team_id",
+        "home_score_period1", "home_score_period2", "home_score_normaltime",
+        "home_score_display", "home_score_current",
+        "away_score_period1", "away_score_period2", "away_score_normaltime",
+        "away_score_display", "away_score_current",
+        "start_timestamp",
+    )
+
+    if enable_json_export or enable_excel_export:
+        first = result_df.iloc[0]
+        kwargs = dict(
+            fn_name="team_match_history_data",
+            data_source=data_source,
+            country=first.get("country", ""),
+            tournament=first.get("tournament", ""),
+            season=first.get("season"),
+        )
+        if enable_json_export:
+            save_json(data=result_df, **kwargs, output_dir=output_dir)
+        if enable_excel_export:
+            save_excel(data=result_df, **kwargs, output_dir=output_dir)
+
+    return result_df

{datafc-2.1.0 → datafc-2.3.0}/datafc/utils/_config.py

@@ -40,6 +40,26 @@ TOURNAMENT_URL_PATTERNS = {
         "match_for_3rd_place": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/match-for-3rd-place",
         "final": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/final",
     },
+    "world_cup": {
+        "group_stage_week": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}",
+        "round_of_32": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/round-of-32",
+        "round_of_16": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/round-of-16",
+        "quarterfinals": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/quarterfinals",
+        "semifinals": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/semifinals",
+        "match_for_3rd_place": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/match-for-3rd-place",
+        "final": "{base_url}/api/v1/unique-tournament/{tournament_id}/season/{season_id}/events/round/{week_number}/slug/final",
+    },
+}
+
+# Slug used in the API URL for each world_cup knockout stage.
+# Used to auto-resolve the season-specific round number via the /rounds endpoint.
+WORLD_CUP_KNOCKOUT_SLUGS: dict[str, str] = {
+    "round_of_32": "round-of-32",
+    "round_of_16": "round-of-16",
+    "quarterfinals": "quarterfinals",
+    "semifinals": "semifinals",
+    "match_for_3rd_place": "match-for-3rd-place",
+    "final": "final",
 }
 
 # ---------------------------------------------------------------------------

{datafc-2.1.0 → datafc-2.3.0}/datafc/utils/_validate.py

@@ -75,7 +75,7 @@ def build_tournament_url(
     base_url: str,
     tournament_id: int,
     season_id: int,
-    week_number: int,
+    week_number: Optional[int],
     tournament_type: Optional[str],
     tournament_stage: Optional[str],
 ) -> str:
@@ -84,13 +84,14 @@ def build_tournament_url(
     if tournament_type is not None:
         validate_tournament_type(tournament_type)
         validate_tournament_stage(tournament_type, tournament_stage)
-        return patterns[tournament_type][tournament_stage].format(
-            base_url=base_url,
-            tournament_id=tournament_id,
-            season_id=season_id,
-            week_number=week_number,
+        template = patterns[tournament_type][tournament_stage]
+    else:
+        template = patterns["default"]
+    if "{week_number}" in template and week_number is None:
+        raise InvalidParameterError(
+            "week_number is required for this tournament_type/tournament_stage combination."
         )
-    return patterns["default"].format(
+    return template.format(
         base_url=base_url,
         tournament_id=tournament_id,
         season_id=season_id,

{datafc-2.1.0 → datafc-2.3.0}/datafc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datafc
-Version: 2.1.0
+Version: 2.3.0
 Summary: Fetch, process, and export structured football data.
 Author-email: Uraz Akgül <urazdev@gmail.com>
 License: MIT
@@ -24,7 +24,7 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
 Dynamic: license-file
 
-# datafc v2.1.0
+# datafc v2.3.0
 
 ## Overview
 
@@ -530,15 +530,34 @@ ucl_df = match_data(
     tournament_type="uefa",
     tournament_stage="round_of_16",
 )
+
+# World Cup knockout stages — week_number not needed:
+wc_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    tournament_type="world_cup",
+    tournament_stage="round_of_16",
+)
+
+# World Cup group stage — week_number required:
+wc_group_df = match_data(
+    tournament_id=16,
+    season_id=58210,
+    week_number=1,
+    tournament_type="world_cup",
+    tournament_stage="group_stage_week",
+)
 ```
 
 Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions. `None` assumes a domestic league.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup. `None` assumes a domestic league.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set.
+  - `"uefa"` options: `preliminary_semifinals`, `preliminary_final`, `qualification_round`, `qualification_playoff`, `group_stage_week`, `playoff_round`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
+  - `"world_cup"` options: `group_stage_week`, `round_of_32`, `round_of_16`, `quarterfinals`, `semifinals`, `match_for_3rd_place`, `final`.
 
 Columns: `country`, `tournament`, `season`, `week`, `game_id`, `home_team`, `home_team_id`, `away_team`, `away_team_id`, `injury_time_1`, `injury_time_2`, `start_timestamp`, `status`, `home_score_current`, `home_score_display`, `home_score_period1`, `home_score_period2`, `home_score_normaltime`, `away_score_current`, `away_score_display`, `away_score_period1`, `away_score_period2`, `away_score_normaltime`.
 
@@ -775,9 +794,9 @@ Parameters:
 
 - `tournament_id` (int)
 - `season_id` (int)
-- `week_number` (int)
-- `tournament_type` (str, optional): `"uefa"` for UEFA competitions.
-- `tournament_stage` (str, optional): Required when `tournament_type="uefa"`. Same options as `match_data`.
+- `week_number` (int, optional): Required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Not needed for other `world_cup` stages.
+- `tournament_type` (str, optional): `"uefa"` for UEFA competitions, `"world_cup"` for FIFA World Cup.
+- `tournament_stage` (str, optional): Required when `tournament_type` is set. Same options as `match_data`.
 
 Same columns as `match_data`.
 
@@ -897,6 +916,20 @@ Columns: `referee_id`, `referee_name`, `tournament_id`, `tournament_name`, `stat
 
 ## Changelog
 
+### v2.3.0
+
+- **Fixed `match_data` for World Cup knockout stages across all seasons.** Round numbers are now resolved automatically from the API instead of being hardcoded, so older seasons work correctly.
+- **Fixed `standings_data` for tournament-format competitions.** Calling this function for World Cup, Euro, or similar tournaments no longer raises an error. Only the available categories are returned.
+
+---
+
+### v2.2.0
+
+- Added `tournament_type="world_cup"` support to `match_data` and `past_matches_data` for FIFA World Cup competitions. Knockout stage rounds are fixed internally; only `group_stage_week` requires `week_number`.
+- `week_number` is now optional (`None` by default). It is required for league rounds, UEFA stages, and `world_cup` + `group_stage_week`. Omitting it when required raises `InvalidParameterError`.
+
+---
+
 ### v2.1.0
 
 - Added `team_match_history_data`: fetches the complete match history for a single team across all competitions using `team_id` directly (no standings dependency).

{datafc-2.1.0 → datafc-2.3.0}/pyproject.toml

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