chipiron.games.match package

Submodules

chipiron.games.match.MatchTag module

class chipiron.games.match.MatchTag.MatchConfigTag(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Cubo = 'setting_cubo'

Duda = 'setting_duda'

Jime = 'setting_jime'

Tron = 'setting_tron'

get_match_settings_args() → MatchSettingsArgs[source]

get_yaml_file_path() → str | PathLike[str][source]

chipiron.games.match.match_args module

This module defines the MatchArgs class, which represents the input arguments needed by the one match script to run.

class chipiron.games.match.match_args.MatchArgs(player_one: PlayerConfigTag | PlayerArgs = PlayerConfigTag.RECUR_ZIPF_BASE_3, player_two: PlayerConfigTag | PlayerArgs = PlayerConfigTag.RECUR_ZIPF_BASE_3, match_setting: MatchConfigTag | MatchSettingsArgs = MatchConfigTag.Cubo)[source]

Bases: object

The input arguments needed by the one match script to run

file_name_player_one (path): The file name for player one. Defaults to ‘RecurZipfBase3.yaml’. file_name_player_two (path): The file name for player two. Defaults to ‘RecurZipfBase3.yaml’. file_name_match_setting (path): The file name for the match setting. Defaults to ‘setting_cubo.yaml’. player_one (dict[Any, Any]): The dictionary for player one. Defaults to an empty dictionary. player_two (dict[Any, Any]): The dictionary for player two. Defaults to an empty dictionary. match (dict[Any, Any]): The dictionary for the match. Defaults to an empty dictionary.

match_setting: MatchConfigTag | MatchSettingsArgs = 'setting_cubo'

player_one: PlayerConfigTag | PlayerArgs = 'RecurZipfBase3'

player_two: PlayerConfigTag | PlayerArgs = 'RecurZipfBase3'

chipiron.games.match.match_factories module

This module contains functions for creating match managers in the Chipiron game framework.

chipiron.games.match.match_factories.create_match_manager(args_match: MatchSettingsArgs, args_player_one: PlayerArgs, args_player_two: PlayerArgs, args_game: GameArgs, implementation_args: ImplementationArgs, universal_behavior: bool = False, seed: int | None = None, output_folder_path: str | PathLike[str] | None = None, gui: bool = False) → MatchManager[source]

Create a match manager for running matches between two players.

Parameters:

implementation_args – (ImplementationArgs) the implementation args
args_match (MatchSettingsArgs) – The match settings arguments.
args_player_one (players.PlayerArgs) – The arguments for player one.
args_player_two (players.PlayerArgs) – The arguments for player two.
args_game (game.GameArgs) – The game arguments.
seed (int | None, optional) – The seed for random number generation. Defaults to None.
output_folder_path (path | None, optional) – The output folder path. Defaults to None.
gui (bool, optional) – Flag indicating whether to enable GUI. Defaults to False.

Returns:

The created match manager.

Return type:

MatchManager

chipiron.games.match.match_factories.create_match_manager_from_args(match_args: MatchArgs, base_script_args: BaseScriptArgs, implementation_args: ImplementationArgs, gui: bool = False) → MatchManager[source]

Create a match manager from the given arguments.

Parameters:

implementation_args (ImplementationArgs) – The implementation args
match_args (MatchArgs) – The match arguments.
base_script_args (ScriptArgs) –
gui (bool, optional) – Flag indicating whether to enable GUI. Defaults to False.

Returns:

The created match manager.

Return type:

MatchManager

chipiron.games.match.match_manager module

Module in charge of playing one match

class chipiron.games.match.match_manager.MatchManager(player_one_id: str, player_two_id: str, game_manager_factory: GameManagerFactory, game_args_factory: GameArgsFactory, match_results_factory: MatchResultsFactory, output_folder_path: str | PathLike[str] | None = None)[source]

Bases: object

Object in charge of playing one match

Parameters:

player_one_id (str) – The ID of player one.
player_two_id (str) – The ID of player two.
game_manager_factory (GameManagerFactory) – The factory for creating game managers.
game_args_factory (GameArgsFactory) – The factory for creating game arguments.
match_results_factory (MatchResultsFactory) – The factory for creating match results.
output_folder_path (path | None, optional) – The path to the output folder. Defaults to None.

play_one_game(player_color_to_factory_args: dict[bool, chipiron.players.player_args.PlayerFactoryArgs], args_game: GameArgs, game_number: int, game_seed: int) → GameReport[source]

Plays one game and returns the game report.

Parameters:

player_color_to_factory_args (dict[chess.Color, PlayerFactoryArgs]) – A dictionary mapping player colors to their factory arguments.
args_game (GameArgs) – The arguments for the game.
game_number (int) – The number of the game.
game_seed (seed) – The seed for the game.

Returns:

The report of the game.

Return type:

GameReport

play_one_match() → MatchReport[source]

Plays one match and returns the match report.

This method plays a single match, which consists of multiple games. It generates game arguments, plays each game, updates the match results, and saves the match report to a file.

Returns:: The report of the match, including the move history and match results.
Return type:: MatchReport

print_info() → None[source]

Prints the information about the players in the match.

This method prints the IDs of player one and player two.

Parameters:: None –
Returns:: None

print_stats_to_file(match_results: IMatchResults) → None[source]

Prints the match statistics to a file.

Parameters:: match_results (IMatchResults) – The match results object containing the statistics.

save_match_report_to_file(match_report: MatchReport) → None[source]

Save the match report to a file.

Parameters:: match_report (MatchReport) – The match report to be saved.

subscribe(subscriber: Queue[IsDataclass]) → None[source]

Subscribe a subscriber to receive updates from the match manager.

Parameters:: subscriber (queue.Queue[IsDataclass]) – The subscriber to be added to the list of subscribers.

chipiron.games.match.match_results module

This module contains the classes for match results.

class chipiron.games.match.match_results.IMatchResults(*args, **kwargs)[source]

Bases: Protocol

Interface for match results.

add_result_one_game(white_player_name_id: str, game_result: FinalGameResult) → None[source]

Adds the result of one game to the match results.

Parameters:

white_player_name_id (str) – The ID of the white player.
game_result (FinalGameResult) – The result of the game.

finish() → None[source]: Finishes the match and marks it as finished.

get_simple_result() → SimpleResults[source]

Returns the simple results of the match.

Returns:: The simple results of the match.
Return type:: SimpleResults

class chipiron.games.match.match_results.MatchReport(match_results: MatchResults, match_move_history: dict[int, list[str]])[source]

Bases: object

Represents a match report containing the match results and move history.

match_move_history: dict[int, list[str]]

match_results: MatchResults

class chipiron.games.match.match_results.MatchResults(player_one_name_id: str, player_two_name_id: str, number_of_games: int = 0, player_one_is_white_white_wins: int = 0, player_one_is_white_black_wins: int = 0, player_one_is_white_draws: int = 0, player_two_is_white_white_wins: int = 0, player_two_is_white_black_wins: int = 0, player_two_is_white_draws: int = 0, match_finished: bool = False)[source]

Bases: object

Represents the results of a match between two players.

add_result_one_game(white_player_name_id: str, game_result: FinalGameResult) → None[source]

Adds the result of one game to the match results.

Parameters:

white_player_name_id (str) – The ID of the white player.
game_result (FinalGameResult) – The result of the game.

finish() → None[source]: Finishes the match and marks it as finished.

get_draws() → int[source]

Returns the number of draws.

Returns:: The number of draws.
Return type:: int

get_player_one_wins() → int[source]

Returns the number of wins for player one.

Returns:: The number of wins for player one.
Return type:: int

get_player_two_wins() → int[source]

Returns the number of wins for player two.

Returns:: The number of wins for player two.
Return type:: int

get_simple_result() → SimpleResults[source]

Returns the simple results of the match.

Returns:: The simple results of the match.
Return type:: SimpleResults

match_finished: bool = False

number_of_games: int = 0

player_one_is_white_black_wins: int = 0

player_one_is_white_draws: int = 0

player_one_is_white_white_wins: int = 0

player_one_name_id: str

player_two_is_white_black_wins: int = 0

player_two_is_white_draws: int = 0

player_two_is_white_white_wins: int = 0

player_two_name_id: str

class chipiron.games.match.match_results.SimpleResults(player_one_wins: int, player_two_wins: int, draws: int)[source]

Bases: object

Represents the simple results of a match.

draws: int

player_one_wins: int

player_two_wins: int

chipiron.games.match.match_results_factory module

Module to create a MatchResults object.

This module provides a MatchResultsFactory class that is responsible for creating MatchResults objects. It also provides a way to subscribe to the MatchResults object and receive updates.

Classes: - MatchResultsFactory: A factory class to create MatchResults objects and manage subscribers.

class chipiron.games.match.match_results_factory.MatchResultsFactory(player_one_name: str, player_two_name: str)[source]

Bases: object

A factory class for creating MatchResults objects.

This class provides methods to create MatchResults objects and subscribe subscribers to receive match results.

player_one_name

The name of player one.

Type:: str

player_two_name

The name of player two.

Type:: str

subscribers

A list of subscribers to receive match results.

Type:: list[queue.Queue[IsDataclass]]

__init__(self, player_one_name: str, player_two_name: str) -> None: Initialize the MatchResultsFactory.

create(self) → IMatchResults[source]: Create a MatchResults object.

subscribe(self, subscriber: queue.Queue[IsDataclass]) -> None: Subscribe a subscriber to receive match results.

create() → IMatchResults[source]

Create a MatchResults object.

Returns:: The created MatchResults object.
Return type:: IMatchResults

player_one_name: str

player_two_name: str

subscribe(subscriber: Queue[IsDataclass]) → None[source]

Subscribe a subscriber to receive match results.

Parameters:: subscriber (queue.Queue[IsDataclass]) – The subscriber to be added to the list of subscribers.

subscribers: list[queue.Queue[chipiron.utils.dataclass.IsDataclass]] = []

chipiron.games.match.match_settings_args module

Module to define the MatchSettingsArgs dataclass.

class chipiron.games.match.match_settings_args.MatchSettingsArgs(number_of_games_player_one_white: int, number_of_games_player_one_black: int, game_setting_file: str | PathLike[str])[source]

Bases: object

Dataclass to store match settings arguments.

Parameters:

number_of_games_player_one_white (int) – The number of games player one plays as white.
number_of_games_player_one_black (int) – The number of games player one plays as black.
game_setting_file (path) – The file path to the game setting file.

game_setting_file: str | PathLike[str]

number_of_games_player_one_black: int

number_of_games_player_one_white: int

chipiron.games.match.observable_match_result module

This module contains the ObservableMatchResults class, which is a wrapper around the MatchResults class.

class chipiron.games.match.observable_match_result.ObservableMatchResults(match_results: ~chipiron.games.match.match_results.MatchResults, mailboxes: list[queue.Queue[chipiron.utils.dataclass.IsDataclass]] = <factory>)[source]

Bases: object

The ObservableMatchResults class provides a way to observe and subscribe to changes in the match results. It maintains a list of mailboxes (queue.Queue) to which it sends notifications whenever there are new match results.

match_results

The underlying MatchResults object that stores the match results.

Type:: MatchResults

mailboxes

A list of mailboxes to which notifications are sent.

Type:: list[queue.Queue[IsDataclass]]

subscribe(mailbox: queue.Queue[IsDataclass]) -> None: Subscribes a mailbox to receive notifications.

copy_match_result() → MatchResults[source]: Creates a deep copy of the match results.

add_result_one_game(white_player_name_id: str, game_result: FinalGameResult) -> None: Adds the result of a single game to the match results.

notify_new_results() → None[source]: Notifies all subscribed mailboxes about the new match results.

get_simple_result() → SimpleResults[source]: Retrieves a simplified version of the match results.

finish() → None[source]: Marks the match as finished and notifies all subscribed mailboxes.

__str__() → str[source]: Returns a string representation of the match results.

add_result_one_game(white_player_name_id: str, game_result: FinalGameResult) → None[source]

Adds the result of a single game to the match results.

Parameters:

white_player_name_id (str) – The ID of the white player.
game_result (FinalGameResult) – The result of the game.

Returns:

None

copy_match_result() → MatchResults[source]

Creates a deep copy of the match results.

Returns:: A deep copy of the match results.
Return type:: MatchResults

finish() → None[source]

Marks the match as finished and notifies all subscribed mailboxes.

Returns:: None

get_simple_result() → SimpleResults[source]

Retrieves a simplified version of the match results.

Returns:: A simplified version of the match results.
Return type:: SimpleResults

mailboxes: list[queue.Queue[chipiron.utils.dataclass.IsDataclass]]

match_results: MatchResults

notify_new_results() → None[source]

Notifies all subscribed mailboxes about the new match results.

Returns:: None

subscribe(mailbox: Queue[IsDataclass]) → None[source]

Subscribes a mailbox to receive notifications.

Parameters:: mailbox (queue.Queue[IsDataclass]) – The mailbox to subscribe.
Returns:: None

chipiron.games.match.utils module

Module to fetch, modify and convert the match settings and game settings.

chipiron.games.match.utils.fetch_match_games_args_convert_and_save(match_args: MatchArgs, profiling: bool = False, testing: bool = False, experiment_output_folder: str | PathLike[str] | None = None) → tuple[chipiron.games.match.match_settings_args.MatchSettingsArgs, chipiron.games.game.game_args.GameArgs][source]

Fetches, modifies, and converts the match settings and game settings.

Parameters:

file_name_match_setting (path) – The path to the match settings file.
profiling (bool, optional) – Flag indicating whether profiling is enabled. Defaults to False.
testing (bool, optional) – Flag indicating whether testing is enabled. Defaults to False.
experiment_output_folder (path | None, optional) – The path to the experiment output folder. Defaults to None.
modification (dict[Any, Any] | None, optional) – Dictionary of modifications to apply. Defaults to None.

Returns:

A tuple containing the match settings and game settings.

Return type:

tuple[MatchSettingsArgs, game.GameArgs]

Module contents

Module to manage matches.

class chipiron.games.match.MatchSettingsArgs(number_of_games_player_one_white: int, number_of_games_player_one_black: int, game_setting_file: str | PathLike[str])[source]

Bases: object

Dataclass to store match settings arguments.

Parameters:

number_of_games_player_one_white (int) – The number of games player one plays as white.
number_of_games_player_one_black (int) – The number of games player one plays as black.
game_setting_file (path) – The file path to the game setting file.

game_setting_file: str | PathLike[str]

number_of_games_player_one_black: int

number_of_games_player_one_white: int

chipiron.games.match.create_match_manager(args_match: MatchSettingsArgs, args_player_one: PlayerArgs, args_player_two: PlayerArgs, args_game: GameArgs, implementation_args: ImplementationArgs, universal_behavior: bool = False, seed: int | None = None, output_folder_path: str | PathLike[str] | None = None, gui: bool = False) → MatchManager[source]

Create a match manager for running matches between two players.

Parameters:

implementation_args – (ImplementationArgs) the implementation args
args_match (MatchSettingsArgs) – The match settings arguments.
args_player_one (players.PlayerArgs) – The arguments for player one.
args_player_two (players.PlayerArgs) – The arguments for player two.
args_game (game.GameArgs) – The game arguments.
seed (int | None, optional) – The seed for random number generation. Defaults to None.
output_folder_path (path | None, optional) – The output folder path. Defaults to None.
gui (bool, optional) – Flag indicating whether to enable GUI. Defaults to False.

Returns:

The created match manager.

Return type:

MatchManager