Example

The following is a simple example of how to use the library to simulate a round of whist with some very basic bots (the source code for example_strategy.py and printing_event_listener.py is also included further below).

print_one_round.py

"""Use the `whist_backend` module to make 5 simple bots play a round of whist."""

from __future__ import annotations

from typing import TYPE_CHECKING

from example_strategy import NoThinkingStrategy
from printing_event_listener import PrinterEventListener

from whist_backend import RoundSimulator

if TYPE_CHECKING:
    from whist_backend.player_strategy_protocol import PlayerStrategy

if __name__ == "__main__":
    strategies: list[PlayerStrategy] = [
        NoThinkingStrategy("Player 1"),
        NoThinkingStrategy("Player 2"),
        NoThinkingStrategy("Player 3"),
        NoThinkingStrategy("Player 4"),
        NoThinkingStrategy("Player 5"),
    ]
    round_simulator = RoundSimulator(
        strategies, event_listeners=[PrinterEventListener()]
    )
    results = round_simulator.play_round()
    for result in results:
        print(f"{result[0].name} won {result[1]} points.")

Sample output for this script would look something like:

Sample output

REVEALED CARD:  4♥ (trump suit ♥, hand size 6)
PLAYERS:
Player 1: hand  8♠, 3♥,10♣, 7♣, K♣, 5♠
Player 2: hand  Q♣, 5♥, 9♦, 9♥, J♦, 5♦
Player 3: hand  K♠, A♣, K♦, 6♥, 2♥, 8♦
Player 4: hand  Q♠, A♦, 4♦, Q♦, 2♣,10♥
Player 5: hand  6♦, 5♣, 7♥, 6♣,10♠, 3♠

BETS:
Player 1: 0
Player 2: 0
Player 3: 0
Player 4: 0
Player 5: 7

A new trick is starting with 0
Player 1 played  8♠ (remaining cards  3♥,10♣, 7♣, K♣, 5♠).
Player 2 played  Q♣ (remaining cards  5♥, 9♦, 9♥, J♦, 5♦).
Player 3 played  K♠ (remaining cards  A♣, K♦, 6♥, 2♥, 8♦).
Player 4 played  Q♠ (remaining cards  A♦, 4♦, Q♦, 2♣,10♥).
Player 5 played 10♠ (remaining cards  6♦, 5♣, 7♥, 6♣, 3♠).
Player 3 won the trick!

A new trick is starting with 2
Player 3 played  A♣ (remaining cards  K♦, 6♥, 2♥, 8♦).
Player 4 played  2♣ (remaining cards  A♦, 4♦, Q♦,10♥).
Player 5 played  5♣ (remaining cards  6♦, 7♥, 6♣, 3♠).
Player 1 played 10♣ (remaining cards  3♥, 7♣, K♣, 5♠).
Player 2 played  5♥ (remaining cards  9♦, 9♥, J♦, 5♦).
Player 2 won the trick!

A new trick is starting with 1
Player 2 played  9♦ (remaining cards  9♥, J♦, 5♦).
Player 3 played  K♦ (remaining cards  6♥, 2♥, 8♦).
Player 4 played  A♦ (remaining cards  4♦, Q♦,10♥).
Player 5 played  6♦ (remaining cards  7♥, 6♣, 3♠).
Player 1 played  3♥ (remaining cards  7♣, K♣, 5♠).
Player 1 won the trick!

A new trick is starting with 0
Player 1 played  7♣ (remaining cards  K♣, 5♠).
Player 2 played  9♥ (remaining cards  J♦, 5♦).
Player 3 played  6♥ (remaining cards  2♥, 8♦).
Player 4 played  4♦ (remaining cards  Q♦,10♥).
Player 5 played  6♣ (remaining cards  7♥, 3♠).
Player 2 won the trick!

A new trick is starting with 1
Player 2 played  J♦ (remaining cards  5♦).
Player 3 played  8♦ (remaining cards  2♥).
Player 4 played  Q♦ (remaining cards 10♥).
Player 5 played  7♥ (remaining cards  3♠).
Player 1 played  K♣ (remaining cards  5♠).
Player 5 won the trick!

A new trick is starting with 4
Player 5 played  3♠ (remaining cards ).
Player 1 played  5♠ (remaining cards ).
Player 2 played  5♦ (remaining cards ).
Player 3 played  2♥ (remaining cards ).
Player 4 played 10♥ (remaining cards ).
Player 4 won the trick!

Player 1 won -1 points.
Player 2 won -2 points.
Player 3 won -1 points.
Player 4 won -1 points.
Player 5 won -6 points.

example_strategy.py

from __future__ import annotations

from typing import TYPE_CHECKING, Optional

from whist_backend import Bet, PlayerStrategy

if TYPE_CHECKING:
    from whist_backend.cards import Card


class NoThinkingStrategy(PlayerStrategy):
    def __init__(self, name: str) -> None:
        self.name = name

    def make_move(self, allowed_cards: list[Card]) -> Card:
        return allowed_cards[0]

    def make_bet(self, disallowed_bet: Optional[int] = None) -> Bet:
        return Bet(disallowed_bet + 1 if disallowed_bet is not None else 0, False)

printing_event_listener.py

from __future__ import annotations

from typing import TYPE_CHECKING, Iterator

from whist_backend import WhistEventListener

if TYPE_CHECKING:
    from whist_backend import Bet, Card, Suit
    from whist_backend.round_simulator import _Player


class PrinterEventListener(WhistEventListener):
    """A simple example WhistEventListener that prints information about game events."""

    def notify_round_start(
        self,
        revealed_card: Card,
        trump_suit: Suit,
        hand_size: int,
        players: list[_Player],
    ) -> None:
        print(
            f"REVEALED CARD: {revealed_card} "
            + f"(trump suit {trump_suit}, hand size {hand_size})"
        )
        print("PLAYERS:")
        for player in players:
            print(player)
        print()

    def notify_card_played(self, player: _Player, played_card: Card) -> None:
        print(
            f"{player.strategy.name} played {played_card} "
            f"(remaining cards {','.join(map(str, player.hand))})."
        )

    def notify_trick_won(self, player: _Player) -> None:
        print(f"{player.strategy.name} won the trick!")
        print()

    def notify_bets_made(self, bets: Iterator[tuple[_Player, Bet]]) -> None:
        print("BETS:")
        for player, bet in bets:
            print(f"{player.strategy.name}: {bet}")
        print()

    def notify_new_trick(self, player_id: int) -> None:
        print(f"A new trick is starting with {player_id}")