game

game.action_type

class texasholdem.game.action_type.ActionType(value)[source]

An enum representing the types of actions a player can take.

ALL_IN = 2: Posts all available chips to the current pot.

CALL = 3: Posts the minimum chips to remain in the pot.

CHECK = 4: Passes the action.

FOLD = 5: Folds the hand and exits the pot.

RAISE = 1: Raises the latest pot.

game.game

The game module includes lightweight data classes:

Player

Pot

GameState

It also includes the main TexasHoldEm class.

class texasholdem.game.game.GameState(value)[source]

An enum representing the state of the game (not just one hand)

RUNNING = 1: The table is active and is able to play hands.

STOPPED = 2: The table is inactive due to lack of players or lack of chips and unable to play hands.

class texasholdem.game.game.Player(player_id, chips)[source]

The TexasHoldEm class uses this class as a bookkeeping mechanism.

player_id

The player id

Type:: int

chips

The number of chips the player has behind them

Type:: int

state

The player state

Type:: PlayerState

last_pot

The pot id of the last pot the player is eligible for.

Type:: int

class texasholdem.game.game.Pot[source]

Class representing a betting pot, players will post to the pot. If players post more than the raised amount, we set the new raised amount.

At the end of a betting round, the bets are consolidated and reset.

amount

The amount of chips in the pot NOT including the current betting round

Type:: int

raised

The highest bet amount in the current betting round

Type:: int

player_amounts

A map from player id to # chips each player has posted this round

Type:: Dict[int, int]

chips_to_call(player_id)[source]

Returns the amount of chips to call for the given player.

Parameters:

player_id (int) – The player_id of the player in the pot

Returns:

The amount the player needs to call to be in this pot.: This is just raised if the player hasn’t bet yet.

Return type:

int

collect_bets()[source]: Collects all the bets players made this round and adds them to the total amount. Resets player betting.

get_amount()[source]

Returns:: How many chips this pot contains not including the current round of betting.
Return type:: int

get_player_amount(player_id)[source]

Parameters:: player_id (int) – The player id
Returns:: the amount the player has bet currently for this pot.
Return type:: int

get_total_amount()[source]

Returns:: How many chips this pot contains including the current round of betting.
Return type:: int

player_post(player_id, amount)[source]

The given player posts amount into this pot. If the total amount for the player exceeds the current raised value, sets it anew.

Parameters:

player_id (int) – The player_id of the player posting
amount (int) – The amount to post into this pot

players_in_pot()[source]

Returns:: An iterator over the player player_id’s that have a stake in this pot.
Return type:: Iterator[int]

remove_player(player_id)[source]

Removes the given player from the pot and adds their betting to the total amount.

Parameters:: player_id (int) – The player id

split_pot(raised_level)[source]

Returns a pot with players and the overflow over the raised_level

Parameters:: raised_level (int) – The chip count to cut off at
Returns:: The new Pot or None if self.raised <= raised_level
Return type:: Pot, optional

class texasholdem.game.game.TexasHoldEm(buyin, big_blind, small_blind, max_players=9)[source]

Represents a table of TexasHoldEm (tournament style).

Instantiate this object with the buyin, big blind, small blind, and the number of players.

To interact with this class, call TexasHoldEm.start_hand() which will run the PREHAND phase (move/post blinds, reset pots, deal cards, etc.)

To input an action at each stage, call TexasHoldEm.take_action() which will execute the given action for the current player.

Parameters:

buyin (int) – The buyin to register for this game.
big_blind (int) – Big blind
small_blind (int) – Small blind
max_players (int) – how many players can sit at the table, defaults to 9.

buyin

The buyin to register for this game.

Type:: int

big_blind

Big blind

Type:: int

small_blind

Small blind

Type:: int

max_players

how many players can sit at the table, defaults to 9.

Type:: int

players

A list of all players in the game.

Type:: List[Player]

btn_loc

The id of the player who has the button.

Type:: int

bb_loc

The id of the player who has the big blind.

Type:: int

sb_loc

The id of the player who has the small blind.

Type:: int

current_player

The id of the player who is to act.

Type:: int

pots

The active Pot objects in the game.

Type:: List[Pot]

board

The communal cards that are out.

Type:: List[Card]

hands

Map from player id to their hand

Type:: Dict[int, List[Card]]

last_raise

The amount of the last raise (that was over the previous bet)

Type:: int

raise_option

If the current player has the option to raise (not taking into account chip count). This is usually true and is only useful in the context of WSOP 2021 Rule 96 regarding when an all-in raise action does not trigger another round of betting.

Type:: bool

num_hands

The number of hands played so far.

Type:: int

hand_phase

The current hand phase

Type:: HandPhase

game_state

The current GameState

Type:: GameState

hand_history

The history of the current hand.

Type:: History

action

get the last action of the game.

Type:: Tuple[ActionType, Optional[int]]

property action: Get the last action (check, call, raise of flop).

active_iter(loc=None, reverse=False)[source]

Iterates through all players that can take an action. i.e. players with states IN or TO_CALL (not including ALL_IN).

Parameters:

loc (int, optional) – The location to start at, defaults to current_player
reverse (bool) – In reverse play order, default False

Returns:

An iterator over active players who can take an action.

Return type:

Iterator[int]

chips_at_stake(player_id)[source]

Parameters:: player_id (int)
Returns:: The amount of chips the player is eligible to win
Return type:: int

chips_to_call(player_id)[source]

Parameters:: player_id (int) – The player id
Returns:: The amount of chips the player needs to call in all pots to play the hand.
Return type:: int

copy(shuffle=True)[source]

Parameters:: shuffle (bool) – Shuffle the deck, defaults to true.
Returns:: A copy of the game.
Return type:: TexasHoldEm

export_history(path='./texas.pgn')[source]

Exports the hand history to a human-readable file. If a directory is given, finds a name of the form texas(n).pgn to export to. PGN files can consequently be imported with import_history().

Parameters:: path (str | os.PathLike]) – The directory or file to export the history to, defaults to the current working directory at the file ./texas.pgn
Returns:: The path to the history file
Return type:: os.PathLike

get_available_moves()[source]

Returns:

A special iterator over the possible moves for the current player,: includes attributes such as action_types and raise_range.

Return type:

MoveIterator

Added in version 0.9.0.

get_hand(player_id)[source]

Parameters:

player_id (int) – The player id

Returns:

A two element list of the hand of the given player,: if the player has not been dealt a hand, returns an empty list

Return type:

List[Card]

static import_history(path)[source]

Import a PGN file i.e. as exported from export_history(). Returns an iterator over game states as specified from the history.

Parameters:

path (str | os.PathLike) – The PGN file to import from

Returns:

An iterator over game states such that: the next hand will play exactly like from the history.

Return type:

Iterator[TexasHoldEm]

Raises:

HistoryImportError – If the file given does not exist or if the file is invalid

in_pot_iter(loc=None, reverse=False)[source]

Iterates through all players with a stake in the pot (i.e. all players without states OUT or SKIP

Parameters:

loc (int, optional) – The location to start at, defaults to current_player
reverse (bool) – In reverse play order, default False

Returns:

An iterator over players with a stake in the pot

Return type:

Iterator[int]

is_game_running()[source]

Returns:: True if the game is running, false o/w
Return type:: bool

is_hand_running()[source]

Returns:: True if there is a hand running, false o/w
Return type:: bool

min_raise()[source]

Returns:: The minimum amount a player can raise by.
Return type:: int

Added in version 0.6.0.

player_bet_amount(player_id)[source]

Parameters:: player_id (int) – The player player_id
Returns:: The amount of chips the player bet this round across all pots.
Return type:: int

player_iter(loc=None, reverse=False, match_states=(PlayerState.SKIP, PlayerState.OUT, PlayerState.IN, PlayerState.TO_CALL, PlayerState.ALL_IN), filter_states=())[source]

Iterates through all players starting at player_id and rotating in order of increasing player id.

Parameters:

loc (int, optional) – The player_id to start at, default is current_player.
reverse (bool) – In reverse play order, default False
match_states (Iterable[PlayerState]) – Only include players with the given states
filter_states (Iterable[PlayerState]) – Exclude players with the given states

Returns:

An iterator over all player ids.

Return type:

Iterator[int]

start_hand()[source]

Starts a new hand. Handles SKIP, not enough chips, resetting pots, rotation and posting of blinds, dealing cards, etc.

Raises:: ValueError – If a hand already in progress.

take_action(action_type, value=None, total=None)[source]

The current player takes the specified action.

Note

value and total are mutually exclusive.

Parameters:

action_type (ActionType) – The action type
value (int, optional) – For a raise action, how much to raise to.
total (int, optional) – For a raise action, how much to raise to.

Raises:

ValueError – If no hand is running or if the move is invalid.

Changed in version 0.6.0: The value has been renamed to total and will be redefined in 1.0.0. Currently, value and total mean to raise to the amount given. In 1.0.0, value will mean to raise an amount more than the current bet amount.

total_to_value(total, player_id)[source]

Translates a raise phrase “raise to total” to the phrase “raise value”.

Parameters:

total (int, optional) – A total amount to raise
player_id (int) – The player who’s doing the raising

Returns:

A translation to an amount the player is raising by

Return type:

Optional[int]

Added in version 0.6.0.

validate_move(player_id=None, action=None, value=None, total=None, throws=False)[source]

Validate the potentially invalid action for the given player.

Note

value and total are mutually exclusive.

Parameters:

player_id (int, optional) – The player to take action. Default current_player.
action (int, optional) – The ActionType to take
value (int, optional) – For a raise action, how much to raise to.
total (int, optional) – For a raise action, how much to raise to.
throws (bool) – If true, will throw an Exception instead if the move is invalid. Default False.

Returns:

True if the move is valid, False otherwise.

Return type:

bool

Raises:

ValueError – If move is invalid and throws is True

Changed in version 0.6.0: The value has been renamed to total and will be redefined in 1.0.0. Currently, value and total mean to raise to the amount given. In 1.0.0, value will mean to raise an amount more than the current bet amount.

value_to_total(value, player_id)[source]

Translates a raise phrase “raise value” to the phrase “raise to total”.

Parameters:

value (int, optional) – An amount to raise past the previous bet
player_id (int) – The player who’s doing the raising

Returns:

A translation to an amount the player is raising to

Return type:

Optional[int]

Added in version 0.6.0.

game.hand_phase

class texasholdem.game.hand_phase.HandPhase(value)[source]

An enum representing the phases of each hand which includes the well-known

HandPhase.PREFLOP

HandPhase.FLOP

HandPhase.TURN

HandPhase.RIVER

In addition to two new phases

HandPhase.PREHAND

HandPhase.SETTLE

which are used for book-keeping.

FLOP = _HandPhase(new_cards=3, next_phase='TURN'): The second betting round of the game. Three communal cards come outs.

PREFLOP = _HandPhase(new_cards=0, next_phase='FLOP'): The first betting round of the game. Players have two cards with no communal cards yet.

PREHAND = _HandPhase(new_cards=0, next_phase='PREFLOP'): In this phase, players sit out if requested, players rejoin if requested, blinds are moved and posted, and card are dealt.

RIVER = _HandPhase(new_cards=1, next_phase='SETTLE'): The fourth and final betting round of the game. One more communal cards come out.

SETTLE = _HandPhase(new_cards=0, next_phase='PREHAND'): If the hand ended early in a previous round, the rest of the communal cards come out to total 5. Winners are decided per pot based on hand strength and rewarded chips.

TURN = _HandPhase(new_cards=1, next_phase='RIVER'): The third betting round of the game. One more communal card comes out.

new_cards()[source]

Returns:: The number of new cards to add to the board
Return type:: int

next_phase()[source]

Returns:: The next HandPhase after this one
Return type:: HandPhase

game.history

The history module includes various dataclasses intended to keep the history of the game to be able to replay hands and export/import notation of the game.

Texas Hold Em Notation Conventions:

The button is assigned ID 0

Each action is a tuple (player_id, action_type, total)

The winner section is a per-pot tuple (Pot id, amount, best rank, winner ids)

class texasholdem.game.history.BettingRoundHistory(new_cards, actions)[source]

Bases: object

History of a Betting Round

actions: A list of PlayerActions

static from_string(string)[source]

Reverse of to_string()

Parameters:: string (str) – The string as returned from to_string()
Returns:: The betting round as represented by the string
Return type:: BettingRoundHistory

new_cards: The new cards that were added this round

to_string(canon_ids)[source]

Parameters:

canon_ids (Dict[int, int]) – Map of old_id -> new_id where the new btn_loc is 0

Returns:

The string representation of the betting round history:: new cards revealed, ordered list of actions

Return type:

str

texasholdem.game.history.FILE_EXTENSION = 'pgn': The extension for the game notation file.

class texasholdem.game.history.History(prehand=None, preflop=None, settle=None, flop=None, turn=None, river=None)[source]

Bases: object

History class of a hand of TexasHoldEm. Includes one history item for each HandPhase. In total, this constitutes a minimal amount of information necessary to replay a hand.

This class also includes to_string() and from_string() methods which provides ways to write / read human-readable information to / from files.

combined_actions()[source]

A list of PlayerAction objects that was taken.

Returns:: The cumulative actions of all players in the game
Return type:: list[PlayerAction]

export_history(path='./texas.pgn')[source]

Exports the hand history to a human-readable file. If a directory is given, finds a name of the form texas(n).pgn to export to. PGN files can consequently be imported with import_history().

Parameters:: path (str | os.PathLike]) – The directory or file to export the history to, defaults to the current working directory at the file ./texas.pgn
Returns:: The path to the history file
Return type:: os.PathLike

flop = None: The Flop History

static from_string(string)[source]

Reverse of to_string()

Parameters:: string (str) – The string as returned from to_string()
Returns:: The hand history as represented by the string
Return type:: History
Raises:: HistoryImportError – If the PGN file is invalid

static import_history(path)[source]

Import a PGN file i.e. as exported from export_history(). Returns an iterator over game states as specified from the history.

Parameters:: path (str | os.PathLike) – The PGN file to import from
Returns:: The history object represented by the PGN file
Return type:: History
Raises:: HistoryImportError – If the file given does not exist or if the file is invalid

preflop = None: The Preflop History

prehand = None: The Prehand History

river = None: The River History

settle = None: The Settle History

to_string()[source]

Returns the string representation of the hand history, including the blind sizes, chips, players cards, in addition to revealed cards per street and an ordered list of actions per street. By convention, we assign the button an ID of 0 in this representation.

Returns:: The string representation of the hand history.
Return type:: str

turn = None: The Turn History

exception texasholdem.game.history.HistoryImportError[source]

Bases: Exception

The history classes will throw this error if it cannot import the given PGN file.

class texasholdem.game.history.PlayerAction(player_id, action_type, total=None, value=None)[source]

Bases: object

History of a Player Action

action_type: The action type

static from_string(string)[source]

Reverse of to_string()

Parameters:: string (str) – The string as returned from to_string()
Returns:: The player action as represented by the string
Return type:: PlayerAction

player_id: The player id

to_string(canon_ids)[source]

Parameters:: canon_ids (Dict[int, int]) – Map of old_id -> new_id where the new btn_loc is 0
Returns:: The string representation of a player action: id, action, amount
Return type:: str

total = None: The total raise amount

value = None: The amount raised

class texasholdem.game.history.PrehandHistory(btn_loc, big_blind, small_blind, player_chips, player_cards)[source]

Bases: object

History of the Prehand Phase

big_blind: The id of the player with the big blind

btn_loc: The id of the player with the button

static from_string(string)[source]

Reverse of to_string()

Parameters:: string (str) – The string as returned from to_string()
Returns:: The prehand history as represented by the string
Return type:: PrehandHistory
Raises:: HistoryImportError – If missing information or a mismatch between cards and chips

player_cards: The cards for each player

player_chips: The number of chips for each player

small_blind: The id of the player with the small blind

to_string(canon_ids)[source]

Parameters:: canon_ids (Dict[int, int]) – Map of old_id -> new_id where the new btn_loc is 0
Returns:: The string representation of the prehand history: blind sizes, chips, and cards
Return type:: str

class texasholdem.game.history.SettleHistory(new_cards, pot_winners)[source]

Bases: object

History of the Settle Phase

static from_string(string)[source]

Reverse of to_string()

Parameters:: string (str) – The string as returned from to_string()
Returns:: The settle history as represented by the string
Return type:: SettleHistory

new_cards: The new cards that were added this round

pot_winners: A map from pot_id to a tuple of winner data amount, best rank, list of winners

to_string(canon_ids)[source]

Parameters:

canon_ids (Dict[int, int]) – Map of old_id -> new_id where the new btn_loc is 0

Returns:

The string representation of the settle history: new cards revealed,: and the winners per pot: (pot_id, total_amount, best_rank, winners list)

Return type:

str

game.move

The move module includes classes related to collections of moves

class texasholdem.game.move.MoveIterator(moves)[source]

Parameters:: moves (Dict[ActionType, Optional[range]) – a dictionary from ActionType to Optional[range] where most of the values will be None with the ActionType.RAISE action having a range as a value.

Added in version 0.9.0.

property action_types: Returns: List[ActionType]: A list of action types represented

property raise_range

The range of the represented raise action, if no raise is possible this is just range(0)

Returns:: The range of the represented raise action.
Return type:: range

sample(num=1)[source]

Parameters:: num (int) – The number of samples
Returns:: The sample(s) of action, total tuples
Return type:: Union[Tuple[ActionType, Optional[int]], List[Tuple[ActionType, Optional[int]]]]

game.player_state

class texasholdem.game.player_state.PlayerState(value)[source]

Player state Enum. For example, if a player is in the pot with the proper amount of chips, that player is said to be PlayerState.IN. If a player needs to call a bet, that player has status PlayerState.TO_CALL. If a player has no more chips to bet, that player is PlayerState.ALL_IN, etc.

ALL_IN = 5: Player is all-in and cannot take more actions this hand.

IN = 3: Player is in the latest pot and has put in enough chips.

OUT = 2: Player has folded their hand this round.

SKIP = 1: Player is sitting out this hand, they will not be dealt cards and will rejoin upon request. Will be implemented in a future version.

TO_CALL = 4: Player is in the latest pot and needs to call a raise.