apologies.game

Classes that track game state.

Note that these classes track game state, but do not implement game rules. The only validations are to prevent changes that literally cannot be represented in game state, such as selecting an invalid square. All other rules (such as the restriction that only one pawn can occupy a space, or the act of sliding down a slider, etc.) are implemented in the rules module, using the methods available on these classes.

In many cases, private attributes are accessible in the constructor to support serialization and deserialization. In general, callers should not pass in optional constructor arguments and should not modify public attributes if an alternate method is available for use.

apologies.game.MIN_PLAYERS

Minimum number of players in a game

Type:

int

apologies.game.MAX_PLAYERS

Maximum number of players in a game

Type:

int

apologies.game.PAWNS

Number of pawns per player

Type:

int

apologies.game.SAFE_SQUARES

Number of safe squares for each color

Type:

int

apologies.game.BOARD_SQUARES

Number of squares around the outside of the board

Type:

int

apologies.game.ADULT_HAND

Number of cards in a player’s hand for an adult mode game

Type:

int

apologies.game.DECK_COUNTS

Dictionary from card name to number of cards in a standard deck

Type:

Dict[Card, int]

apologies.game.DECK_SIZE

The total expected size of a complete deck

Type:

int

apologies.game.DRAW_AGAIN

Whether each card results in a draw again action

Type:

Dict[Card, bool]

apologies.game.CIRCLE

The position of the start circle for each color

Type:

Dict[PlayerColor, Position]

apologies.game.TURN

The position of the turn square for each color, where forward movement turns into safe zone

Type:

Dict[PlayerColor, Position()

apologies.game.SLIDE

The slide start/end squares for each color

Type:

Dict[PlayerColor, Tuple(int, int)

Module Contents

apologies.game.MIN_PLAYERS = 2

apologies.game.MAX_PLAYERS = 4

apologies.game.PAWNS = 4

apologies.game.SAFE_SQUARES = 5

apologies.game.BOARD_SQUARES = 60

class apologies.game.GameMode

Bases: enum.Enum

Available game play modes.

STANDARD = 'Standard'

ADULT = 'Adult'

class apologies.game.PlayerColor

Bases: enum.Enum

Enumeration of all player colors, listed in order of use.

RED = 'Red'

YELLOW = 'Yellow'

GREEN = 'Green'

BLUE = 'Blue'

class apologies.game.CardType

Bases: enum.Enum

All legal types of cards.

The “A” card (CARD_APOLOGIES) is like the “Sorry” card in the original game.

CARD_1 = '1'

CARD_2 = '2'

CARD_3 = '3'

CARD_4 = '4'

CARD_5 = '5'

CARD_7 = '7'

CARD_8 = '8'

CARD_10 = '10'

CARD_11 = '11'

CARD_12 = '12'

CARD_APOLOGIES = 'A'

apologies.game.ADULT_HAND = 5

apologies.game.DECK_COUNTS

apologies.game.DECK_SIZE

apologies.game.DRAW_AGAIN

class apologies.game.Card

A card in a deck or in a player’s hand.

id

Unique identifier for this card

Type:

str

cardtype

The type of the card

Type:

CardType

id: str

cardtype: CardType

class apologies.game.Deck

The deck of cards associated with a game.

Callers should not pass in constructor arguments. These are accessible to support serialization and deserialization.

draw() → Card

Draw a random card from the draw pile.

discard(card: Card) → None

Discard back to the discard pile.

class apologies.game.Position

The position of a pawn on the board.

Callers should not pass in or directly modify the start, home, safe, or square attributes. These are accessible to support serialization and deserialization. Instead, use the provided methods to safely modify the object in-place.

start

Whether this pawn resides in its start area

Type:

boolean

home

Whether this pawn resides in its home area

Type:

boolean

safe

Zero-based index of the square in the safe area where this pawn resides

Type:

int

square

Zero-based index of the square on the board where this pawn resides

Type:

int

start: bool = True

home: bool = False

safe: int | None

square: int | None

__str__() → str

Return str(self).

copy() → Position

Return a fully-independent copy of the position.

move_to_position(position: Position) → Position

Move the pawn to a specific position on the board.

Returns:

A reference to the position, for chaining

Return type:

Position

Raises:

ValueError – If the position is invalid

move_to_start() → Position

Move the pawn back to its start area.

Returns:

A reference to the position, for chaining

Return type:

Position

Raises:

ValueError – If the position is invalid

move_to_home() → Position

Move the pawn to its home area.

Returns:

A reference to the position, for chaining

Return type:

Position

Raises:

ValueError – If the position is invalid

move_to_safe(square: int) → Position

Move the pawn to a square in its safe area.

Parameters:

square (int) – Zero-based index of the square in the safe area

Returns:

A reference to the position, for chaining

Return type:

Position

Raises:

ValueError – If the square is not valid

move_to_square(square: int) → Position

Move the pawn to a square on the board.

Parameters:

square (int) – Zero-based index of the square on the board where this pawn resides

Returns:

A reference to the position, for chaining

Return type:

Position

Raises:

ValueError – If the square is not valid

class apologies.game.Pawn

A pawn on the board, belonging to a player.

Callers should not pass in the position attribute. This is accessible to support serialization and deserialization. Instead, use the provided methods to safely modify the position in-place.

color

The color of this pawn

Type:

str

index

Zero-based index of this pawn for a given user

Type:

int

name

The full name of this pawn as “colorindex”

Type:

str

position

The position of this pawn on the board

Type:

Position

color: PlayerColor

index: int

name: str

position: Position

__str__() → str

Return str(self).

class apologies.game.Player

A player, which has a color and a set of pawns.

Callers should not pass in the hand and pawns constructor arguments. These are accessible to support serialization and deserialization.

color

The color of the player

Type:

str

hand

List of cards in the player’s hand

Type:

List[Card]

pawns

List of all pawns belonging to the player

Type:

List[Pawn]

turns

Number of turns for this player

Type:

int

color: PlayerColor

hand: List[Card]

pawns: List[Pawn]

turns: int = 0

copy() → Player

Return a fully-independent copy of the player.

public_data() → Player

Return a fully-independent copy of the player with only public data visible.

find_first_pawn_in_start() → Pawn | None

Find the first pawn in the start area, if any.

all_pawns_in_home() → bool

Whether all of this user’s pawns are in home.

class apologies.game.History

Tracks an action taken during the game.

action

String describing the action

Type:

str

color

Color of the player associated with the action

Type:

Optional[PlayerColor]

card

Card associated with the action

Type:

Optional[CardType]

timestamp

Timestamp tied to the action (defaults to current time)

Type:

DateTime

action: str

color: PlayerColor | None

card: CardType | None

timestamp: pendulum.datetime.DateTime

__str__() → str

Return str(self).

class apologies.game.PlayerView

A player-specific view of the game, showing only the information a player would have available on their turn.

player

The player associated with the view.

Type:

Player

opponents

The player’s opponents, with private information stripped

Type:

Dict[PlayerColor, Player]

player: Player

opponents: Dict[PlayerColor, Player]

copy() → PlayerView

Return a fully-independent copy of the player view.

get_pawn(prototype: Pawn) → Pawn | None

Return the pawn from this view with the same color and index.

all_pawns() → List[Pawn]

Return a list of all pawns on the board.

class apologies.game.Game

The game, consisting of state for a set of players.

Callers should not pass in optional constructor arguments. These are accessible to support serialization and deserialization.

playercount

Number of players in the game

Type:

int

players

All players in the game

Type:

Dict[PlayerColor, Player]

deck

The deck of cards for the game

Type:

Deck

history

Game history

Type:

History

property started: bool

Whether the game has been started.

property completed: bool

Whether the game is completed.

property winner: Player | None

The winner of the game, if any.

playercount: int

players: Dict[PlayerColor, Player]

deck: Deck

history: List[History]

copy() → Game

Return a fully-independent copy of the game.

to_json() → str

Serialize the game state to JSON.

static from_json(data: str) → Game

Deserialize the game state from JSON.

track(action: str, player: Player | None = None, card: Card | None = None) → None

Tracks an action taken during the game.

create_player_view(color: PlayerColor) → PlayerView

Return a player-specific view of the game, showing only the information a player would have available on their turn.

apologies.game.CIRCLE

apologies.game.TURN

apologies.game.SLIDE