blackjack21 package

Submodules

blackjack21.dealer module

class blackjack21.dealer.Dealer(name: str, *, hit_soft_17: bool = False)

Bases: object

Dealer class.

Parameters:

• name – str

• hit_soft_17 – bool, whether the dealer hits on a soft 17

add_card(card: Card) → None

Adds a card to the dealer’s hand.

property bust: bool

Dealer’s bust status (total > 21).

clear_hand() → None

Clears the dealer’s hand.

property hand: list[Card]

The list of Card objects in the dealer’s hand.

property is_soft: bool

Checks if the hand is ‘soft’ (an Ace is counted as 11).

property name: str

Dealer’s name.

property stand: bool

Dealer’s stand status (total >= 17).

property total: int

Dealer’s hand total.

blackjack21.deck module

class blackjack21.deck.Card(suit: CardSuit, rank: CardRank, value: int)

Bases: object

Card class.

Parameters:

• suit – suit of the card

• rank – rank of the card

• value – value of the card in the game

rank: CardRank

suit: CardSuit

value: int

class blackjack21.deck.Deck(suits: Sequence[CardSuit], ranks: Mapping[CardRank, int] = {'10': 10, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9, 'A': 11, 'J': 10, 'K': 10, 'Q': 10}, *, count: int = 1)

Bases: object

Deck of cards class (Iterable).

Parameters:

• suits – sequence of 4 suits

• ranks – A mapping of card ranks to their integer values.

• count – int number of decks to be merged

Raises:

• InvalidSuits – if length of suits is not 4

• InvalidRanks – if length of ranks is not 13

property cards: list[Card]

List of Card class objects currently in the deck.

draw_card() → Card

Draw a card. Auto-resets from drawn pile if empty.

Returns:

Card object

Raises:

EmptyDeckError – if the deck and drawn pile are both empty

property drawn_cards: list[Card]

List of Card class objects drawn from the deck.

property penetration: float

Returns the percentage of the deck that has been used, from 0.0 to 1.0.

reset() → None

Resets the deck by returning all drawn cards and reshuffling.

shuffle() → None

Shuffle the cards in the deck.

blackjack21.exceptions module

exception blackjack21.exceptions.BlackjackException(*args)

Bases: Exception

Blackjack base class exception.

exception blackjack21.exceptions.EmptyDeckError

Bases: BlackjackException

Raised when attempting to draw from an empty deck.

exception blackjack21.exceptions.InvalidActionError(message: str)

Bases: BlackjackException

Raised when an action is attempted in an invalid game state.

exception blackjack21.exceptions.InvalidPlayersData(player_data: tuple[str, int])

Bases: BlackjackException

Raised when the input player data is invalid.

exception blackjack21.exceptions.InvalidRanks(ranks: Sequence[CardRank])

Bases: BlackjackException

Raised when length of ranks tuple is not 13.

exception blackjack21.exceptions.InvalidSuits(suits: Sequence[CardSuit])

Bases: BlackjackException

Raised when length of suits tuple is not 4.

exception blackjack21.exceptions.PlayDealerFailure(name: str)

Bases: BlackjackException

Raised when dealer tries to play their hand before all players have finished.

exception blackjack21.exceptions.PlayFailure(name: str, action: str)

Bases: BlackjackException

Raised when player tries to play double down/split when they are not eligible.

blackjack21.players module

class blackjack21.players.GameResult(value)

Bases: str, Enum

Represents the outcome of a player’s hand.

BLACKJACK = 'BLACKJACK'

DEALER_BUST = 'DEALER_BUST'

DEALER_WIN = 'DEALER_WIN'

PLAYER_BUST = 'PLAYER_BUST'

PLAYER_WIN = 'PLAYER_WIN'

PUSH = 'PUSH'

SURRENDER = 'SURRENDER'

class blackjack21.players.GameState(value)

Bases: str, Enum

Represents the current phase of the game.

DEALER_TURN = 'DEALER_TURN'

INIT = 'INIT'

PLAYERS_TURN = 'PLAYERS_TURN'

ROUND_OVER = 'ROUND_OVER'

class blackjack21.players.Hand(bet: BetAmount)

Bases: object

A single hand of cards. Does not know its owner.

Parameters:

bet – int

add_card(card: Card) → None

Adds a card to the hand.

property bet: BetAmount

Player’s bet amount.

property bust: bool

Player’s bust status.

double_bet() → None

Double the bet (for double-down).

property is_complete: bool

Hand cannot take more actions.

mark_stood() → None

Record that the player explicitly chose to stand.

pop_card() → Card

Remove and return the last card (for splitting).

result: GameResult | None

surrender() → None

Mark this hand as surrendered.

property surrendered: bool

Player’s surrender status.

property total: int

Player’s hand total.

class blackjack21.players.Player(name: PlayerName, bet: BetAmount)

Bases: object

Player class, containing one or more hands.

Parameters:

• name – str

• bet – int

property hands: list[Hand]

List of Hand class objects for the player.

insert_hand_after(existing: Hand, new_hand: Hand) → None

Insert a new hand immediately after an existing one (for splitting).

property name: PlayerName

Player name.

blackjack21.table module

class blackjack21.table.Action(value)

Bases: str, Enum

Player actions during their turn.

DOUBLE = 'double'

HIT = 'hit'

SPLIT = 'split'

STAND = 'stand'

SURRENDER = 'surrender'

class blackjack21.table.CardSource(*args, **kwargs)

Bases: Protocol

Anything that can provide cards.

draw_card() → Card

class blackjack21.table.Table(players: Iterable[tuple[str, int]], deck: CardSource, *, dealer_name: str = 'Dealer', hit_soft_17: bool = False, on_round_reset: Callable[[], None] | None = None)

Bases: object

Create object for this class to initialize a blackjack table (Iterable through players).

Parameters:

• players – An iterable of player tuples (name, bet).

• deck – A card source to be used for the game.

• dealer_name – The name of the dealer.

• hit_soft_17 – bool, whether the dealer hits on a soft 17.

• on_round_reset – Optional callback invoked when a round resets.

available_actions() → frozenset[Action]

Returns the set of legal actions for the current hand.

property current_hand: Hand | None

The hand that is currently being played.

property current_player: Player | None

The player whose hand is currently being played.

property dealer: Dealer

Table’s Dealer class object.

property dealer_visible_hand: list[Card]

The dealer’s hand that is visible to players.

If the players’ turns are over, it returns the full hand. Otherwise, it returns only the first card (the up-card).

property deck: CardSource

The table’s card source.

double_down() → Card

The current hand doubles the bet, takes one more card, and stands.

hit() → Card

The current hand takes another card. Advances to the next hand if it busts or stands.

property players: list[Player]

List of Player class objects for the Table.

split() → None

Splits the current hand if the two cards have the same value.

stand() → None

The current hand stands. The game moves to the next hand.

start_game() → None

Deals the initial cards to start the game.

property state: GameState

The current phase of the game.

surrender() → None

The current hand surrenders. Only allowed on the first two cards.

blackjack21.table.shoe_reset_hook(deck: Deck, threshold: float = 0.75) → Callable[[], None]

Standard shoe management: reset when penetration exceeds threshold.

blackjack21.table.validate_player(name: str, bet: int) → tuple[PlayerName, BetAmount]

Validate raw player data at the boundary and wrap in domain types.

Module contents

blackjack21.

class blackjack21.Action(value)

Bases: str, Enum

Player actions during their turn.

DOUBLE = 'double'

HIT = 'hit'

SPLIT = 'split'

STAND = 'stand'

SURRENDER = 'surrender'

exception blackjack21.BlackjackException(*args)

Bases: Exception

Blackjack base class exception.

class blackjack21.Card(suit: CardSuit, rank: CardRank, value: int)

Bases: object

Card class.

Parameters:

• suit – suit of the card

• rank – rank of the card

• value – value of the card in the game

rank: CardRank

suit: CardSuit

value: int

class blackjack21.CardSource(*args, **kwargs)

Bases: Protocol

Anything that can provide cards.

draw_card() → Card

class blackjack21.Dealer(name: str, *, hit_soft_17: bool = False)

Bases: object

Dealer class.

Parameters:

• name – str

• hit_soft_17 – bool, whether the dealer hits on a soft 17

add_card(card: Card) → None

Adds a card to the dealer’s hand.

property bust: bool

Dealer’s bust status (total > 21).

clear_hand() → None

Clears the dealer’s hand.

property hand: list[Card]

The list of Card objects in the dealer’s hand.

property is_soft: bool

Checks if the hand is ‘soft’ (an Ace is counted as 11).

property name: str

Dealer’s name.

property stand: bool

Dealer’s stand status (total >= 17).

property total: int

Dealer’s hand total.

class blackjack21.Deck(suits: Sequence[CardSuit], ranks: Mapping[CardRank, int] = {'10': 10, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9, 'A': 11, 'J': 10, 'K': 10, 'Q': 10}, *, count: int = 1)

Bases: object

Deck of cards class (Iterable).

Parameters:

• suits – sequence of 4 suits

• ranks – A mapping of card ranks to their integer values.

• count – int number of decks to be merged

Raises:

• InvalidSuits – if length of suits is not 4

• InvalidRanks – if length of ranks is not 13

property cards: list[Card]

List of Card class objects currently in the deck.

draw_card() → Card

Draw a card. Auto-resets from drawn pile if empty.

Returns:

Card object

Raises:

EmptyDeckError – if the deck and drawn pile are both empty

property drawn_cards: list[Card]

List of Card class objects drawn from the deck.

property penetration: float

Returns the percentage of the deck that has been used, from 0.0 to 1.0.

reset() → None

Resets the deck by returning all drawn cards and reshuffling.

shuffle() → None

Shuffle the cards in the deck.

exception blackjack21.EmptyDeckError

Bases: BlackjackException

Raised when attempting to draw from an empty deck.

class blackjack21.GameResult(value)

Bases: str, Enum

Represents the outcome of a player’s hand.

BLACKJACK = 'BLACKJACK'

DEALER_BUST = 'DEALER_BUST'

DEALER_WIN = 'DEALER_WIN'

PLAYER_BUST = 'PLAYER_BUST'

PLAYER_WIN = 'PLAYER_WIN'

PUSH = 'PUSH'

SURRENDER = 'SURRENDER'

class blackjack21.GameState(value)

Bases: str, Enum

Represents the current phase of the game.

DEALER_TURN = 'DEALER_TURN'

INIT = 'INIT'

PLAYERS_TURN = 'PLAYERS_TURN'

ROUND_OVER = 'ROUND_OVER'

class blackjack21.Hand(bet: BetAmount)

Bases: object

A single hand of cards. Does not know its owner.

Parameters:

bet – int

add_card(card: Card) → None

Adds a card to the hand.

property bet: BetAmount

Player’s bet amount.

property bust: bool

Player’s bust status.

double_bet() → None

Double the bet (for double-down).

property is_complete: bool

Hand cannot take more actions.

mark_stood() → None

Record that the player explicitly chose to stand.

pop_card() → Card

Remove and return the last card (for splitting).

result: GameResult | None

surrender() → None

Mark this hand as surrendered.

property surrendered: bool

Player’s surrender status.

property total: int

Player’s hand total.

class blackjack21.HandTotal(value: int, is_soft: bool)

Bases: NamedTuple

Computed hand total with metadata.

is_soft: bool

Alias for field number 1

value: int

Alias for field number 0

exception blackjack21.InvalidActionError(message: str)

Bases: BlackjackException

Raised when an action is attempted in an invalid game state.

exception blackjack21.InvalidPlayersData(player_data: tuple[str, int])

Bases: BlackjackException

Raised when the input player data is invalid.

exception blackjack21.InvalidRanks(ranks: Sequence[CardRank])

Bases: BlackjackException

Raised when length of ranks tuple is not 13.

exception blackjack21.InvalidSuits(suits: Sequence[CardSuit])

Bases: BlackjackException

Raised when length of suits tuple is not 4.

exception blackjack21.PlayDealerFailure(name: str)

Bases: BlackjackException

Raised when dealer tries to play their hand before all players have finished.

exception blackjack21.PlayFailure(name: str, action: str)

Bases: BlackjackException

Raised when player tries to play double down/split when they are not eligible.

class blackjack21.Player(name: PlayerName, bet: BetAmount)

Bases: object

Player class, containing one or more hands.

Parameters:

• name – str

• bet – int

property hands: list[Hand]

List of Hand class objects for the player.

insert_hand_after(existing: Hand, new_hand: Hand) → None

Insert a new hand immediately after an existing one (for splitting).

property name: PlayerName

Player name.

class blackjack21.Table(players: Iterable[tuple[str, int]], deck: CardSource, *, dealer_name: str = 'Dealer', hit_soft_17: bool = False, on_round_reset: Callable[[], None] | None = None)

Bases: object

Create object for this class to initialize a blackjack table (Iterable through players).

Parameters:

• players – An iterable of player tuples (name, bet).

• deck – A card source to be used for the game.

• dealer_name – The name of the dealer.

• hit_soft_17 – bool, whether the dealer hits on a soft 17.

• on_round_reset – Optional callback invoked when a round resets.

available_actions() → frozenset[Action]

Returns the set of legal actions for the current hand.

property current_hand: Hand | None

The hand that is currently being played.

property current_player: Player | None

The player whose hand is currently being played.

property dealer: Dealer

Table’s Dealer class object.

property dealer_visible_hand: list[Card]

The dealer’s hand that is visible to players.

If the players’ turns are over, it returns the full hand. Otherwise, it returns only the first card (the up-card).

property deck: CardSource

The table’s card source.

double_down() → Card

The current hand doubles the bet, takes one more card, and stands.

hit() → Card

The current hand takes another card. Advances to the next hand if it busts or stands.

property players: list[Player]

List of Player class objects for the Table.

split() → None

Splits the current hand if the two cards have the same value.

stand() → None

The current hand stands. The game moves to the next hand.

start_game() → None

Deals the initial cards to start the game.

property state: GameState

The current phase of the game.

surrender() → None

The current hand surrenders. Only allowed on the first two cards.

blackjack21.shoe_reset_hook(deck: Deck, threshold: float = 0.75) → Callable[[], None]

Standard shoe management: reset when penetration exceeds threshold.

blackjack21.validate_player(name: str, bet: int) → tuple[PlayerName, BetAmount]

Validate raw player data at the boundary and wrap in domain types.