pygambit.gambit.Game.set_players

Game.set_players(players: list[str], drop: bool = False, add: bool = True) → None

Set the players of the game to be players, matching by label.

An entry of players matching the label of a current player refers to that player, which keeps its moves or strategies and its payoffs at every outcome; an entry matching no current player creates a new player there, with no decisions in an extensive game, or a single strategy labeled "1" in a strategic game. A current player whose label is not in players is deleted. Listing the current labels in a new order reorders the players.

A player can only be deleted if it has no decisions in the game (in an extensive game) or exactly one strategy (in a strategic game); otherwise the operation raises.

The defaults permit creation and forbid deletion: adding a player – inserting its label into the current list – is the common, non-destructive edit, while deletion discards the player’s payoffs at every outcome, so it must be confirmed.

Added in version 17.0.0: Subsumes and replaces Game.add_player.

Parameters:

• players (list of str) – The labels of the players the game is to have, in order. Must be nonempty and without duplicates; each label must be a valid, nonempty label, and in an extensive game must not be the reserved chance player label.

• drop (bool, default False) – Deleting players is destructive, so it must be explicitly confirmed: if any current player is missing from players and drop is False, the operation raises without modifying the game.

• add (bool, default True) – If False, entries of players matching no current player raise.

Raises:

• TypeError – If players is a string, or not an iterable of strings.

• UndefinedOperationError – If players is empty; or if a player to be deleted has decisions in the game, or more than one strategy.

• ValueError – If a label in players is repeated, empty, is not a valid label, or (in an extensive game) is the reserved label of the chance player.