Match

The Match class is the top-level entity representing a padel match. It encapsulates both the metadata (teams, duration, location) and the state management logic by holding a MatchScoreHistory instance.

Properties

Core Properties

Name
teams
Type
dict[TeamId, Team]
Description
A dictionary mapping TeamId to each Team playing the match.
Name
court
Type
Court | None
Description
The Court geometry instance representing the physical padel court.
Name
config
Type
MatchConfiguration
Description
The complete MatchConfiguration instance containing the rules and formats for the match.
Name
history
Type
MatchScoreHistory
Description
The underlying MatchScoreHistory engine driving the score logic.

Match Status & Logic

Name
winner
Type
Team | None
Description
Returns the Team that won the match based on the score and best_of_sets, or None if incomplete.
Name
is_completed
Type
bool
Description
Returns True if a winner has been decided.

Configuration Shortcuts (Proxies)

The following properties are convenience proxies for the properties encapsulated within the config (MatchConfiguration) instance. Reading or writing these properties directly forwards the action to the configuration instance.

Name
best_of_sets
Type
int
Description
Shortcut for config.best_of_sets. The maximum number of sets to determine a winner (typically 3 or 5).
Name
advantage_method
Type
str
Description
Shortcut for config.advantage_method. The game-level scoring rules. Can be "advantage" or "gold_point".
Name
set_format
Type
str
Description
Shortcut for config.set_format. The format of sets played. Can be "standard" or "mini".
Name
deciding_set_format
Type
str
Description
Shortcut for config.deciding_set_format. The format of the final/deciding set. Can be "regular", "tiebreak", or "super_tiebreak".
Name
starting_server_team
Type
TeamId
Description
Shortcut for config.starting_server_team. The team configured to start serving first in the match.
Name
set_starting_servers
Type
dict[int, dict[TeamId, Player]]
Description
Shortcut for config.set_starting_servers. A dictionary mapping 1-based set indexes (e.g. 1, 2, 3) to each team's chosen initial server for that set.

Initialization

You can create a Match by providing optional parameters. If no teams are provided, default generic teams will be instantiated.

Note: During initialization, PadelKit performs early validation checks. A ValueError will be raised if duplicate player names are found across teams, or if any configured starting servers do not belong to their respective teams.

Core Arguments

Name
teams
Type
dict[TeamId, Team]
Description
A dictionary mapping a TeamId to a Team object.
Name
config
Type
MatchConfiguration | None
Description
An optional custom MatchConfiguration object to initialize the match rules. If provided, other individual scoring parameter arguments (like best_of_sets, advantage_method) are ignored.
Name
court
Type
Court | None
Description
The Court geometry instance representing the court bounds and landmark points.
Name
date
Type
datetime | None
Description
The date and time of the match.
Name
duration_minutes
Type
int | None
Description
Total duration of the match in minutes.

Configuration Shortcut Arguments

These arguments are automatically packaged into a MatchConfiguration if a custom config object is not provided.

Name
best_of_sets
Type
int
Description
The number of sets to determine a winner (e.g., 3 means the first to win 2 sets wins).
Name
advantage_method
Type
str
Description
The game-level scoring system. Can be "advantage" (normal deuce/advantage) or "gold_point" (golden point at 40-40).
Name
set_format
Type
str
Description
The length of sets. Can be "standard" (sets to 6 games) or "mini" (sets to 4 games).
Name
deciding_set_format
Type
str
Description
How the final set is resolved if sets are tied. Can be "regular" (standard set), "tiebreak" (7-point tie-break), or "super_tiebreak" (10-point super tie-break).
Name
starting_server_team
Type
TeamId
Description
The team that starts serving first in the match.
Name
set_starting_servers
Type
dict[int, dict[TeamId, Player]] | None
Description
A dictionary mapping a 1-based set index (e.g., 1, 2, 3) to a nested dictionary mapping TeamId to the Player chosen to start serving for that team in that set.

Instantiation

class

Match

from padelkit import Match, Court
from datetime import datetime

# Initialize a standard court
court = Court.fip_standard()

# Start a premium mini-set match with gold points
# and a match-deciding super tie-break
match = Match(
    best_of_sets=3,
    advantage_method="gold_point",
    set_format="mini",
    deciding_set_format="super_tiebreak",
    date=datetime.now(),
    court=court
)

Output structure

Match(
  teams={
    TeamId.A: Team(id=TeamId.A, player1=Player(name='Player 1'), player2=Player(name='Player 2')),
    TeamId.B: Team(id=TeamId.B, player1=Player(name='Player 3'), player2=Player(name='Player 4'))
  },
  config=MatchConfiguration(
    best_of_sets=3,
    advantage_method='gold_point',
    set_format='mini',
    deciding_set_format='super_tiebreak',
    starting_server_team=<TeamId.A: 'A'>,
    set_starting_servers={}
  ),
  history=<MatchScoreHistory object at 0x...>,
  duration_minutes=None,
  date=datetime.datetime(...),
  court=Court(dimensions=CourtDimensions(length=20.0, width=10.0, ...))
)

methodmatch.set_set_starting_server()

Setting Set Starting Servers

Configures the starting server player for a specific team in a specific set.

Note: The configured player must belong to the specified team. If the player is not a member of that team, a ValueError will be raised.

Required arguments

Name
set_index
Type
int
Description
The 1-based index of the set (e.g., 1 for the first set, 2 for the second set).
Name
team_id
Type
TeamId
Description
The team identifying (TeamId.A or TeamId.B).
Name
player
Type
Player
Description
The Player chosen to serve first for the team in that set.

Usage

method

set_set_starting_server

from padelkit import Player, TeamId

player = Player("Juan Lebrón")
# Set server for Set 1
match.set_set_starting_server(set_index=1, team_id=TeamId.A, player=player)