transfermarkt-api 5.0.0__py3-none-any.whl

transfermarkt_api/__init__.py

@@ -0,0 +1,23 @@
+"""Async Python access to Transfermarkt data."""
+
+from transfermarkt_api._version import __version__ as __version__
+from transfermarkt_api.cache import CacheConfig as CacheConfig
+from transfermarkt_api.client import Transfermarkt as Transfermarkt
+from transfermarkt_api.exceptions import (
+    EndpointUnavailable as EndpointUnavailable,
+)
+from transfermarkt_api.exceptions import (
+    NotFound as NotFound,
+)
+from transfermarkt_api.exceptions import (
+    TransfermarktError as TransfermarktError,
+)
+from transfermarkt_api.exceptions import (
+    UpstreamBlocked as UpstreamBlocked,
+)
+from transfermarkt_api.exceptions import (
+    UpstreamError as UpstreamError,
+)
+from transfermarkt_api.exceptions import (
+    UpstreamTimeout as UpstreamTimeout,
+)

transfermarkt_api/_version.py

@@ -0,0 +1,3 @@
+"""Release version shared by the SDK and server."""
+
+__version__ = "5.0.0"

transfermarkt_api/cache.py

@@ -0,0 +1,20 @@
+"""Configuration for the SDK's per-client response caches."""
+
+from dataclasses import dataclass
+from math import isfinite
+
+
+@dataclass(frozen=True)
+class CacheConfig:
+    """Successful response TTLs (seconds) and cache capacity."""
+
+    ttl: float = 600
+    reference_ttl: float = 86_400
+    max_entries: int = 2_000
+
+    def __post_init__(self) -> None:
+        """Reject unusable cache settings before allocating resources."""
+        if not isinstance(self.max_entries, int) or isinstance(self.max_entries, bool) or self.max_entries < 1:
+            raise ValueError("max_entries must be a positive integer")
+        if not all(isfinite(value) and value > 0 for value in (self.ttl, self.reference_ttl)):
+            raise ValueError("cache TTLs must be finite and positive")

transfermarkt_api/client.py

@@ -0,0 +1,226 @@
+"""Typed async facade over the upstream assembly services."""
+
+from collections.abc import Awaitable, Callable
+from types import TracebackType
+from typing import Any, NoReturn, Self, TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from transfermarkt_api.cache import CacheConfig
+from transfermarkt_api.exceptions import EndpointUnavailable, UpstreamError
+from transfermarkt_api.schemas import (
+    Achievements,
+    ClubListing,
+    ClubPlayers,
+    ClubProfile,
+    ClubSearch,
+    CoachProfile,
+    CoachSearch,
+    CompetitionClubs,
+    CompetitionSearch,
+    CompetitionSeasons,
+    CompetitionTable,
+    Countries,
+    Game,
+    PlayerAbsences,
+    PlayerInjuries,
+    PlayerMarketValue,
+    PlayerMatches,
+    PlayerNationalCareer,
+    PlayerProfile,
+    PlayerSearch,
+    PlayerStats,
+    PlayerTransfers,
+)
+from transfermarkt_api.services import countries
+from transfermarkt_api.services.clubs import achievements as club_achievements
+from transfermarkt_api.services.clubs import listing as club_listing
+from transfermarkt_api.services.clubs import players as club_players
+from transfermarkt_api.services.clubs import profile as club_profile
+from transfermarkt_api.services.clubs import search as club_search
+from transfermarkt_api.services.coaches import profile as coach_profile
+from transfermarkt_api.services.coaches import search as coach_search
+from transfermarkt_api.services.competitions import clubs as competition_clubs
+from transfermarkt_api.services.competitions import search as competition_search
+from transfermarkt_api.services.competitions import seasons as competition_seasons
+from transfermarkt_api.services.competitions import table as competition_table
+from transfermarkt_api.services.games import game
+from transfermarkt_api.services.players import absences as player_absences
+from transfermarkt_api.services.players import achievements as player_achievements
+from transfermarkt_api.services.players import injuries as player_injuries
+from transfermarkt_api.services.players import market_value as player_market_value
+from transfermarkt_api.services.players import matches as player_matches
+from transfermarkt_api.services.players import national_career as player_national_career
+from transfermarkt_api.services.players import profile as player_profile
+from transfermarkt_api.services.players import search as player_search
+from transfermarkt_api.services.players import stats as player_stats
+from transfermarkt_api.services.players import transfers as player_transfers
+from transfermarkt_api.tfmkt import TfmktClient
+from transfermarkt_api.tfmkt.freshness import fetch_scope
+
+Model = TypeVar("Model", bound=BaseModel)
+
+
+class Transfermarkt:
+    """Async data client; owns its transport and supports one event loop per instance."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://tmapi.transfermarkt.technology",
+        timeout: float | httpx.Timeout | None = 15.0,
+        max_concurrency: int = 10,
+        transport: httpx.AsyncBaseTransport | None = None,
+        cache: CacheConfig | None = CacheConfig(),
+    ) -> None:
+        """Configure upstream access; cache=None disables ordinary and reference caching."""
+        self._client = TfmktClient(
+            base_url=base_url,
+            timeout=timeout,
+            max_concurrency=max_concurrency,
+            transport=transport,
+            cache=cache,
+        )
+
+    async def __aenter__(self) -> Self:
+        """Enter this client's lifetime without making a request."""
+        if self._client.http.is_closed:
+            raise RuntimeError("Transfermarkt client is closed")
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the owned transport, including when the body raises."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the owned HTTP client and transport; safe to call more than once."""
+        await self._client.aclose()
+
+    async def _call(self, model: type[Model], service: Callable[..., Awaitable[dict]], *args: Any) -> Model:
+        with fetch_scope():
+            data = await service(self._client, *args)
+            try:
+                return model.model_validate(data)
+            except ValidationError as error:
+                raise UpstreamError(f"Unexpected upstream payload for {model.__name__}") from error
+
+    async def countries(self) -> Countries:
+        """List country metadata, including historical entries."""
+        return await self._call(Countries, countries.list_countries)
+
+    async def clubs(self, country_id: int) -> ClubListing:
+        """List the available clubs for a country."""
+        _positive_integer(country_id, "country_id")
+        return await self._call(ClubListing, club_listing.list_clubs, country_id)
+
+    async def search_clubs(self, club_name: str, *, page_number: int = 1) -> ClubSearch:
+        """Search clubs, returning one page."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(ClubSearch, club_search.search_clubs, club_name, page_number)
+
+    async def club_profile(self, club_id: str) -> ClubProfile:
+        """Get a club's profile."""
+        return await self._call(ClubProfile, club_profile.get_club_profile, club_id)
+
+    async def club_players(self, club_id: str, *, season_id: str | None = None) -> ClubPlayers:
+        """Get the current or historical squad of a club."""
+        return await self._call(ClubPlayers, club_players.get_club_players, club_id, season_id)
+
+    async def club_achievements(self, club_id: str) -> Achievements:
+        """Get a club's titles."""
+        return await self._call(Achievements, club_achievements.get_club_achievements, club_id)
+
+    async def search_players(self, player_name: str, *, page_number: int = 1) -> PlayerSearch:
+        """Search players, returning one page."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(PlayerSearch, player_search.search_players, player_name, page_number)
+
+    async def player_profile(self, player_id: str) -> PlayerProfile:
+        """Get a player's profile."""
+        return await self._call(PlayerProfile, player_profile.get_player_profile, player_id)
+
+    async def player_market_value(self, player_id: str) -> PlayerMarketValue:
+        """Get current and historical player valuations."""
+        return await self._call(PlayerMarketValue, player_market_value.get_player_market_value, player_id)
+
+    async def player_transfers(self, player_id: str) -> PlayerTransfers:
+        """Get a player's transfer history."""
+        return await self._call(PlayerTransfers, player_transfers.get_player_transfers, player_id)
+
+    async def player_stats(self, player_id: str) -> PlayerStats:
+        """Get a player's club statistics by season and competition."""
+        return await self._call(PlayerStats, player_stats.get_player_stats, player_id)
+
+    async def player_matches(
+        self, player_id: str, *, season_id: str | None = None, page_number: int = 1
+    ) -> PlayerMatches:
+        """Get one page of past matches, optionally filtered by season."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(PlayerMatches, player_matches.get_player_matches, player_id, page_number, season_id)
+
+    async def player_injuries(self, player_id: str, *, page_number: int = 1) -> PlayerInjuries:
+        """Get one page of a player's injuries."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(PlayerInjuries, player_injuries.get_player_injuries, player_id, page_number)
+
+    async def player_absences(self, player_id: str, *, page_number: int = 1) -> PlayerAbsences:
+        """Get one page of a player's non-injury absences."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(PlayerAbsences, player_absences.get_player_absences, player_id, page_number)
+
+    async def player_achievements(self, player_id: str) -> Achievements:
+        """Get a player's titles and awards."""
+        return await self._call(Achievements, player_achievements.get_player_achievements, player_id)
+
+    async def player_national_career(self, player_id: str) -> PlayerNationalCareer:
+        """Get a player's senior and youth national teams."""
+        return await self._call(PlayerNationalCareer, player_national_career.get_player_national_career, player_id)
+
+    async def search_coaches(self, coach_name: str, *, page_number: int = 1) -> CoachSearch:
+        """Search coaches, returning one page."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(CoachSearch, coach_search.search_coaches, coach_name, page_number)
+
+    async def coach_profile(self, coach_id: str) -> CoachProfile:
+        """Get a coach's profile."""
+        return await self._call(CoachProfile, coach_profile.get_coach_profile, coach_id)
+
+    async def search_competitions(self, competition_name: str, *, page_number: int = 1) -> CompetitionSearch:
+        """Search competitions, returning one page."""
+        _positive_integer(page_number, "page_number")
+        return await self._call(
+            CompetitionSearch, competition_search.search_competitions, competition_name, page_number
+        )
+
+    async def competition_clubs(self, competition_id: str, *, season_id: str | None = None) -> CompetitionClubs:
+        """Get the clubs in a competition season."""
+        return await self._call(CompetitionClubs, competition_clubs.get_competition_clubs, competition_id, season_id)
+
+    async def competition_table(self, competition_id: str, *, season_id: str | None = None) -> CompetitionTable:
+        """Get the league or group tables in a competition season."""
+        return await self._call(CompetitionTable, competition_table.get_competition_table, competition_id, season_id)
+
+    async def competition_seasons(self, competition_id: str) -> CompetitionSeasons:
+        """Get the available seasons for a competition."""
+        return await self._call(CompetitionSeasons, competition_seasons.get_competition_seasons, competition_id)
+
+    async def game(self, game_id: str) -> Game:
+        """Get match details, lineups, statistics and events."""
+        return await self._call(Game, game.get_game, game_id)
+
+    async def player_jersey_numbers(self, player_id: str) -> NoReturn:
+        """Raise EndpointUnavailable: upstream provides no jersey-number history."""
+        raise EndpointUnavailable(
+            "Jersey number history is not available: Transfermarkt's JSON API has no equivalent data."
+        )
+
+
+def _positive_integer(value: int, name: str) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise ValueError(f"{name} must be a positive integer")

transfermarkt_api/exceptions.py

@@ -0,0 +1,31 @@
+"""Failures exposed to SDK consumers, independent of the HTTP server."""
+
+
+class TransfermarktError(Exception):
+    """Base class for failures fetching or assembling Transfermarkt data."""
+
+    def __init__(self, message: str, *, url: str | None = None, status_code: int | None = None) -> None:
+        """Attach upstream request metadata when available."""
+        super().__init__(message)
+        self.url = url
+        self.status_code = status_code
+
+
+class NotFound(TransfermarktError):
+    """The requested entity does not exist upstream."""
+
+
+class UpstreamBlocked(TransfermarktError):
+    """Upstream challenged or refused the request."""
+
+
+class UpstreamTimeout(TransfermarktError):
+    """An upstream request timed out."""
+
+
+class UpstreamError(TransfermarktError):
+    """An upstream connection, response or assembled model was invalid."""
+
+
+class EndpointUnavailable(TransfermarktError):
+    """There is no upstream data source for this endpoint."""

transfermarkt_api/schemas/__init__.py

@@ -0,0 +1,24 @@
+"""Public typed response models; nested models also live in their resource modules."""
+
+from transfermarkt_api.schemas.achievements import Achievements as Achievements
+from transfermarkt_api.schemas.clubs import ClubPlayers as ClubPlayers
+from transfermarkt_api.schemas.clubs import ClubProfile as ClubProfile
+from transfermarkt_api.schemas.clubs import ClubSearch as ClubSearch
+from transfermarkt_api.schemas.clubs.listing import ClubListing as ClubListing
+from transfermarkt_api.schemas.coaches import CoachProfile as CoachProfile
+from transfermarkt_api.schemas.coaches import CoachSearch as CoachSearch
+from transfermarkt_api.schemas.competitions import CompetitionClubs as CompetitionClubs
+from transfermarkt_api.schemas.competitions import CompetitionSearch as CompetitionSearch
+from transfermarkt_api.schemas.competitions import CompetitionSeasons as CompetitionSeasons
+from transfermarkt_api.schemas.competitions import CompetitionTable as CompetitionTable
+from transfermarkt_api.schemas.countries import Countries as Countries
+from transfermarkt_api.schemas.games import Game as Game
+from transfermarkt_api.schemas.players import PlayerAbsences as PlayerAbsences
+from transfermarkt_api.schemas.players import PlayerInjuries as PlayerInjuries
+from transfermarkt_api.schemas.players import PlayerMarketValue as PlayerMarketValue
+from transfermarkt_api.schemas.players import PlayerMatches as PlayerMatches
+from transfermarkt_api.schemas.players import PlayerNationalCareer as PlayerNationalCareer
+from transfermarkt_api.schemas.players import PlayerProfile as PlayerProfile
+from transfermarkt_api.schemas.players import PlayerSearch as PlayerSearch
+from transfermarkt_api.schemas.players import PlayerStats as PlayerStats
+from transfermarkt_api.schemas.players import PlayerTransfers as PlayerTransfers

transfermarkt_api/schemas/achievements.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class AchievementEntity(TransfermarktBaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+
+
+class AchievementDetail(TransfermarktBaseModel):
+    season: AchievementEntity
+    club: Optional[AchievementEntity] = None
+    competition: Optional[AchievementEntity] = None
+
+
+class Achievement(TransfermarktBaseModel):
+    title: str
+    count: int
+    details: list[AchievementDetail]
+
+
+class Achievements(TransfermarktBaseModel, AuditMixin):
+    id: str
+    achievements: list[Achievement]

transfermarkt_api/schemas/base.py

@@ -0,0 +1,17 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from transfermarkt_api.tfmkt.freshness import data_fetched_at
+
+
+class AuditMixin(BaseModel):
+    updated_at: datetime = Field(
+        default_factory=data_fetched_at,
+        description="When the upstream data in this response was fetched (oldest fetch if served from cache).",
+    )
+
+
+class TransfermarktBaseModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel)

transfermarkt_api/schemas/clubs/__init__.py

@@ -0,0 +1,3 @@
+from transfermarkt_api.schemas.clubs.players import ClubPlayers as ClubPlayers
+from transfermarkt_api.schemas.clubs.profile import ClubProfile as ClubProfile
+from transfermarkt_api.schemas.clubs.search import ClubSearch as ClubSearch

transfermarkt_api/schemas/clubs/listing.py

@@ -0,0 +1,14 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class ListedClub(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class ClubListing(TransfermarktBaseModel, AuditMixin):
+    country_id: int
+    country_name: str
+    clubs: list[ListedClub]

transfermarkt_api/schemas/clubs/players.py

@@ -0,0 +1,30 @@
+from datetime import date
+from typing import Optional
+
+from pydantic import HttpUrl
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class ClubPlayer(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    image_url: Optional[HttpUrl] = None
+    position: Optional[str] = None
+    shirt_number: Optional[int] = None
+    is_captain: Optional[bool] = None
+    date_of_birth: Optional[date] = None
+    age: Optional[int] = None
+    nationality: list[str]
+    current_club: Optional[str] = None
+    height: Optional[int] = None
+    foot: Optional[str] = None
+    joined_on: Optional[date] = None
+    signed_from: Optional[str] = None
+    contract: Optional[date] = None
+    market_value: Optional[int] = None
+
+
+class ClubPlayers(TransfermarktBaseModel, AuditMixin):
+    id: str
+    players: list[ClubPlayer]

transfermarkt_api/schemas/clubs/profile.py

@@ -0,0 +1,82 @@
+from datetime import date
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class ClubSquad(TransfermarktBaseModel):
+    size: Optional[int] = None
+    average_age: Optional[float] = None
+    foreigners: Optional[int] = None
+    national_team_players: Optional[int] = None
+    domestic_players: Optional[int] = None
+    average_market_value: Optional[int] = None
+    acquisition_value: Optional[int] = None
+    top_18_players_market_value: Optional[int] = None
+    top_18_share_percentage: Optional[float] = None
+
+
+class ClubCoach(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    since: Optional[date] = None
+
+
+class ClubLeague(TransfermarktBaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    country_id: Optional[str] = None
+    country_name: Optional[str] = None
+    tier: Optional[str] = None
+
+
+class ClubHistoricalName(TransfermarktBaseModel):
+    name: Optional[str] = None
+    short_name: Optional[str] = None
+    abbreviation: Optional[str] = None
+    season_id: Optional[str] = None
+
+
+class ClubStadium(TransfermarktBaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    capacity: Optional[int] = None
+    international_capacity: Optional[int] = None
+    website: Optional[str] = None
+    address_line_1: Optional[str] = None
+    address_line_2: Optional[str] = None
+    country_id: Optional[str] = None
+    country_name: Optional[str] = None
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    build_year: Optional[int] = None
+    renovation_year: Optional[int] = None
+    field_length: Optional[int] = None
+    field_width: Optional[int] = None
+    field_surface: Optional[str] = None
+    images: list[str] = []
+
+
+class ClubProfile(TransfermarktBaseModel, AuditMixin):
+    id: str
+    url: Optional[str] = None
+    name: str
+    official_name: Optional[str] = None
+    short_name: Optional[str] = None
+    abbreviation: Optional[str] = None
+    club_code: Optional[str] = None
+    image: Optional[str] = None
+    address_line_1: Optional[str] = None
+    address_line_2: Optional[str] = None
+    address_line_3: Optional[str] = None
+    colors: list[str] = []
+    stadium_name: Optional[str] = None
+    stadium_seats: Optional[int] = None
+    stadium: Optional[ClubStadium] = None
+    current_market_value: Optional[int] = None
+    confederation: Optional[str] = None
+    coach: Optional[ClubCoach] = None
+    squad: ClubSquad
+    league: ClubLeague
+    historical_crests: list[str] = []
+    historical_names: list[ClubHistoricalName] = []

transfermarkt_api/schemas/clubs/search.py

@@ -0,0 +1,19 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class ClubSearchResult(TransfermarktBaseModel):
+    id: str
+    url: Optional[str] = None
+    name: Optional[str] = None
+    country: Optional[str] = None
+    squad: Optional[int] = None
+    market_value: Optional[int] = None
+
+
+class ClubSearch(TransfermarktBaseModel, AuditMixin):
+    query: str
+    page_number: int
+    last_page_number: int
+    results: list[ClubSearchResult]

transfermarkt_api/schemas/coaches/__init__.py

@@ -0,0 +1,31 @@
+from datetime import date
+from typing import Optional
+
+from pydantic import HttpUrl
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+from transfermarkt_api.schemas.players.profile import PlayerPlaceOfBirth
+
+
+class Coach(TransfermarktBaseModel):
+    id: str
+    url: Optional[HttpUrl] = None
+    name: Optional[str] = None
+    name_in_home_country: Optional[str] = None
+    image_url: Optional[HttpUrl] = None
+    date_of_birth: Optional[date] = None
+    age: Optional[int] = None
+    place_of_birth: PlayerPlaceOfBirth
+    citizenship: list[str]
+    license: Optional[str] = None
+
+
+class CoachProfile(Coach, AuditMixin):
+    pass
+
+
+class CoachSearch(TransfermarktBaseModel, AuditMixin):
+    query: str
+    page_number: int
+    last_page_number: int
+    results: list[Coach]

transfermarkt_api/schemas/competitions/__init__.py

@@ -0,0 +1,4 @@
+from transfermarkt_api.schemas.competitions.clubs import CompetitionClubs as CompetitionClubs
+from transfermarkt_api.schemas.competitions.search import CompetitionSearch as CompetitionSearch
+from transfermarkt_api.schemas.competitions.seasons import CompetitionSeasons as CompetitionSeasons
+from transfermarkt_api.schemas.competitions.table import CompetitionTable as CompetitionTable

transfermarkt_api/schemas/competitions/clubs.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class CompetitionClub(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+
+
+class CompetitionClubs(TransfermarktBaseModel, AuditMixin):
+    id: str
+    name: str
+    season_id: str
+    clubs: list[CompetitionClub]

transfermarkt_api/schemas/competitions/search.py

@@ -0,0 +1,21 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class CompetitionSearchResult(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    country: Optional[str] = None
+    clubs: Optional[int] = None
+    players: Optional[int] = None
+    total_market_value: Optional[int] = None
+    mean_market_value: Optional[int] = None
+    continent: Optional[str] = None
+
+
+class CompetitionSearch(TransfermarktBaseModel, AuditMixin):
+    query: str
+    page_number: int
+    last_page_number: int
+    results: list[CompetitionSearchResult]

transfermarkt_api/schemas/competitions/seasons.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class Season(TransfermarktBaseModel):
+    id: str
+    name: Optional[str] = None
+    match_days: Optional[int] = None
+
+
+class CompetitionSeasons(TransfermarktBaseModel, AuditMixin):
+    id: str
+    name: Optional[str] = None
+    seasons: list[Season]

transfermarkt_api/schemas/competitions/table.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from transfermarkt_api.schemas.base import AuditMixin, TransfermarktBaseModel
+
+
+class TableRow(TransfermarktBaseModel):
+    position: Optional[int] = None
+    previous_position: Optional[int] = None
+    club_id: str
+    club_name: Optional[str] = None
+    matches: Optional[int] = None
+    wins: Optional[int] = None
+    draws: Optional[int] = None
+    losses: Optional[int] = None
+    goals_for: Optional[int] = None
+    goals_against: Optional[int] = None
+    goal_difference: Optional[int] = None
+    points: Optional[int] = None
+    zone: Optional[str] = None
+
+
+class Table(TransfermarktBaseModel):
+    name: Optional[str] = None
+    rows: list[TableRow]
+
+
+class CompetitionTable(TransfermarktBaseModel, AuditMixin):
+    id: str
+    name: Optional[str] = None
+    season_id: str
+    tables: list[Table]