refactor: implement pydantic schemas

app/api/endpoints/clubs.py

@@ -2,28 +2,29 @@
 
 from fastapi import APIRouter
 
+from app.schemas import clubs as schemas
 from app.services.clubs.players import TransfermarktClubPlayers
 from app.services.clubs.profile import TransfermarktClubProfile
 from app.services.clubs.search import TransfermarktClubSearch
 
 router = APIRouter()
 
 
-@router.get("/search/{club_name}")
+@router.get("/search/{club_name}", response_model=schemas.ClubSearch, response_model_exclude_none=True)
 def search_clubs(club_name: str, page_number: Optional[int] = 1) -> dict:
     tfmkt = TransfermarktClubSearch(query=club_name, page_number=page_number)
     found_clubs = tfmkt.search_clubs()
     return found_clubs
 
 
-@router.get("/{club_id}/profile")
+@router.get("/{club_id}/profile", response_model=schemas.ClubProfile, response_model_exclude_defaults=True)
 def get_club_profile(club_id: str) -> dict:
     tfmkt = TransfermarktClubProfile(club_id=club_id)
     club_profile = tfmkt.get_club_profile()
     return club_profile
 
 
-@router.get("/{club_id}/players")
+@router.get("/{club_id}/players", response_model=schemas.ClubPlayers, response_model_exclude_defaults=True)
 def get_club_players(club_id: str, season_id: Optional[str] = None) -> dict:
     tfmkt = TransfermarktClubPlayers(club_id=club_id, season_id=season_id)
     club_players = tfmkt.get_club_players()

app/api/endpoints/competitions.py

@@ -2,21 +2,22 @@
 
 from fastapi import APIRouter
 
+from app.schemas import competitions as schemas
 from app.services.competitions.clubs import TransfermarktCompetitionClubs
 from app.services.competitions.search import TransfermarktCompetitionSearch
 
 router = APIRouter()
 
 
-@router.get("/search/{competition_name}")
-def search_competitions(competition_name: str, page_number: Optional[int] = 1) -> dict:
+@router.get("/search/{competition_name}", response_model=schemas.CompetitionSearch)
+def search_competitions(competition_name: str, page_number: Optional[int] = 1):
     tfmkt = TransfermarktCompetitionSearch(query=competition_name, page_number=page_number)
     competitions = tfmkt.search_competitions()
     return competitions
 
 
-@router.get("/{competition_id}/clubs")
-def get_competition_clubs(competition_id: str, season_id: Optional[str] = None) -> dict:
+@router.get("/{competition_id}/clubs", response_model=schemas.CompetitionClubs)
+def get_competition_clubs(competition_id: str, season_id: Optional[str] = None):
     tfmkt = TransfermarktCompetitionClubs(competition_id=competition_id, season_id=season_id)
     competition_clubs = tfmkt.get_competition_clubs()
     return competition_clubs

app/api/endpoints/players.py

@@ -2,6 +2,7 @@
 
 from fastapi import APIRouter
 
+from app.schemas import players as schemas
 from app.services.players.achievements import TransfermarktPlayerAchievements
 from app.services.players.injuries import TransfermarktPlayerInjuries
 from app.services.players.jersey_numbers import TransfermarktPlayerJerseyNumbers
@@ -14,56 +15,56 @@
 router = APIRouter()
 
 
-@router.get("/search/{player_name}")
+@router.get("/search/{player_name}", response_model=schemas.PlayerSearch, response_model_exclude_none=True)
 def search_players(player_name: str, page_number: Optional[int] = 1):
     tfmkt = TransfermarktPlayerSearch(query=player_name, page_number=page_number)
     found_players = tfmkt.search_players()
     return found_players
 
 
-@router.get("/{player_id}/profile")
+@router.get("/{player_id}/profile", response_model=schemas.PlayerProfile, response_model_exclude_none=True)
 def get_player_profile(player_id: str):
     tfmkt = TransfermarktPlayerProfile(player_id=player_id)
     player_info = tfmkt.get_player_profile()
     return player_info
 
 
-@router.get("/{player_id}/market_value")
+@router.get("/{player_id}/market_value", response_model=schemas.PlayerMarketValue, response_model_exclude_none=True)
 def get_player_market_value(player_id: str):
     tfmkt = TransfermarktPlayerMarketValue(player_id=player_id)
     player_market_value = tfmkt.get_player_market_value()
     return player_market_value
 
 
-@router.get("/{player_id}/transfers")
+@router.get("/{player_id}/transfers", response_model=schemas.PlayerTransfers, response_model_exclude_none=True)
 def get_player_transfers(player_id: str):
     tfmkt = TransfermarktPlayerTransfers(player_id=player_id)
     player_market_value = tfmkt.get_player_transfers()
     return player_market_value
 
 
-@router.get("/{player_id}/jersey_numbers")
+@router.get("/{player_id}/jersey_numbers", response_model=schemas.PlayerJerseyNumbers, response_model_exclude_none=True)
 def get_player_jersey_numbers(player_id: str):
     tfmkt = TransfermarktPlayerJerseyNumbers(player_id=player_id)
     player_jerseynumbers = tfmkt.get_player_jersey_numbers()
     return player_jerseynumbers
 
 
-@router.get("/{player_id}/stats")
+@router.get("/{player_id}/stats", response_model=schemas.PlayerStats, response_model_exclude_none=True)
 def get_player_stats(player_id: str):
     tfmkt = TransfermarktPlayerStats(player_id=player_id)
     player_stats = tfmkt.get_player_stats()
     return player_stats
 
 
-@router.get("/{player_id}/injuries")
+@router.get("/{player_id}/injuries", response_model=schemas.PlayerInjuries, response_model_exclude_none=True)
 def get_player_injuries(player_id: str, page_number: Optional[int] = 1):
     tfmkt = TransfermarktPlayerInjuries(player_id=player_id, page_number=page_number)
     players_injuries = tfmkt.get_player_injuries()
     return players_injuries
 
 
-@router.get("/{player_id}/achievements")
+@router.get("/{player_id}/achievements", response_model=schemas.PlayerAchievements, response_model_exclude_none=True)
 def get_player_achievements(player_id: str):
     tfmkt = TransfermarktPlayerAchievements(player_id=player_id)
     player_achievements = tfmkt.get_player_achievements()

app/schemas/base.py

@@ -0,0 +1,82 @@
+from datetime import datetime
+
+from dateutil import parser
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic.alias_generators import to_camel
+
+
+class IDMixin(BaseModel):
+    id: str
+
+
+class AuditMixin(BaseModel):
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+
+class TransfermarktBaseModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    @field_validator(
+        "date_of_birth",
+        "joined_on",
+        "contract",
+        "founded_on",
+        "members_date",
+        "from_date",
+        "until_date",
+        "date",
+        "contract_expires",
+        "joined",
+        "retired_since",
+        mode="before",
+        check_fields=False,
+    )
+    def parse_str_to_date(cls, v: str):
+        try:
+            return parser.parse(v).date() if v else None
+        except parser.ParserError:
+            return None
+
+    @field_validator(
+        "current_market_value",
+        "current_transfer_record",
+        "market_value",
+        "mean_market_value",
+        "members",
+        "total_market_value",
+        "age",
+        "goals",
+        "assists",
+        "yellow_cards",
+        "red_cards",
+        "minutes_played",
+        mode="before",
+        check_fields=False,
+    )
+    def parse_str_to_int(cls, v: str):
+        parsed_value = (
+            (
+                v.replace("bn", "000000000")
+                .replace("m", "000000")
+                .replace("k", "000")
+                .replace("€", "")
+                .replace(".", "")
+                .replace("+", "")
+                .replace(".", "")
+                .replace("'", "")
+            )
+            if v and any(char.isdigit() for char in v)
+            else None
+        )
+        return int(parsed_value) if parsed_value else None
+
+    @field_validator("height", mode="before", check_fields=False)
+    def parse_height(cls, v: str):
+        if not any(char.isdigit() for char in v):
+            return None
+        return int(v.replace(",", "").replace("m", ""))
+
+    @field_validator("days", mode="before", check_fields=False)
+    def parse_days(cls, v: str):
+        days = "".join(filter(str.isdigit, v))
+        return int(days) if days else None

app/schemas/clubs/__init__.py

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

app/schemas/clubs/players.py

@@ -0,0 +1,25 @@
+from datetime import date
+from typing import Optional
+
+from app.schemas.base import TransfermarktBaseModel
+
+
+class ClubPlayer(TransfermarktBaseModel):
+    name: str
+    position: str
+    date_of_birth: date
+    age: int
+    nationality: list[str]
+    current_club: Optional[str] = None
+    height: Optional[int] = None
+    foot: Optional[str] = None
+    joined_on: Optional[date] = None
+    joined: Optional[str] = None
+    signed_from: Optional[str] = None
+    contract: Optional[date] = None
+    market_value: Optional[int] = None
+    status: Optional[str] = ""
+
+
+class ClubPlayers(TransfermarktBaseModel):
+    players: list[ClubPlayer]

app/schemas/clubs/profile.py

@@ -0,0 +1,47 @@
+from datetime import date
+from typing import Optional
+
+from app.schemas.base import TransfermarktBaseModel
+
+
+class ClubSquad(TransfermarktBaseModel):
+    size: int
+    average_age: float
+    foreigners: int
+    national_team_players: int
+
+
+class ClubLeague(TransfermarktBaseModel):
+    id: str
+    name: str
+    country_id: str
+    country_name: str
+    tier: str
+
+
+class ClubProfile(TransfermarktBaseModel):
+    url: str
+    name: str
+    official_name: str
+    image: str
+    legal_form: Optional[str] = None
+    address_line_1: str
+    address_line_2: str
+    address_line_3: str
+    tel: str
+    fax: str
+    website: str
+    founded_on: date
+    members: Optional[int] = None
+    members_date: Optional[date] = None
+    other_sports: Optional[list[str]] = None
+    colors: Optional[list[str]] = []
+    stadium_name: str
+    stadium_seats: int
+    current_transfer_record: int
+    current_market_value: int
+    confederation: Optional[str] = None
+    fifa_world_ranking: Optional[str] = None
+    squad: ClubSquad
+    league: ClubLeague
+    historical_crests: Optional[list[str]] = []

app/schemas/clubs/search.py

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

app/schemas/competitions/__init__.py

@@ -0,0 +1,2 @@
+from app.schemas.competitions.clubs import CompetitionClubs as CompetitionClubs
+from app.schemas.competitions.search import CompetitionSearch as CompetitionSearch

app/schemas/competitions/clubs.py

@@ -0,0 +1,12 @@
+from app.schemas.base import AuditMixin, IDMixin, TransfermarktBaseModel
+
+
+class CompetitionClub(TransfermarktBaseModel, IDMixin):
+    name: str
+
+
+class CompetitionClubs(TransfermarktBaseModel, IDMixin, AuditMixin):
+    id: str
+    name: str
+    season_id: str
+    clubs: list[CompetitionClub]

app/schemas/competitions/search.py

@@ -0,0 +1,20 @@
+from typing import Optional
+
+from app.schemas.base import AuditMixin, IDMixin, TransfermarktBaseModel
+
+
+class CompetitionSearchResult(TransfermarktBaseModel, IDMixin):
+    name: str
+    country: str
+    clubs: int
+    players: int
+    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]

app/schemas/players/__init__.py

@@ -0,0 +1,8 @@
+from app.schemas.players.achievements import PlayerAchievements as PlayerAchievements
+from app.schemas.players.injuries import PlayerInjuries as PlayerInjuries
+from app.schemas.players.jersey_numbers import PlayerJerseyNumbers as PlayerJerseyNumbers
+from app.schemas.players.market_value import PlayerMarketValue as PlayerMarketValue
+from app.schemas.players.profile import PlayerProfile as PlayerProfile
+from app.schemas.players.search import PlayerSearch as PlayerSearch
+from app.schemas.players.stats import PlayerStats as PlayerStats
+from app.schemas.players.transfers import PlayerTransfers as PlayerTransfers

app/schemas/players/achievements.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+from app.schemas.base import AuditMixin, IDMixin, TransfermarktBaseModel
+
+
+class AchievementDetail(TransfermarktBaseModel):
+    id: Optional[str] = None
+    name: str
+
+
+class AchievementDetails(TransfermarktBaseModel):
+    competition: Optional[AchievementDetail] = None
+    season: AchievementDetail
+    club: Optional[AchievementDetail] = None
+
+
+class PlayerAchievement(TransfermarktBaseModel):
+    title: str
+    count: int
+    details: list[AchievementDetails]
+
+
+class PlayerAchievements(TransfermarktBaseModel, IDMixin, AuditMixin):
+    achievements: list[PlayerAchievement]