apologies.source

Character input sources. A character could be a person or could be computer-driven.

Module Contents

class apologies.source.CharacterInputSource

Bases: abc.ABC

A generic source of input for a character, which could be a person or could be computer-driven. Concrete character input sources must have a valid zero-arguments constructor.

property fullname: str

Get the fully-qualified name of the character input source.

property name: str

Get the fully-qualified name of the character input source.

abstract choose_move(mode: apologies.game.GameMode, view: apologies.game.PlayerView, legal_moves: List[apologies.rules.Move], evaluator: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → apologies.rules.Move

Choose the next move for a character.

There is always at least one legal move: a forfeit. Nothing else is legal, so the character must choose to discard one card. In standard mode, there is effectively no choice (since there is only one card in play), but in adult mode the character can choose which to discard. If a move has an empty list of actions, then this is a forfeit.

The source must return a move from among the passed-in set of legal moves. If a source returns an illegal move, then a legal move will be chosen at random and executed. This way, a misbehaving source (or a source attempting to cheat) does not get an advantage. The game rules require a player to make a legal move if one is available, even if that move is disadvantageous.

Parameters:

• mode (GameMode) – Game mode

• view (PlayerView) – Player-specific view of the game

• legal_moves (List[Move]) – The set of legal moves

• evaluator (Callable[[PlayerView, Move], PlayerView]) – Function to evaluate a move, returning new state

Returns:

The character’s next move as described above

Return type:

Move

class apologies.source.NoOpInputSource

Bases: CharacterInputSource

A no-op input source, which raises an error if ever used.

The Apologies library is designed with a synchronous callback model in mind. If your application uses a different model, you may use lower-level methods to interact with the game engine directly, rather than getting user input from a callback. In that case, you will use this character input source. If you get an error, you’ll know that you’ve done something wrong.

abstract choose_move(_mode: apologies.game.GameMode, _view: apologies.game.PlayerView, _moves: List[apologies.rules.Move], _evaluator: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → apologies.rules.Move

Choose the next move for a character.

There is always at least one legal move: a forfeit. Nothing else is legal, so the character must choose to discard one card. In standard mode, there is effectively no choice (since there is only one card in play), but in adult mode the character can choose which to discard. If a move has an empty list of actions, then this is a forfeit.

The source must return a move from among the passed-in set of legal moves. If a source returns an illegal move, then a legal move will be chosen at random and executed. This way, a misbehaving source (or a source attempting to cheat) does not get an advantage. The game rules require a player to make a legal move if one is available, even if that move is disadvantageous.

Parameters:

• mode (GameMode) – Game mode

• view (PlayerView) – Player-specific view of the game

• legal_moves (List[Move]) – The set of legal moves

• evaluator (Callable[[PlayerView, Move], PlayerView]) – Function to evaluate a move, returning new state

Returns:

The character’s next move as described above

Return type:

Move

class apologies.source.RandomInputSource

Bases: CharacterInputSource

A source of input for a character which chooses randomly from among legal moves.

choose_move(mode: apologies.game.GameMode, view: apologies.game.PlayerView, legal_moves: List[apologies.rules.Move], unused: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → apologies.rules.Move

Randomly choose the next move for a character.

class apologies.source.RewardInputSource

Bases: CharacterInputSource

A source of input for a character which chooses its next move based on a reward calculation.

abstract calculate(view: apologies.game.PlayerView, move: apologies.rules.Move, evaluator: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → Tuple[apologies.rules.Move, float]

Calculate the reward associated with a move, returning a tuple of (Move, reward).

choose_move(mode: apologies.game.GameMode, view: apologies.game.PlayerView, legal_moves: List[apologies.rules.Move], evaluator: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → apologies.rules.Move

Choose the next move for a player by evaluating and scoring the available moves.

class apologies.source.RewardV1InputSource

Bases: RewardInputSource

A source of input for a character which chooses its next move based on the RewardCalculatorV1.

calculator

calculate(view: apologies.game.PlayerView, move: apologies.rules.Move, evaluator: Callable[[apologies.game.PlayerView, apologies.rules.Move], apologies.game.PlayerView]) → Tuple[apologies.rules.Move, float]

Calculate the reward associated with a move, returning a tuple of (Move, reward).

apologies.source.source(name: str) → CharacterInputSource

Create a character input source by name.

As a special case, if the name is not fully-qualified, we will assume “apologies.source”.

Parameters:

name (str) – Fully-qualified name of the source, like “apologies.source.RandomInputSource”

Returns:

An instance of the named source

Return type:

CharacterInputSource

Raises:

ValueError – If the named source does not exist or is not a CharacterInputSource