Reference

pokerkit.analysis module

pokerkit.analysis implements classes related to poker analysis.

class pokerkit.analysis.Statistics(payoffs: list[int])

Bases: object

The class for player statistics.

Parameters:: payoffs – The payoffs of each hand.

classmethod from_hand_history(*hhs: HandHistory) → dict[str, Statistics]

Obtain statistics for each position and players (if any) for a hand history or hand histories.

Parameters:: hh – The hand history/histories to analyze.
Returns:: The hand history statistics.

classmethod merge(*statistics: Statistics) → Statistics

Merge the statistics.

Parameters:: statistics – The statistics to merge.
Returns:: The merged stats.

property payoff_mean: float

Return the payoff rate (per hand).

Returns:: The payoff rate.

property payoff_stderr: float

Return the payoff standard error.

Returns:: The payoff standard error.

property payoff_stdev: float

Return the payoff standard deviation.

Returns:: The payoff standard deviation.

property payoff_sum: float

Return the total payoff.

Returns:: The total payoff.

payoffs: list[int]: The payoffs.

property sample_count: int

Return the sample size.

Returns:: The sample size.

pokerkit.analysis.calculate_equities(hole_ranges: Iterable[Iterable[Iterable[Card]]], board_cards: Iterable[Card], hole_dealing_count: int, board_dealing_count: int, deck: Deck, hand_types: Iterable[type[Hand]], *, sample_count: int, executor: Executor | None = None) → list[float]

Calculate the equities.

The user may supply an executor to use parallelization. If not given, a single-threaded evaluation is performed.

>>> from concurrent.futures import ProcessPoolExecutor
>>> from pokerkit import *
>>> calculate_equities(
...     (
...         parse_range('33'),
...         parse_range('33'),
...     ),
...     Card.parse('Tc8d6h4s'),
...     2,
...     5,
...     Deck.STANDARD,
...     (StandardHighHand,),
...     sample_count=1000,
... )
[0.5, 0.5]
>>> calculate_equities(
...     (
...         parse_range('2h2c'),
...         parse_range('3h3c'),
...         parse_range('AhKh'),
...     ),
...     Card.parse('3s3d4c'),
...     2,
...     5,
...     Deck.STANDARD,
...     (StandardHighHand,),
...     sample_count=1000,
... )
[0.0, 1.0, 0.0]
>>> with ProcessPoolExecutor() as executor:
...     calculate_equities(
...         (
...             parse_range('2h2c'),
...             parse_range('3h3c'),
...             parse_range('AsKs'),
...         ),
...         Card.parse('QsJsTs'),
...         2,
...         5,
...         Deck.STANDARD,
...         (StandardHighHand,),
...         sample_count=1000,
...         executor=executor,
...     )
...
[0.0, 0.0, 1.0]

Parameters:

hole_ranges – The ranges of each player in the pot.
board_cards – The board cards, may be empty.
hole_dealing_count – The final number of hole cards; for hold’em, it is 2.
board_dealing_count – The final number of board cards; for hold’em, it is 5.
deck – The deck; most games typically use pokerkit.utilities.Deck.STANDARD.
hand_types – The hand types; most games typically just use pokerkit.hands.StandardHighHand.
sample_count – The number of samples to simulate, higher value gives greater accuracy and fidelity.
executor – The optional executor, defaults to None which is just using 1 thread/process. The user can supply a ProcessPoolExecutor to use processes.

Returns:

The equity values.

pokerkit.analysis.calculate_hand_strength(player_count: int, hole_range: Iterable[Iterable[Card]], board_cards: Iterable[Card], hole_dealing_count: int, board_dealing_count: int, deck: Deck, hand_types: Iterable[type[Hand]], *, sample_count: int, executor: Executor | None = None) → float

Calculate the hand strength: odds of beating a single other hand chosen uniformly at random.

The user may supply an executor to use parallelization. If not given, a single-threaded evaluation is performed.

>>> from concurrent.futures import ProcessPoolExecutor
>>> from pokerkit import *
>>> calculate_hand_strength(
...     3,
...     parse_range('3h3c'),
...     Card.parse('3s3d2c2h'),
...     2,
...     5,
...     Deck.STANDARD,
...     (StandardHighHand,),
...     sample_count=1000,
... )
1.0
>>> with ProcessPoolExecutor() as executor:
...     calculate_hand_strength(
...         3,
...         parse_range('AsKs'),
...         Card.parse('QsJsTs'),
...         2,
...         5,
...         Deck.STANDARD,
...         (StandardHighHand,),
...         sample_count=1000,
...         executor=executor,
...     )
...
1.0

Parameters:

player_count – Number of players in the pot.
hole_range – The range of the player.
board_cards – The board cards, may be empty.
hole_dealing_count – The final number of hole cards; for hold’em, it is 2.
board_dealing_count – The final number of board cards; for hold’em, it is 5.
deck – The deck; most games typically use pokerkit.utilities.Deck.STANDARD.
hand_types – The hand types; most games typically just use pokerkit.hands.StandardHighHand.
sample_count – The number of samples to simulate, higher value gives greater accuracy and fidelity.
executor – The optional executor, defaults to None which is just using 1 thread/process. The user can supply a ProcessPoolExecutor to use processes.

Returns:

The equity values.

pokerkit.analysis.calculate_icm(payouts: Iterable[float], chips: Iterable[float]) → tuple[float, ...]

Calculate the independent chip model (ICM) values.

>>> calculate_icm([70, 30], [50, 30, 20])  
(45.17..., 32.25, 22.57...)
>>> calculate_icm([50, 30, 20], [25, 87, 88])  
(25.69..., 37.08..., 37.21...)
>>> calculate_icm([50, 30, 20], [21, 89, 90])  
(24.85..., 37.51..., 37.63...)
>>> calculate_icm([50, 30, 20], [198, 1, 1])  
(49.79..., 25.10..., 25.10...)

Parameters:

payouts – The payouts.
chips – The players’ chips.

Returns:

The ICM values.

pokerkit.analysis.parse_range(*raw_ranges: str, rank_order: RankOrder = RankOrder.STANDARD) → set[frozenset[Card]]

Parse the range.

The notations can be separated by a whitespace, comma, or a semicolon. The returned range is a set of frozensets of cards.

>>> rng = parse_range('AKs')
>>> len(rng)
4
>>> frozenset(Card.parse('AsKs')) in rng
True
>>> frozenset(Card.parse('AcKd')) in rng
False

Parameters:

raw_ranges – The raw ranges to be parsed.
rank_order – The rank ordering to be used, defaults to pokerkit.utilities.RankOrder.

Returns:

The range.

pokerkit.games module

pokerkit.games implements various poker game definitions.

The classes here allow users to “save” certain configurations to create poker states in a simple manner. This is crucial, as poker states require tons of parameters to be specified.

class pokerkit.games.DeuceToSevenLowballMixin

Bases: object

The abstract base class for deuce-to-seven lowball games.

deck: ClassVar[Deck] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardLowHand'>,)

hole_dealing_count: ClassVar[int] = 5

class pokerkit.games.Draw(automations: tuple[~pokerkit.state.Automation, ...], streets: tuple[~pokerkit.state.Street, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Poker, ABC

The abstract base class for draw games.

hole_dealing_count: ClassVar[int]: The number of hole dealings.

max_completion_betting_or_raising_count: ClassVar[int | None]: The maximum number of completions, bettings, or raisings.

class pokerkit.games.FixedLimitBadugi(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, TripleDraw

The class for fixed-limit badugi games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit badugi game.

Below shows an example badugi hand from Wikipedia.

Link: https://en.wikipedia.org/wiki/Badugi

>>> from math import inf
>>> state = FixedLimitBadugi.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     4,
...     inf,
...     4,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('????????')  # Bob  
HoleDealing(commentary=None, player_index=0, cards=(??, ??, ??, ??),...
>>> state.deal_hole('????????')  # Carol  
HoleDealing(commentary=None, player_index=1, cards=(??, ??, ??, ??),...
>>> state.deal_hole('????????')  # Ted  
HoleDealing(commentary=None, player_index=2, cards=(??, ??, ??, ??),...
>>> state.deal_hole('????????')  # Alice  
HoleDealing(commentary=None, player_index=3, cards=(??, ??, ??, ??),...

>>> state.fold()  # Ted
Folding(commentary=None, player_index=2)
>>> state.check_or_call()  # Alice
CheckingOrCalling(commentary=None, player_index=3, amount=2)
>>> state.check_or_call()  # Bob
CheckingOrCalling(commentary=None, player_index=0, amount=1)
>>> state.check_or_call()  # Carol
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Below shows the first draw and actions.

>>> state.stand_pat_or_discard('????')  # Bob  
StandingPatOrDiscarding(commentary=None, player_index=0, cards=(??, ...
>>> state.stand_pat_or_discard('????')  # Carol  
StandingPatOrDiscarding(commentary=None, player_index=1, cards=(??, ...
>>> state.stand_pat_or_discard('??')  # Alice
StandingPatOrDiscarding(commentary=None, player_index=3, cards=(??,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('????')  # Bob  
HoleDealing(commentary=None, player_index=0, cards=(??, ??), statuse...
>>> state.deal_hole('????')  # Carol  
HoleDealing(commentary=None, player_index=1, cards=(??, ??), statuse...
>>> state.deal_hole('??')  # Alice  
HoleDealing(commentary=None, player_index=3, cards=(??,), statuses=(...

>>> state.check_or_call()  # Bob
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.complete_bet_or_raise_to()  # Carol
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=2)
>>> state.check_or_call()  # Alice
CheckingOrCalling(commentary=None, player_index=3, amount=2)
>>> state.check_or_call()  # Bob
CheckingOrCalling(commentary=None, player_index=0, amount=2)

Below shows the second draw and actions.

>>> state.stand_pat_or_discard('??')  # Bob
StandingPatOrDiscarding(commentary=None, player_index=0, cards=(??,))
>>> state.stand_pat_or_discard()  # Carol
StandingPatOrDiscarding(commentary=None, player_index=1, cards=())
>>> state.stand_pat_or_discard('??')  # Alice
StandingPatOrDiscarding(commentary=None, player_index=3, cards=(??,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('??')  # Bob  
HoleDealing(commentary=None, player_index=0, cards=(??,), statuses=(...
>>> state.deal_hole('??')  # Alice  
HoleDealing(commentary=None, player_index=3, cards=(??,), statuses=(...

>>> state.check_or_call()  # Bob
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.complete_bet_or_raise_to()  # Carol
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=4)
>>> state.complete_bet_or_raise_to()  # Alice
CompletionBettingOrRaisingTo(commentary=None, player_index=3, amount=8)
>>> state.fold()  # Bob
Folding(commentary=None, player_index=0)
>>> state.check_or_call()  # Carol
CheckingOrCalling(commentary=None, player_index=1, amount=4)

Below shows the third draw and actions.

>>> state.stand_pat_or_discard('??')  # Carol
StandingPatOrDiscarding(commentary=None, player_index=1, cards=(??,))
>>> state.stand_pat_or_discard()  # Alice
StandingPatOrDiscarding(commentary=None, player_index=3, cards=())
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('??')  # Carol  
HoleDealing(commentary=None, player_index=1, cards=(??,), statuses=(...

>>> state.check_or_call()  # Carol
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.complete_bet_or_raise_to()  # Alice
CompletionBettingOrRaisingTo(commentary=None, player_index=3, amount=4)
>>> state.check_or_call()  # Carol
CheckingOrCalling(commentary=None, player_index=1, amount=4)

Below show the showdown.

>>> state.show_or_muck_hole_cards(
...     '2s4c6d9h',
... )  # Alice  
HoleCardsShowingOrMucking(commentary=None, player_index=3, hole_card...
>>> state.show_or_muck_hole_cards(
...     '3s5d7c8h',
... )  # Carol  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...

Below show the final stacks.

>>> state.stacks
[inf, inf, inf, inf]
>>> state.payoffs
[-4, 20, 0, -16]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

deck: ClassVar[Deck] = (Ac, Ad, Ah, As, 2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks)

The deck.

Different variants use different decks, which must be specified.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.BadugiHand'>,)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

hole_dealing_count: ClassVar[int] = 4: The number of hole dealings.

class pokerkit.games.FixedLimitDeuceToSevenLowballTripleDraw(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, DeuceToSevenLowballMixin, TripleDraw

The class for fixed-limit deuce-to-seven lowball triple draw games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit deuce-to-seven lowball triple draw game.

Below shows a bad beat between Yockey and Arieh.

Link: https://youtu.be/pChCqb2FNxY

>>> state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (75000, 150000),
...     150000,
...     300000,
...     (1180000, 4340000, 5910000, 10765000),
...     4,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('7h6c4c3d2c')  # Yockey  
HoleDealing(commentary=None, player_index=0, cards=(7h, 6c, 4c, 3d, ...
>>> state.deal_hole('??????????')  # Hui  
HoleDealing(commentary=None, player_index=1, cards=(??, ??, ??, ??, ...
>>> state.deal_hole('??????????')  # Esposito  
HoleDealing(commentary=None, player_index=2, cards=(??, ??, ??, ??, ...
>>> state.deal_hole('AsQs6s5c3c')  # Arieh  
HoleDealing(commentary=None, player_index=3, cards=(As, Qs, 6s, 5c, ...

>>> state.fold()  # Esposito
Folding(commentary=None, player_index=2)
>>> state.complete_bet_or_raise_to()  # Arieh  
CompletionBettingOrRaisingTo(commentary=None, player_index=3, amount...
>>> state.complete_bet_or_raise_to()  # Yockey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.fold()  # Hui
Folding(commentary=None, player_index=1)
>>> state.check_or_call()  # Arieh
CheckingOrCalling(commentary=None, player_index=3, amount=150000)

Below shows the first draw and actions.

>>> state.stand_pat_or_discard()  # Yockey
StandingPatOrDiscarding(commentary=None, player_index=0, cards=())
>>> state.stand_pat_or_discard('AsQs')  # Arieh  
StandingPatOrDiscarding(commentary=None, player_index=3, cards=(As, ...
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('2hQh')  # Arieh  
HoleDealing(commentary=None, player_index=3, cards=(2h, Qh), statuse...

>>> state.complete_bet_or_raise_to()  # Yockey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Arieh
CheckingOrCalling(commentary=None, player_index=3, amount=150000)

Below shows the second draw and actions.

>>> state.stand_pat_or_discard()  # Yockey
StandingPatOrDiscarding(commentary=None, player_index=0, cards=())
>>> state.stand_pat_or_discard('Qh')  # Arieh
StandingPatOrDiscarding(commentary=None, player_index=3, cards=(Qh,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('4d')  # Arieh  
HoleDealing(commentary=None, player_index=3, cards=(4d,), statuses=(...

>>> state.complete_bet_or_raise_to()  # Yockey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Arieh
CheckingOrCalling(commentary=None, player_index=3, amount=300000)

Below shows the third draw and actions.

>>> state.stand_pat_or_discard()  # Yockey
StandingPatOrDiscarding(commentary=None, player_index=0, cards=())
>>> state.stand_pat_or_discard('6s')  # Arieh
StandingPatOrDiscarding(commentary=None, player_index=3, cards=(6s,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_hole('7c')  # Arieh  
HoleDealing(commentary=None, player_index=3, cards=(7c,), statuses=(...

>>> state.complete_bet_or_raise_to()  # Yockey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Arieh
CheckingOrCalling(commentary=None, player_index=3, amount=280000)

Below show the final stacks.

>>> state.stacks
[0, 4190000, 5910000, 12095000]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

class pokerkit.games.FixedLimitOmahaHoldemHighLowSplitEightOrBetter(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: PotLimitPokerMixin, OmahaHoldemMixin, Holdem

The class for fixed-limit Omaha hold’em high/low-split eight or better low games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit Omaha hold’em high/low-split eight or better low game.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.OmahaHoldemHand'>, <class 'pokerkit.hands.OmahaEightOrBetterLowHand'>)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

class pokerkit.games.FixedLimitPokerMixin

Bases: object

The mixin for fixed-limit poker games.

betting_structure: ClassVar[BettingStructure] = 'Fixed-limit'

max_completion_betting_or_raising_count: ClassVar[int | None] = 4

class pokerkit.games.FixedLimitRazz(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, SevenCardStud

The class for fixed-limit razz games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit razz game.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
bring_in – The bring-in.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

deck: ClassVar[Deck] = (Ac, Ad, Ah, As, 2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks)

The deck.

Different variants use different decks, which must be specified.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.RegularLowHand'>,)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

low: ClassVar[bool] = True: The low status.

class pokerkit.games.FixedLimitSevenCardStud(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, SevenCardStud

The class for fixed-limit seven card stud games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit seven card stud game.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
bring_in – The bring-in.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

deck: ClassVar[Deck] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The deck.

Different variants use different decks, which must be specified.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardHighHand'>,)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

low: ClassVar[bool] = False: The low status.

class pokerkit.games.FixedLimitSevenCardStudHighLowSplitEightOrBetter(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, SevenCardStud

The class for fixed-limit seven card stud high/low-split eight or better low games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit seven card stud high/low-split eight or better low game.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
bring_in – The bring-in.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

deck: ClassVar[Deck] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The deck.

Different variants use different decks, which must be specified.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardHighHand'>, <class 'pokerkit.hands.EightOrBetterLowHand'>)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

low: ClassVar[bool] = False: The low status.

class pokerkit.games.FixedLimitTexasHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: FixedLimitPokerMixin, TexasHoldemMixin, Holdem

The class for fixed-limit Texas hold’em games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a fixed-limit Texas hold’em game.

Below is an example hand in fixed-limit Texas hold’em.

>>> state = FixedLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     4,
...     200,
...     2,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('AcAs')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, As), statuse...
>>> state.deal_hole('7h6h')  
HoleDealing(commentary=None, player_index=1, cards=(7h, 6h), statuse...

>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=4)
>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount=6)
>>> state.fold()
Folding(commentary=None, player_index=1)

Below show the final stacks.

>>> state.stacks
[204, 196]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The antes.
raw_blinds_or_straddles – The blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
raw_starting_stacks – The starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

class pokerkit.games.Holdem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Poker, ABC

The abstract base class for hold’em games.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

hole_dealing_count: ClassVar[int]: The number of hole dealings.

max_completion_betting_or_raising_count: ClassVar[int | None]: The maximum number of completions, bettings, or raisings.

class pokerkit.games.NoLimitDeuceToSevenLowballSingleDraw(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: NoLimitPokerMixin, DeuceToSevenLowballMixin, SingleDraw

The class for no-limit deuce-to-seven lowball single draw games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a no-limit deuce-to-seven lowball single draw game.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
min_bet – The min bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

class pokerkit.games.NoLimitPokerMixin

Bases: object

The mixin for no-limit poker games.

betting_structure: ClassVar[BettingStructure] = 'No-limit'

max_completion_betting_or_raising_count: ClassVar[int | None] = None

class pokerkit.games.NoLimitRoyalHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: NoLimitTexasHoldem

The class for no-limit royal hold’em games.

deck: ClassVar[Deck] = (Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The deck.

Different variants use different decks, which must be specified.

class pokerkit.games.NoLimitShortDeckHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: NoLimitPokerMixin, UnfixedLimitHoldem

The class for no-limit short-deck hold’em games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a no-limit short-deck hold’em game.

Below shows an all-in hand between Xuan and Phua.

Link: https://youtu.be/QlgCcphLjaQ

>>> state = NoLimitShortDeckHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     3000,
...     {-1: 3000},
...     3000,
...     (495000, 232000, 362000, 403000, 301000, 204000),
...     6,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('Th8h')  # Badziakouski  
HoleDealing(commentary=None, player_index=0, cards=(Th, 8h), statuse...
>>> state.deal_hole('QsJd')  # Zhong  
HoleDealing(commentary=None, player_index=1, cards=(Qs, Jd), statuse...
>>> state.deal_hole('QhQd')  # Xuan  
HoleDealing(commentary=None, player_index=2, cards=(Qh, Qd), statuse...
>>> state.deal_hole('8d7c')  # Jun  
HoleDealing(commentary=None, player_index=3, cards=(8d, 7c), statuse...
>>> state.deal_hole('KhKs')  # Phua  
HoleDealing(commentary=None, player_index=4, cards=(Kh, Ks), statuse...
>>> state.deal_hole('8c7h')  # Koon  
HoleDealing(commentary=None, player_index=5, cards=(8c, 7h), statuse...

>>> state.check_or_call()  # Badziakouski
CheckingOrCalling(commentary=None, player_index=0, amount=3000)
>>> state.check_or_call()  # Zhong
CheckingOrCalling(commentary=None, player_index=1, amount=3000)
>>> state.complete_bet_or_raise_to(35000)  # Xuan  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.fold()  # Jun
Folding(commentary=None, player_index=3)
>>> state.complete_bet_or_raise_to(
...     298000,
... )  # Phua  
CompletionBettingOrRaisingTo(commentary=None, player_index=4, amount...
>>> state.fold()  # Koon
Folding(commentary=None, player_index=5)
>>> state.fold()  # Badziakouski
Folding(commentary=None, player_index=0)
>>> state.fold()  # Zhong
Folding(commentary=None, player_index=1)
>>> state.check_or_call()  # Xuan
CheckingOrCalling(commentary=None, player_index=2, amount=263000)

Below shows the flop dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('9h6cKc')
BoardDealing(commentary=None, cards=(9h, 6c, Kc))

Below shows the turn dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Jh')
BoardDealing(commentary=None, cards=(Jh,))

Below shows the river dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ts')
BoardDealing(commentary=None, cards=(Ts,))

Below show the final stacks.

>>> state.stacks
[489000, 226000, 684000, 400000, 0, 198000]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
min_bet – The min bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

deck: ClassVar[Deck] = (6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The deck.

Different variants use different decks, which must be specified.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.ShortDeckHoldemHand'>,)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

hole_dealing_count: ClassVar[int] = 2: The number of hole dealings.

class pokerkit.games.NoLimitTexasHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: NoLimitPokerMixin, TexasHoldemMixin, UnfixedLimitHoldem

The class for no-limit Texas hold’em games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a no-limit Texas hold’em game.

Below shows the 4-runout hand between Phil Hellmuth and the Loose Cannon Ernest Wiggins.

Link: https://youtu.be/cnjJv7x0HMY?si=4l05Ez7lQVczt8DI&t=638

>>> from math import inf
>>> from pokerkit import Automation, Mode, NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     False,
...     {-1: 600},
...     (200, 400, 800),
...     400,
...     (inf, 116400, 86900, inf, 50000, inf),
...     6,
...     mode=Mode.CASH_GAME,
... )

Below are the pre-flop dealings and actions.

>>> state.deal_hole('JsTh')  # Tony G  
HoleDealing(commentary=None, player_index=0, cards=(Js, Th), statuse...
>>> state.deal_hole('Ah9d')  # Hellmuth  
HoleDealing(commentary=None, player_index=1, cards=(Ah, 9d), statuse...
>>> state.deal_hole('KsKc')  # Wiggins  
HoleDealing(commentary=None, player_index=2, cards=(Ks, Kc), statuse...
>>> state.deal_hole('5c2h')  # Negreanu  
HoleDealing(commentary=None, player_index=3, cards=(5c, 2h), statuse...
>>> state.deal_hole('6h5h')  # Brunson  
HoleDealing(commentary=None, player_index=4, cards=(6h, 5h), statuse...
>>> state.deal_hole('6s3s')  # Laak  
HoleDealing(commentary=None, player_index=5, cards=(6s, 3s), statuse...
>>> state.fold()  # Negreanu
Folding(commentary=None, player_index=3)
>>> state.complete_bet_or_raise_to(
...     2800,
... )  # Brunson  
CompletionBettingOrRaisingTo(commentary=None, player_index=4, amount...
>>> state.fold()  # Laak
Folding(commentary=None, player_index=5)
>>> state.check_or_call()  # Tony G
CheckingOrCalling(commentary=None, player_index=0, amount=2600)
>>> state.complete_bet_or_raise_to(
...     12600,
... )  # Hellmuth  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.check_or_call()  # Wiggins
CheckingOrCalling(commentary=None, player_index=2, amount=11800)
>>> state.check_or_call()  # Brunson
CheckingOrCalling(commentary=None, player_index=4, amount=9800)
>>> state.check_or_call()  # Tony G
CheckingOrCalling(commentary=None, player_index=0, amount=9800)

Below are the flop dealing and actions.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('9hTs9s')
BoardDealing(commentary=None, cards=(9h, Ts, 9s))
>>> state.check_or_call()  # Tony G
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.complete_bet_or_raise_to(
...     17000,
... )  # Hellmuth  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.complete_bet_or_raise_to(
...     36000,
... )  # Wiggins  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.fold()  # Brunson
Folding(commentary=None, player_index=4)
>>> state.fold()  # Tony G
Folding(commentary=None, player_index=0)
>>> state.complete_bet_or_raise_to(
...     103800,
... )  # Hellmuth  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.check_or_call()  # Wiggins
CheckingOrCalling(commentary=None, player_index=2, amount=38300)

Below is selecting the number of runouts.

>>> state.select_runout_count(4)  # Hellmuth
RunoutCountSelection(commentary=None, player_index=1, runout_count=4)
>>> state.select_runout_count(None)  # Wiggins  
RunoutCountSelection(commentary=None, player_index=2, runout_count=N...

Below is the first runout.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Jh')  # Turn
BoardDealing(commentary=None, cards=(Jh,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ad')  # River
BoardDealing(commentary=None, cards=(Ad,))

Below is the second runout.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Kh')  # Turn
BoardDealing(commentary=None, cards=(Kh,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('3c')  # River
BoardDealing(commentary=None, cards=(3c,))

Below is the third runout.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('7s')  # Turn
BoardDealing(commentary=None, cards=(7s,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('8s')  # River
BoardDealing(commentary=None, cards=(8s,))

Below is the fourth runout.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Qc')  # Turn
BoardDealing(commentary=None, cards=(Qc,))
>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Kd')  # River
BoardDealing(commentary=None, cards=(Kd,))

Below are the final stacks.

>>> state.stacks
[inf, 79400, 149700, inf, 37400, inf]

Below shows the first televised million dollar pot between Tom Dwan and Phil Ivey.

Link: https://youtu.be/GnxFohpljqM

>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     500,
...     (1000, 2000),
...     2000,
...     (1125600, inf, 553500),
...     3,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('Ac2d')  # Ivey  
HoleDealing(commentary=None, player_index=0, cards=(Ac, 2d), statuse...
>>> state.deal_hole('????')  # Antonius  
HoleDealing(commentary=None, player_index=1, cards=(??, ??), statuse...
>>> state.deal_hole('7h6h')  # Dwan  
HoleDealing(commentary=None, player_index=2, cards=(7h, 6h), statuse...

>>> state.complete_bet_or_raise_to(7000)  # Dwan  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.complete_bet_or_raise_to(23000)  # Ivey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.fold()  # Antonius
Folding(commentary=None, player_index=1)
>>> state.check_or_call()  # Dwan
CheckingOrCalling(commentary=None, player_index=2, amount=16000)

Below shows the flop dealing and actions.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Jc3d5c')
BoardDealing(commentary=None, cards=(Jc, 3d, 5c))

>>> state.complete_bet_or_raise_to(35000)  # Ivey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Dwan
CheckingOrCalling(commentary=None, player_index=2, amount=35000)

Below shows the turn dealing and actions.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('4h')
BoardDealing(commentary=None, cards=(4h,))

>>> state.complete_bet_or_raise_to(90000)  # Ivey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.complete_bet_or_raise_to(
...     232600,
... )  # Dwan  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.complete_bet_or_raise_to(
...     1067100,
... )  # Ivey  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Dwan
CheckingOrCalling(commentary=None, player_index=2, amount=262400)

Below shows the river dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Jh')
BoardDealing(commentary=None, cards=(Jh,))

Below shows the final stacks.

>>> state.stacks
[572100, inf, 1109500]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The antes.
raw_blinds_or_straddles – The blinds or straddles.
min_bet – The min bet.
raw_starting_stacks – The starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

class pokerkit.games.OmahaHoldemMixin

Bases: object

The mixin for Omaha hold’em games.

deck: ClassVar[Deck] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

hole_dealing_count: ClassVar[int] = 4

class pokerkit.games.Poker(automations: tuple[~pokerkit.state.Automation, ...], streets: tuple[~pokerkit.state.Street, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: ABC

The abstract base class for poker games.

The instances of this class serves two purposes. First, it allows the users to save state initialization parameters so they do not have to be specified each time a new state is created. Second, the number and complexities of parameters that has to be specified to initialize the state is reduced.

Parameters:

automations – The automations.
streets – The streets.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
bring_in – The bring-in.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

ante_trimming_status: bool

The ante trimming status.

It denotes whether or not to activate the trimming behavior during bet collection immediately after the antes are posted.

Usually, if you want uniform antes, set this to True. If you want non-uniform antes like big blind antes, set this to False.

automations: tuple[Automation, ...]

The automations.

Allows the user to specify what steps they do not care about and therefore should be automatically handled by PokerKit.

betting_structure: ClassVar[BettingStructure]

The betting structure.

This class attribute determines the betting limits of a particular game (e.g., no-limit, pot-limit, or fixed-limit).

property big_bet: int

Return the big bet.

This is the min-bet amount of the last street.

It may be different from the small bet (primarily in fixed-limit games).

Returns:: The big bet.

bring_in: int

The bring-in.

Some poker games do not have the bring-in, in which case 0 should be its value.

property button_status: bool

Return whether this game is a button game (i.e., has a rotating button).

We deem that a variant is a button game if it has betting round whose opener is decided based on position (not up card/hand like in stud).

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.button_status
True

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.button_status
False

Returns:: The button status.

deck: ClassVar[Deck]

The deck.

Different variants use different decks, which must be specified.

divmod: Callable[[int, int], tuple[int, int]]

The divmod function.

This is used to denote how pots are divided up (for multiple boards, multiple winners, multiple hand types, etc.).

hand_types: ClassVar[tuple[type[Hand], ...]]

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

property max_board_card_count: int

Return the maximum number of board cards that can be dealt.

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.max_board_card_count
5

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.max_board_card_count
0

Returns:: The maximum number of board cards.

property max_down_card_count: int

Return the maximum number of down cards a single player can have.

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.max_down_card_count
2

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.max_down_card_count
3

Returns:: The maximum number of down cards.

property max_hole_card_count: int

Return the maximum number of hole cards a single player can have.

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.max_hole_card_count
2

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.max_hole_card_count
7

Returns:: The maximum number of hole cards.

property max_up_card_count: int

Return the maximum number of up cards a single player can have.

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.max_up_card_count
0

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.max_up_card_count
4

Returns:: The maximum number of up cards.

property min_bet: int

Return the min bet.

Returns:: The min bet.
Raises:: ValueError – If the small and big bets are not identical.

mode: Mode

The mode.

There are two modes available to be set: the tournament and cash-game mode. Tournaments use a stricter rule-set than typical cash-games. For more details, please consult pokerkit.state.Mode.

rake: Callable[[int, State], tuple[int, int]]

The rake function.

Rake functions are used in PokerKit to denote how the rakes are collected from the pot. Multiple pots may exist (side-pots) in which case the method is called for each pot.

property rank_orders: tuple[RankOrder, ...]

Return the rank orders for each hand type used.

A hand type may use different rank orderings (deuce-low, ace-low, etc.).

>>> game = NoLimitTexasHoldem((), True, 0, (1, 2), 2)
>>> game.rank_orders  
(<RankOrder.STANDARD: (<Rank.DEUCE: '2'>, <Rank.TREY: '3'>, <Rank.FO...

>>> game = FixedLimitRazz((), True, 1, 1, 2, 4)
>>> game.rank_orders  
(<RankOrder.REGULAR: (<Rank.ACE: 'A'>, <Rank.DEUCE: '2'>, <Rank.TREY...

Returns:: The rank orders.

raw_antes: Iterable[int] | Mapping[int, int] | int

The “raw” antes.

In PokerKit, the term raw is used to denote the fact that they can be supplied in many forms and will be “parsed” or “evaluated” further to convert them into a more ideal form.

For instance, 0 will be interpreted as no ante for all players. Another value will be interpreted as that value as the antes for all. [0, 2] and {1: 2} will be considered as the big blind ante whereas ``{-1: 2} will be considered as the button ante.

raw_blinds_or_straddles: Iterable[int] | Mapping[int, int] | int

The “raw” blinds or straddles.

Just like for the antes, the blinds/straddles are also “interpreted” by PokerKit in the same fashion.

property small_bet: int

Return the small bet.

This is the min-bet amount of the first street.

It may be different from the big bet (primarily in fixed-limit games).

Returns:: The small bet.

starting_board_count: int

The starting board count.

For most poker games, it should be 1. Of course, for double board games, it should be 2. Triple/Quadruple/etc. board games are almost unheard of. Therefore, this value should mostly be 1 or sometimes 2.

streets: tuple[Street, ...]

The streets.

Each street contains information about the corresponding betting round and corresponding dealing/draw stage before it occurs.

class pokerkit.games.PotLimitOmahaHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: PotLimitPokerMixin, OmahaHoldemMixin, UnfixedLimitHoldem

The class for pot-limit Omaha hold’em games.

classmethod create_state(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, raw_starting_stacks: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>) → State

Create a pot-limit Omaha hold’em game.

Below shows the largest online poker pot every played between Patrik Antonius and Viktor Blom.

Link: https://youtu.be/UMBm66Id2AA

>>> state = PotLimitOmahaHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (500, 1000),
...     1000,
...     (1259450.25, 678473.5),
...     2,
... )

Below shows the pre-flop dealings and actions.

>>> state.deal_hole('Ah3sKsKh')  # Antonius  
HoleDealing(commentary=None, player_index=0, cards=(Ah, 3s, Ks, Kh),...
>>> state.deal_hole('6d9s7d8h')  # Blom  
HoleDealing(commentary=None, player_index=1, cards=(6d, 9s, 7d, 8h),...

>>> state.complete_bet_or_raise_to(3000)  # Blom  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.complete_bet_or_raise_to(
...     9000,
... )  # Antonius  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.complete_bet_or_raise_to(27000)  # Blom  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.complete_bet_or_raise_to(
...     81000,
... )  # Antonius  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Blom
CheckingOrCalling(commentary=None, player_index=1, amount=54000)

Below shows the flop dealing and actions.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('4s5c2h')
BoardDealing(commentary=None, cards=(4s, 5c, 2h))

>>> state.complete_bet_or_raise_to(
...     91000,
... )  # Antonius  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.complete_bet_or_raise_to(
...     435000,
... )  # Blom  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.complete_bet_or_raise_to(
...     779000,
... )  # Antonius  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.check_or_call()  # Blom
CheckingOrCalling(commentary=None, player_index=1, amount=162473.5)

Below shows the turn dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('5h')
BoardDealing(commentary=None, cards=(5h,))

Below shows the river dealing.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('9c')
BoardDealing(commentary=None, cards=(9c,))

Below show the final stacks.

>>> state.stacks
[1937923.75, 0.0]

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
min_bet – The min bet.
raw_starting_stacks – The “raw” starting stacks.
player_count – The number of players.
starting_board_count – The starting board count.
mode – The mode.
divmod – The divmod function.
rake – The rake function.

Returns:

The created state.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.OmahaHoldemHand'>,)

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

class pokerkit.games.PotLimitPokerMixin

Bases: object

The mixin for pot-limit poker games.

betting_structure: ClassVar[BettingStructure] = 'Pot-limit'

max_completion_betting_or_raising_count: ClassVar[int | None] = None

class pokerkit.games.SevenCardStud(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, bring_in: int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Poker, ABC

The abstract base class for seven card stud games.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
bring_in – The bring-in.
small_bet – The small bet.
big_bet – The big bet.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

low: ClassVar[bool]: The low status.

max_completion_betting_or_raising_count: ClassVar[int | None]: The maximum number of completions, bettings, or raisings.

class pokerkit.games.SingleDraw(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Draw, ABC

The abstract base class for single draw games.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
min_bet – The min bet.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

class pokerkit.games.TexasHoldemMixin

Bases: object

The mixin for Texas hold’em games.

deck: ClassVar[Deck] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardHighHand'>,)

hole_dealing_count: ClassVar[int] = 2

class pokerkit.games.TripleDraw(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, small_bet: int, big_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Draw, ABC

The abstract base class for triple draw games.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
small_bet – The small bet.
big_bet – The big bet.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

class pokerkit.games.UnfixedLimitHoldem(automations: tuple[~pokerkit.state.Automation, ...], ante_trimming_status: bool, raw_antes: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, raw_blinds_or_straddles: ~collections.abc.Iterable[int] | ~collections.abc.Mapping[int, int] | int, min_bet: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: Holdem, ABC

The abstract base class for unfixed-limit hold’em games.

Parameters:

automations – The automations.
ante_trimming_status – The ante trimming status.
raw_antes – The “raw” antes.
raw_blinds_or_straddles – The “raw” blinds or straddles.
min_bet – The minimum bet.
mode – The mode.
starting_board_count – The starting board count.
divmod – The divmod function.
rake – The rake function.

max_completion_betting_or_raising_count: ClassVar[int | None] = None: The maximum number of completions, bettings, or raisings.

pokerkit.hands module

pokerkit.hands implements classes related to poker hands.

class pokerkit.hands.BadugiHand(cards: Iterable[Card] | Card | str)

Bases: Hand

The class for badugi hands (ace-to-five).

>>> h0 = BadugiHand('Kc')
>>> h1 = BadugiHand('Ac')
>>> h2 = BadugiHand('4c8dKh')
>>> h3 = BadugiHand('Ac2d3h5s')
>>> h4 = BadugiHand('Ac2d3h4s')
>>> h0 < h1 < h2 < h3 < h4
True

>>> h = BadugiHand('Ac2d3c4s5c')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2d3c4s5c' form an invalid BadugiHand hand.
>>> h = BadugiHand('Ac2d3c4s')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2d3c4s' form an invalid BadugiHand hand.
>>> h = BadugiHand('AcAd3h4s')
Traceback (most recent call last):
    ...
ValueError: The cards 'AcAd3h4s' form an invalid BadugiHand hand.
>>> h = BadugiHand('Ac2c')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2c' form an invalid BadugiHand hand.
>>> h = BadugiHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid BadugiHand hand.

classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

>>> h0 = BadugiHand.from_game('2s4c5d6h')
>>> h1 = BadugiHand('2s4c5d6h')
>>> h0 == h1
True
>>> h0 = BadugiHand.from_game('2s3s4d7h')
>>> h1 = BadugiHand('2s4d7h')
>>> h0 == h1
True
>>> h0 = BadugiHand.from_game('KcKdKhKs')
>>> h1 = BadugiHand('Ks')
>>> h0 == h1
True
>>> h0 = BadugiHand.from_game('Ac2c3c4c')
>>> h1 = BadugiHand('Ac')
>>> h0 == h1
True

>>> h0 = BadugiHand.from_game('AcAdAhAs')
>>> h1 = BadugiHand('As')
>>> h0 == h1
True
>>> h0 = StandardBadugiHand.from_game('Ac2c3c4c')
>>> h1 = StandardBadugiHand('2c')
>>> h0 == h1
True

>>> h0 = StandardBadugiHand.from_game('2s3d3c4d')
>>> h1 = StandardBadugiHand.from_game('2s3c3d4d')
>>> h0 == h1
True

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

lookup: ClassVar[Lookup] = BadugiLookup(): The hand lookup.

low: ClassVar[bool] = True: The low status.

class pokerkit.hands.BoardCombinationHand(cards: Iterable[Card] | Card | str)

Bases: CombinationHand, ABC

The abstract base class for board-combination hands.

board_card_count: ClassVar[int]: The number of board cards.

classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

>>> h0 = GreekHoldemHand.from_game('Ac2d', 'QdJdTh2sKs')
>>> h1 = GreekHoldemHand('2s2dAcKsQd')
>>> h0 == h1
True
>>> h0 = GreekHoldemHand.from_game('AsKs', 'QdJdTh2s2d')
>>> h1 = GreekHoldemHand('AsKsQdJdTh')
>>> h0 == h1
True
>>> h0 = GreekHoldemHand.from_game('Ac9c', 'AhKhQhJhTh')
>>> h1 = GreekHoldemHand('AcAhKhQh9c')
>>> h0 == h1
True

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

class pokerkit.hands.CombinationHand(cards: Iterable[Card] | Card | str)

Bases: Hand, ABC

The abstract base class for combination hands.

Here, the hands are formed by combining hole cards and board cards in whatever way possible.

card_count: ClassVar[int]: The number of cards.

classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

>>> h0 = StandardHighHand.from_game('AcAdAhAsKc')
>>> h1 = StandardHighHand('AcAdAhAsKc')
>>> h0 == h1
True
>>> h0 = StandardHighHand.from_game('Ac9c', 'AhKhQhJhTh')
>>> h1 = StandardHighHand('AhKhQhJhTh')
>>> h0 == h1
True

>>> h0 = StandardLowHand.from_game('AcAdAhAsKc', '')
>>> h1 = StandardLowHand('AcAdAhAsKc')
>>> h0 == h1
True
>>> h0 = StandardLowHand.from_game('Ac9c', 'AhKhQhJhTh')
>>> h1 = StandardLowHand('AcQhJhTh9c')
>>> h0 == h1
True

>>> h0 = ShortDeckHoldemHand.from_game('AcKs', 'AhAsKcJsTs')
>>> h1 = ShortDeckHoldemHand('AcAhAsKcKs')
>>> h0 == h1
True
>>> h0 = ShortDeckHoldemHand.from_game('AcAd', '6s7cKcKd')
>>> h1 = ShortDeckHoldemHand('AcAdKcKd7c')
>>> h0 == h1
True

>>> h0 = EightOrBetterLowHand.from_game('As2s', '2c3c4c5c6c')
>>> h1 = EightOrBetterLowHand('Ad2d3d4d5d')
>>> h0 == h1
True

>>> h0 = RegularLowHand.from_game('AcAd', 'AhAsKcQdQh')
>>> h1 = RegularLowHand('AcAsQdQhKc')
>>> h0 == h1
True
>>> h0 = RegularLowHand.from_game('AcAd', 'AhAsKcQd')
>>> h1 = RegularLowHand('AdAhAsKcQd')
>>> h0 == h1
True

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

class pokerkit.hands.EightOrBetterLowHand(cards: Iterable[Card] | Card | str)

Bases: CombinationHand

The class for eight or better low hands.

>>> h0 = EightOrBetterLowHand('8c7d6h4s2c')
>>> h1 = EightOrBetterLowHand('7c5d4h3s2c')
>>> h2 = EightOrBetterLowHand('5d4h3s2dAd')
>>> h0 < h1 < h2
True

>>> h = EightOrBetterLowHand('AcAsAd2s4s')  
Traceback (most recent call last):
    ...
ValueError: The cards 'AcAsAd2s4s' form an invalid EightOrBetterLowHand ...
>>> h = EightOrBetterLowHand('TsJsQsKsAs')  
Traceback (most recent call last):
    ...
ValueError: The cards 'TsJsQsKsAs' form an invalid EightOrBetterLowHand ...
>>> h = EightOrBetterLowHand('4c5dThJsAcKh2h')  
Traceback (most recent call last):
    ...
ValueError: The cards '4c5dThJsAcKh2h' form an invalid EightOrBetterLowH...
>>> h = EightOrBetterLowHand('Ac2c3c4c')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2c3c4c' form an invalid EightOrBetterLowHand hand.
>>> h = EightOrBetterLowHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid EightOrBetterLowHand hand.

card_count: ClassVar[int] = 5: The number of cards.

lookup: ClassVar[Lookup] = EightOrBetterLookup(): The hand lookup.

low: ClassVar[bool] = True: The low status.

class pokerkit.hands.GreekHoldemHand(cards: Iterable[Card] | Card | str)

Bases: BoardCombinationHand

The class for Greek hold’em hands.

In Greek hold’em, the player must use all of their hole cards to make a hand.

>>> h0 = GreekHoldemHand('7c5d4h3s2c')
>>> h1 = GreekHoldemHand('7c6d4h3s2c')
>>> h2 = GreekHoldemHand('8c7d6h4s2c')
>>> h3 = GreekHoldemHand('AcAsAd2s4s')
>>> h4 = GreekHoldemHand('TsJsQsKsAs')
>>> h0 < h1 < h2 < h3 < h4
True

board_card_count: ClassVar[int] = 3: The number of board cards.

card_count: ClassVar[int] = 5: The number of cards.

lookup: ClassVar[Lookup] = StandardLookup(): The hand lookup.

low: ClassVar[bool] = False: The low status.

class pokerkit.hands.Hand(cards: Iterable[Card] | Card | str)

Bases: Hashable, ABC

The abstract base class for poker hands.

Stronger hands are considered greater than weaker hands.

>>> h0 = ShortDeckHoldemHand('6s7s8s9sTs')
>>> h1 = ShortDeckHoldemHand('7c8c9cTcJc')
>>> h2 = ShortDeckHoldemHand('2c2d2h2s3h')  
Traceback (most recent call last):
    ...
ValueError: The cards '2c2d2h2s3h' form an invalid ShortDeckHoldemHand h...
>>> h0
6s7s8s9sTs
>>> h1
7c8c9cTcJc
>>> print(h0)
Straight flush (6s7s8s9sTs)
>>> h0 < h1
True

It does not make sense to compare hands of different types.

>>> h3 = BadugiHand('6d7s8h9c')
>>> h3 < h0  
Traceback (most recent call last):
    ...
TypeError: '<' not supported between instances of 'BadugiHand' and 'Shor...
>>> h3 < 500
Traceback (most recent call last):
    ...
TypeError: '<' not supported between instances of 'BadugiHand' and 'int'

The hands are immutable and hence hashable.

>>> h0 = ShortDeckHoldemHand('6s7s8s9sTs')
>>> h1 = ShortDeckHoldemHand('7c8c9cTcJc')
>>> hands = {h0, h1}

Parameters:: cards – The cards that form the hand.
Raises:: ValueError – If the cards form an invalid hand.

property cards: tuple[Card, ...]

Return the cards that form this hand.

>>> hole = 'AsAc'
>>> board = 'Kh3sAdAh'
>>> hand = StandardHighHand.from_game(hole, board)
>>> hand.cards
(As, Ac, Kh, Ad, Ah)

Returns:: The cards that form this hand.

property entry: Entry

Return the hand entry.

>>> hole = 'AsAc'
>>> board = 'Kh3sAdAh'
>>> hand = StandardHighHand.from_game(hole, board)
>>> hand.entry.label
<Label.FOUR_OF_A_KIND: 'Four of a kind'>

Returns:: The hand entry.

abstract classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

Raises:

ValueError – If no valid hand can be formed.

Create a poker hand from a game setting or return None if no valid hand can be formed.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations, or None if no valid hand can be formed.

lookup: ClassVar[Lookup]: The hand lookup.

low: ClassVar[bool]: The low status.

class pokerkit.hands.HoleBoardCombinationHand(cards: Iterable[Card] | Card | str)

Bases: BoardCombinationHand, ABC

The abstract base class for hole-board-combination hands.

Here, the hands are formed by combining a specific number of hole cards and board cards.

classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

>>> h0 = OmahaHoldemHand.from_game('6c7c8c9c', '8s9sTc')
>>> h1 = OmahaHoldemHand('6c7c8s9sTc')
>>> h0 == h1
True
>>> h0 = OmahaHoldemHand.from_game('6c7c8s9s', '8c9cTc')
>>> h1 = OmahaHoldemHand('6c7c8c9cTc')
>>> h0 == h1
True
>>> h0 = OmahaHoldemHand.from_game('6c7c8c9c', '8s9sTc9hKs')
>>> h1 = OmahaHoldemHand('8c8s9c9s9h')
>>> h0 == h1
True
>>> h0 = OmahaHoldemHand.from_game('6c7c8sAh', 'As9cTc2sKs')
>>> h1 = OmahaHoldemHand('AhAsKsTc8s')
>>> h0 == h1
True

>>> h0 = OmahaEightOrBetterLowHand.from_game('As2s3s4s', '2c3c4c5c6c')
>>> h1 = OmahaEightOrBetterLowHand('Ad2d3d4d5d')
>>> h0 == h1
True
>>> h0 = OmahaEightOrBetterLowHand.from_game('As6s7s8s', '2c3c4c5c6c')
>>> h1 = OmahaEightOrBetterLowHand('Ad2d3d4d6d')
>>> h0 == h1
True

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

hole_card_count: ClassVar[int]: The number of hole cards.

class pokerkit.hands.KuhnPokerHand(cards: Iterable[Card] | Card | str)

Bases: Hand

The class for Kuhn poker hands.

>>> h0 = KuhnPokerHand('Js')
>>> h1 = KuhnPokerHand('Qs')
>>> h2 = KuhnPokerHand('Ks')
>>> h0 < h1 < h2
True

>>> h = KuhnPokerHand('As')
Traceback (most recent call last):
    ...
ValueError: The cards 'As' form an invalid KuhnPokerHand hand.

classmethod from_game(hole_cards: Iterable[Card] | Card | str, board_cards: Iterable[Card] | Card | str = ()) → Hand

Create a poker hand from a game setting.

In a game setting, a player uses private cards from their hole and the public cards from the board to make their hand.

>>> h0 = KuhnPokerHand.from_game('Ks')
>>> h1 = KuhnPokerHand('Ks')
>>> h0 == h1
True

Parameters:

hole_cards – The hole cards.
board_cards – The optional board cards.

Returns:

The strongest hand from possible card combinations.

lookup: ClassVar[Lookup] = KuhnPokerLookup(): The hand lookup.

low: ClassVar[bool] = False: The low status.

class pokerkit.hands.OmahaEightOrBetterLowHand(cards: Iterable[Card] | Card | str)

Bases: HoleBoardCombinationHand

The class for Omaha eight or better low hands.

>>> h0 = OmahaEightOrBetterLowHand('8c7d6h4s2c')
>>> h1 = OmahaEightOrBetterLowHand('7c5d4h3s2c')
>>> h2 = OmahaEightOrBetterLowHand('5d4h3s2dAd')
>>> h0 < h1 < h2
True

board_card_count: ClassVar[int] = 3: The number of board cards.

card_count: ClassVar[int] = 5: The number of cards.

hole_card_count: ClassVar[int] = 2: The number of hole cards.

lookup: ClassVar[Lookup] = EightOrBetterLookup(): The hand lookup.

low: ClassVar[bool] = True: The low status.

class pokerkit.hands.OmahaHoldemHand(cards: Iterable[Card] | Card | str)

Bases: HoleBoardCombinationHand

The class for Omaha hold’em hands.

In Omaha hold’em, the player must use a fixed number of their hole cards to make a hand.

>>> h0 = OmahaHoldemHand('7c5d4h3s2c')
>>> h1 = OmahaHoldemHand('7c6d4h3s2c')
>>> h2 = OmahaHoldemHand('8c7d6h4s2c')
>>> h3 = OmahaHoldemHand('AcAsAd2s4s')
>>> h4 = OmahaHoldemHand('TsJsQsKsAs')
>>> h0 < h1 < h2 < h3 < h4
True

board_card_count: ClassVar[int] = 3: The number of board cards.

card_count: ClassVar[int] = 5: The number of cards.

hole_card_count: ClassVar[int] = 2: The number of hole cards.

lookup: ClassVar[Lookup] = StandardLookup(): The hand lookup.

low: ClassVar[bool] = False: The low status.

class pokerkit.hands.RegularLowHand(cards: Iterable[Card] | Card | str)

Bases: CombinationHand

The class for low regular hands.

Here, flushes are ignored.

>>> h0 = RegularLowHand('KhKsKcKdAc')
>>> h1 = RegularLowHand('2s2c3s3cAh')
>>> h2 = RegularLowHand('6c4d3h2sAc')
>>> h3 = RegularLowHand('Ac2c3c4c5c')
>>> h0 < h1 < h2 < h3
True

>>> h = RegularLowHand('4c5dThJsAcKh2h')
Traceback (most recent call last):
    ...
ValueError: The cards '4c5dThJsAcKh2h' form an invalid RegularLowHand hand.
>>> h = RegularLowHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid RegularLowHand hand.

card_count: ClassVar[int] = 5: The number of cards.

lookup: ClassVar[Lookup] = RegularLookup(): The hand lookup.

low: ClassVar[bool] = True: The low status.

class pokerkit.hands.ShortDeckHoldemHand(cards: Iterable[Card] | Card | str)

Bases: CombinationHand

The class for short-deck hold’em hands.

Here, flushes beat full houses.

>>> h0 = ShortDeckHoldemHand('6c7d8h9sJc')
>>> h1 = ShortDeckHoldemHand('7c7d7hTsQc')
>>> h2 = ShortDeckHoldemHand('As6c7h8h9h')
>>> h3 = ShortDeckHoldemHand('AsAhKcKhKd')
>>> h4 = ShortDeckHoldemHand('6s7s8sTsQs')
>>> h0 < h1 < h2 < h3 < h4
True

>>> h = ShortDeckHoldemHand('4c5dThJsAcKh2h')  
Traceback (most recent call last):
    ...
ValueError: The cards '4c5dThJsAcKh2h' form an invalid ShortDeckHoldemHa...
>>> h = ShortDeckHoldemHand('Ac2c3c4c5c')  
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2c3c4c5c' form an invalid ShortDeckHoldemHand ...
>>> h = ShortDeckHoldemHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid ShortDeckHoldemHand hand.

card_count: ClassVar[int] = 5: The number of cards.

lookup: ClassVar[Lookup] = ShortDeckHoldemLookup(): The hand lookup.

low: ClassVar[bool] = False: The low status.

class pokerkit.hands.StandardBadugiHand(cards: Iterable[Card] | Card | str)

Bases: BadugiHand

The class for standard badugi hands (deuce-to-seven).

lookup: ClassVar[Lookup] = StandardBadugiLookup(): The hand lookup.

class pokerkit.hands.StandardHand(cards: Iterable[Card] | Card | str)

Bases: CombinationHand, ABC

The abstract base class for standard hands.

card_count: ClassVar[int] = 5: The number of cards.

lookup: ClassVar[Lookup] = StandardLookup(): The hand lookup.

class pokerkit.hands.StandardHighHand(cards: Iterable[Card] | Card | str)

Bases: StandardHand

The class for standard high hands.

>>> h0 = StandardHighHand('7c5d4h3s2c')
>>> h1 = StandardHighHand('7c6d4h3s2c')
>>> h2 = StandardHighHand('8c7d6h4s2c')
>>> h3 = StandardHighHand('AcAsAd2s4s')
>>> h4 = StandardHighHand('TsJsQsKsAs')
>>> h0 < h1 < h2 < h3 < h4
True

>>> h = StandardHighHand('4c5dThJsAcKh2h')  
Traceback (most recent call last):
    ...
ValueError: The cards '4c5dThJsAcKh2h' form an invalid StandardHighHand ...
>>> h = StandardHighHand('Ac2c3c4c')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2c3c4c' form an invalid StandardHighHand hand.
>>> h = StandardHighHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid StandardHighHand hand.

low: ClassVar[bool] = False: The low status.

class pokerkit.hands.StandardLowHand(cards: Iterable[Card] | Card | str)

Bases: StandardHand

The class for standard low hands.

>>> h0 = StandardLowHand('TsJsQsKsAs')
>>> h1 = StandardLowHand('AcAsAd2s4s')
>>> h2 = StandardLowHand('8c7d6h4s2c')
>>> h3 = StandardLowHand('7c6d4h3s2c')
>>> h4 = StandardLowHand('7c5d4h3s2c')
>>> h0 < h1 < h2 < h3 < h4
True

>>> h = StandardLowHand('4c5dThJsAcKh2h')  
Traceback (most recent call last):
    ...
ValueError: The cards '4c5dThJsAcKh2h' form an invalid StandardLowHand h...
>>> h = StandardLowHand('Ac2c3c4c')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ac2c3c4c' form an invalid StandardLowHand hand.
>>> h = StandardLowHand(())
Traceback (most recent call last):
    ...
ValueError: The cards () form an invalid StandardLowHand hand.

low: ClassVar[bool] = True: The low status.

pokerkit.lookups module

pokerkit.lookups implements classes related to poker hand lookups.

Lookups are used by PokerKit’s hand types to discern hand strengths.

class pokerkit.lookups.BadugiLookup

Bases: Lookup

The class for badugi hand lookups (ace-to-five).

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.BadugiHand.

>>> lookup = BadugiLookup()
>>> e0 = lookup.get_entry('2s')
>>> e1 = lookup.get_entry('KhQc')
>>> e2 = lookup.get_entry('AcAdAhAs')
Traceback (most recent call last):
    ...
ValueError: The cards 'AcAdAhAs' form an invalid hand.
>>> e0 > e1
True
>>> e0.label
<Label.HIGH_CARD: 'High card'>
>>> e1.label
<Label.HIGH_CARD: 'High card'>

rank_order: ClassVar[RankOrder] = (Rank.ACE, Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING): The rank order.

class pokerkit.lookups.EightOrBetterLookup

Bases: Lookup

The class for eight or better hand lookups.

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.EightOrBetterLowHand.

rank_order: ClassVar[RankOrder] = (Rank.ACE, Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT): The rank order.

class pokerkit.lookups.Entry(index: int, label: Label)

Bases: object

The class for hand lookup entries.

The index represents the strength of the corresponding hand. In this library, a stronger hand is considered greater. In other words, stronger hands have either a greater or less (depending on whether using a high/low hand) index with which different entries and hands are compared.

The attributes are read-only.

Note that the entries in the example below are meaningless. They are only meant to show how entries are used by other poker utilities.

>>> e0 = Entry(0, Label.HIGH_CARD)
>>> e1 = Entry(1, Label.HIGH_CARD)
>>> e2 = Entry(1, Label.HIGH_CARD)
>>> e0 < e1
True
>>> e1 < e2
False
>>> e0 == e1
False
>>> e1 == e2
True
>>> e0.index
0
>>> e0.label
<Label.HIGH_CARD: 'High card'>

Parameters:

index – The index of the entry.
label – The label of the hand.

index: int: The index of the corresponding hand.

label: Label: The label of the corresponding hand.

class pokerkit.lookups.KuhnPokerLookup

Bases: Lookup

The class for Kuhn poker hand lookups.

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.KuhnPokerHand.

>>> lookup = KuhnPokerLookup()
>>> e0 = lookup.get_entry('J?')
>>> e1 = lookup.get_entry('Q?')
>>> e2 = lookup.get_entry('2?')
Traceback (most recent call last):
    ...
ValueError: The cards '2?' form an invalid hand.
>>> e0 < e1
True
>>> e0.label
<Label.HIGH_CARD: 'High card'>
>>> e1.label
<Label.HIGH_CARD: 'High card'>

rank_order: ClassVar[RankOrder] = (Rank.JACK, Rank.QUEEN, Rank.KING): The rank order.

class pokerkit.lookups.Label(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for all hand classification labels.

The label describes the type of each hand.

>>> Label.ONE_PAIR
<Label.ONE_PAIR: 'One pair'>
>>> Label.FULL_HOUSE
<Label.FULL_HOUSE: 'Full house'>

FLUSH: str = 'Flush': The label of flush.

FOUR_OF_A_KIND: str = 'Four of a kind': The label of four of a kind.

FULL_HOUSE: str = 'Full house': The label of full house.

HIGH_CARD: str = 'High card': The label of high cards.

ONE_PAIR: str = 'One pair': The label of one pair.

STRAIGHT: str = 'Straight': The label of straight.

STRAIGHT_FLUSH: str = 'Straight flush': The label of straight flush.

THREE_OF_A_KIND: str = 'Three of a kind': The label of three of a kind.

TWO_PAIR: str = 'Two pair': The label of two pair.

class pokerkit.lookups.Lookup

Bases: ABC

The abstract base class for hand lookups.

Lookups are used internally by hands. If you want to evaluate poker hands, please use one of the hand classes.

>>> lookup = StandardLookup()
>>> e0 = lookup.get_entry('As3sQhJsJc')
>>> e1 = lookup.get_entry('2s4sKhKsKc')
>>> e0 < e1
True
>>> e0.label
<Label.ONE_PAIR: 'One pair'>
>>> e1.label
<Label.THREE_OF_A_KIND: 'Three of a kind'>

get_entry(cards: Iterable[Card] | Card | str) → Entry

Return the corresponding lookup entry of the hand that the cards form.

>>> lookup = ShortDeckHoldemLookup()
>>> entry = lookup.get_entry('Ah6h7s8c9s')
>>> entry.index
1128
>>> entry.label
<Label.STRAIGHT: 'Straight'>
>>> entry = lookup.get_entry('Ah6h7s8c2s')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ah6h7s8c2s' form an invalid hand.

Parameters:: cards – The cards to look up.
Returns:: The corresponding lookup entry.
Raises:: ValueError – If cards do not form a valid hand.

get_entry_or_none(cards: Iterable[Card] | Card | str) → Entry | None

Return the corresponding lookup entry of the hand that the cards form if it exists. Otherwise, return None.

>>> lookup = ShortDeckHoldemLookup()
>>> lookup.get_entry('Ah6h7s8c2s')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ah6h7s8c2s' form an invalid hand.
>>> lookup.get_entry_or_none('Ah6h7s8c2s') is None
True

Parameters:: cards – The cards to look up.
Returns:: The optional corresponding lookup entry.

has_entry(cards: Iterable[Card] | Card | str) → bool

Return whether the cards can be looked up.

The cards can be looked up if the lookup contains an entry with the given cards.

>>> lookup = ShortDeckHoldemLookup()
>>> lookup.has_entry('Ah6h7s8c9s')
True
>>> lookup.has_entry('Ah6h7s8c2s')
False

Parameters:: cards – The cards to look up.
Returns:: True if the cards can looked up, otherwise False.

rank_order: ClassVar[RankOrder]: The rank order.

class pokerkit.lookups.RegularLookup

Bases: Lookup

The class for regular hand lookups.

Here, flushes are ignored.

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.RegularLowHand.

>>> lookup = RegularLookup()
>>> e0 = lookup.get_entry('Ah6h7s8c9s')
>>> e1 = lookup.get_entry('AhAc6s6hTd')
>>> e2 = lookup.get_entry('3s4sQhTc')
Traceback (most recent call last):
    ...
ValueError: The cards '3s4sQhTc' form an invalid hand.
>>> e0 < e1
True
>>> e0.label
<Label.HIGH_CARD: 'High card'>
>>> e1.label
<Label.TWO_PAIR: 'Two pair'>

rank_order: ClassVar[RankOrder] = (Rank.ACE, Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING): The rank order.

class pokerkit.lookups.ShortDeckHoldemLookup

Bases: Lookup

The class for short-deck hold’em hand lookups.

Here, flushes beat full houses.

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.ShortDeckHoldemHand.

>>> lookup = ShortDeckHoldemLookup()
>>> e0 = lookup.get_entry('AhAc6s6hTd')
>>> e1 = lookup.get_entry('Ah6h7s8c9s')
>>> e2 = lookup.get_entry('Ah2h3s4c5s')
Traceback (most recent call last):
    ...
ValueError: The cards 'Ah2h3s4c5s' form an invalid hand.
>>> e0 < e1
True
>>> e0.label
<Label.TWO_PAIR: 'Two pair'>
>>> e1.label
<Label.STRAIGHT: 'Straight'>

rank_order: ClassVar[RankOrder] = (Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The rank order.

class pokerkit.lookups.StandardBadugiLookup

Bases: BadugiLookup

The class for standard badugi hand lookups (deuce-to-seven).

Lookups are used by evaluators. If you want to evaluate poker hands, please use pokerkit.hands.StandardBadugiHand.

rank_order: ClassVar[RankOrder] = (Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The rank order.

class pokerkit.lookups.StandardLookup

Bases: Lookup

The class for standard hand lookups.

Lookups are used by evaluators. If you want to evaluate poker hands, please subclasses of pokerkit.hands.Hand that use this lookup.

>>> lookup = StandardLookup()
>>> e0 = lookup.get_entry('Ah6h7s8c9s')
>>> e1 = lookup.get_entry('AhAc6s6hTd')
>>> e2 = lookup.get_entry('AcAdAhAsAc')
Traceback (most recent call last):
    ...
ValueError: The cards 'AcAdAhAsAc' form an invalid hand.
>>> e0 < e1
True
>>> e0.label
<Label.HIGH_CARD: 'High card'>
>>> e1.label
<Label.TWO_PAIR: 'Two pair'>

rank_order: ClassVar[RankOrder] = (Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The rank order.

pokerkit.notation module

pokerkit.notation implements classes related to poker notations.

class pokerkit.notation.ACPCProtocolParser(game: Poker, starting_stack: int)

Bases: Parser

A class for ACPC Protocol hand history parser.

AUTOMATIONS: ClassVar[tuple[Automation, ...]] = (Automation.ANTE_POSTING, Automation.BET_COLLECTION, Automation.BLIND_OR_STRADDLE_POSTING, Automation.HOLE_CARDS_SHOWING_OR_MUCKING, Automation.RUNOUT_COUNT_SELECTION, Automation.HAND_KILLING, Automation.CHIPS_PUSHING, Automation.CHIPS_PULLING): The automations for the game being simulated.

BETTING_OR_RAISING_TO: ClassVar[Pattern[str]] = re.compile('r(?P<amount>\\d*)'): The betting or raising_to pattern.

BLIND_POSTING: ClassVar[Pattern[str]] = re.compile('b(?P<blind>\\d+)'): The blind-posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('/'): The board-dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('c(?P<amount>\\d*)'): The checking or calling pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('f'): The folding pattern.

HAND: ClassVar[tuple[Pattern[str], ...]] = (re.compile('^(?P<players>[^:\\n]+):(?P<hand>\\d+):(?P<actions>[^:\\n]+):(?P<cards>[^:\\n]+):(?P<results>[^:\\n]+)$', re.MULTILINE), re.compile('^STATE:(?P<hand>\\d+):(?P<actions>[^:\\n]+):(?P<cards>[^:\\n]+):(?P<results>[^:\\n]+):(?P<players>[^:\\n]+)$', re.MULTILINE)): The hand patterns.

game: Poker: The game being played.

starting_stack: int: The starting stacks.

class pokerkit.notation.AbsolutePokerParser

Bases: REParser

A class for Absolute Poker hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - Ante \\D?(?P<ante>[0-9.,]+)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - Posts (small|big) blind \\D?(?P<blind_or_straddle>[0-9.,]+)'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('\\*\\*\\*( (FLOP) \\*\\*\\*| (TURN|RIVER) \\*\\*\\* \\[[0-9TJQKAcdhs ]+\\]) \\[(?P<cards>[0-9TJQKAcdhs ]+)\\]'): Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - C(all|heck)s'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - (Bets|Raises|All-In(\$Raise\$)?) \\D?(?P<amount>[0-9.,]+)'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'Absolute Poker'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \$(?P<time_zone_abbreviation>\\S+)\$'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile(' Seat #(?P<final_seat>\\d+) is the( dead)? dealer'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - Folds'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^Stage #.+?(?=^\\n{2,})', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) - Shows \\[(?P<cards>[0-9TJQKAcdhs ]+)\\]'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('(?!)'): Hole dealing pattern.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'winnings': (re.compile('Seat \\d+: (?P<player>.+?)( \$\\D+\$)? collected Total \$\\D?(?P<winnings>[0-9.,]+)\$'), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('Seat (?P<seat>\\d+) - (?P<player>.+) \$\\D?[0-9.,]+ in chips\$'): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('Seat \\d+ - (?P<player>.+) \$\\D?(?P<starting_stack>[0-9.,]+) in chips\$'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency_symbol': (re.compile('\$(?P<currency_symbol>\\D?)[0-9.,]+ in chips\$'), <class 'str'>), 'day': (re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \$(?P<time_zone_abbreviation>\\S+)\$'), <class 'int'>), 'hand': (re.compile('Stage #(?P<hand>\\d+):'), <class 'int'>), 'month': (re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \$(?P<time_zone_abbreviation>\\S+)\$'), <class 'int'>), 'seat_count': (re.compile('\$(?P<seat_count>\\d+) max\$'), <class 'int'>), 'table': (re.compile('Table: (?P<table>.+?) \$'), <class 'str'>), 'time': (re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \\((?P<time_zone_abbreviation>\\S+)\$'), <function parse_time>), 'time_zone_abbreviation': (re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \$(?P<time_zone_abbreviation>\\S+)\$'), <class 'str'>), 'year': (re.compile(' - (?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) \$(?P<time_zone_abbreviation>\\S+)\$'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile(': (?P<variant>Holdem( \$1 on 1\$)? No Limit) '): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {'Holdem No Limit': 'NT', 'Holdem (1 on 1) No Limit': 'NT'}: Variant conversion lookup.

class pokerkit.notation.FullTiltPokerParser

Bases: REParser

A class for Full Tilt Poker hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?!)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) posts the (small|big) blind of \\D?(?P<blind_or_straddle>[0-9.,]+)'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('\\*\\*\\*( (FLOP) \\*\\*\\*| (TURN|RIVER) \\*\\*\\* \\[[1-9TJQKAcdhs ]+\\]) \\[(?P<cards>[1-9TJQKAcdhs ]+)\\]'): Board dealing pattern.

CAP: ClassVar[Pattern[str]] = re.compile(' \\D?(?P<cap>[0-9.,]+) Cap ')

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) c(all|heck)s'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) (bets|raises to) \\D?(?P<amount>[0-9.,]+)'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'Full Tilt Poker'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile('The button is in seat #(?P<final_seat>\\d+)'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) folds'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^Full Tilt Poker Game #.+?(?=^\\n{2,})', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) shows \\[(?P<cards>[1-9TJQKAcdhs ]+)\\]'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('(?!)'): Hole dealing pattern.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'winnings': (re.compile('Seat \\d+: (?P<player>.+) collected \$\\D?(?P<winnings>[0-9.,]+)\$'), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('Seat (?P<seat>\\d+): (?P<player>.+) \\('): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('Seat \\d+: (?P<player>.+) \$\\D?(?P<starting_stack>[0-9.,]+)\$'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency_symbol': (re.compile('\$(?P<currency_symbol>\\D?)[0-9.,]+\$'), <class 'str'>), 'day': (re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'), <class 'int'>), 'hand': (re.compile('Full Tilt Poker Game #(?P<hand>\\d+):'), <class 'int'>), 'month': (re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'), <class 'int'>), 'seat_count': (re.compile('\$(?P<seat_count>\\d+) max\$'), <class 'int'>), 'table': (re.compile('Table (?P<table>.+?) '), <class 'str'>), 'time': (re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'), <function parse_time>), 'time_zone_abbreviation': (re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'), <class 'str'>), 'year': (re.compile(' - (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+)'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile(" - (\\D?\\d+ Cap )?(?P<variant>No Limit Hold'em) - "): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {"No Limit Hold'em": 'NT'}: Variant conversion lookup.

class pokerkit.notation.HandHistory(*, variant: str, ante_trimming_status: bool = False, antes: list[int], blinds_or_straddles: list[int] | None = None, bring_in: int | None = None, small_bet: int | None = None, big_bet: int | None = None, min_bet: int | None = None, starting_stacks: list[int], actions: list[str], author: str | None = None, event: str | None = None, url: str | None = None, venue: str | None = None, address: str | None = None, city: str | None = None, region: str | None = None, postal_code: str | None = None, country: str | None = None, time: ~datetime.time | None = None, time_zone: str | None = None, day: int | None = None, month: int | None = None, year: int | None = None, hand: str | int | None = None, level: int | None = None, seats: list[int] | None = None, seat_count: int | None = None, table: str | int | None = None, players: list[str] | None = None, finishing_stacks: list[int] | None = None, winnings: list[int] | None = None, currency: str | None = None, currency_symbol: str | None = None, time_limit: int | None = None, time_banks: list[int] | None = None, user_defined_fields: dict[str, ~typing.Any] = <factory>, automations: tuple[~pokerkit.state.Automation, ...] = (Automation.ANTE_POSTING, Automation.BET_COLLECTION, Automation.BLIND_OR_STRADDLE_POSTING, Automation.CARD_BURNING, Automation.RUNOUT_COUNT_SELECTION, Automation.HAND_KILLING, Automation.CHIPS_PUSHING, Automation.CHIPS_PULLING), divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, percentage=0), parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>)

Bases: Iterable[State]

The class for hand histories.

Parameters:

variant – The variant name. For more information, please refer to pokerkit.notation.HandHistory.variant.
ante_trimming_status – The ante trimming status. For more information, please refer to pokerkit.notation.HandHistory.ante_trimming_status.
antes – The antes. For more information, please refer to pokerkit.notation.HandHistory.antes.
blinds_or_straddles – The blinds or straddles. For more information, please refer to pokerkit.notation.HandHistory.blinds_or_straddles.
bring_in – The bring-in. For more information, please refer to pokerkit.notation.HandHistory.bring_in.
small_bet – The small bet. For more information, please refer to pokerkit.notation.HandHistory.small_bet.
big_bet – The big bet. For more information, please refer to pokerkit.notation.HandHistory.big_bet.
min_bet – The minimum bet. For more information, please refer to pokerkit.notation.HandHistory.min_bet.
starting_stacks – The starting stacks. For more information, please refer to pokerkit.notation.HandHistory.starting_stacks.
actions – The actions. For more information, please refer to pokerkit.notation.HandHistory.actions.
author – The author. For more information, please refer to pokerkit.notation.HandHistory.author.
event – The event. For more information, please refer to pokerkit.notation.HandHistory.event.
url – The url. For more information, please refer to pokerkit.notation.HandHistory.url.
venue – The venue. For more information, please refer to pokerkit.notation.HandHistory.venue.
address – The address. For more information, please refer to pokerkit.notation.HandHistory.address.
city – The city. For more information, please refer to pokerkit.notation.HandHistory.city.
region – The region. For more information, please refer to pokerkit.notation.HandHistory.region.
postal_code – The postal code. For more information, please refer to pokerkit.notation.HandHistory.postal_code.
country – The country. For more information, please refer to pokerkit.notation.HandHistory.country.
time – The time. For more information, please refer to pokerkit.notation.HandHistory.time.
time_zone – The time zone. For more information, please refer to pokerkit.notation.HandHistory.time_zone.
day – The day. For more information, please refer to pokerkit.notation.HandHistory.day.
month – The month. For more information, please refer to pokerkit.notation.HandHistory.month.
year – The year. For more information, please refer to pokerkit.notation.HandHistory.year.
hand – The hand name or number. For more information, please refer to pokerkit.notation.HandHistory.hand.
level – The level. For more information, please refer to pokerkit.notation.HandHistory.level.
seats – The seat numbers. For more information, please refer to pokerkit.notation.HandHistory.seats.
seat_count – The number of seats. For more information, please refer to pokerkit.notation.HandHistory.seat_count.
table – The table number. For more information, please refer to pokerkit.notation.HandHistory.table.
players – The player names. For more information, please refer to pokerkit.notation.HandHistory.players.
finishing_stacks – The finishing stacks. For more information, please refer to pokerkit.notation.HandHistory.finishing_stacks.
winnings – The winnings. For more information, please refer to pokerkit.notation.HandHistory.winnings.
currency – The currency. For more information, please refer to pokerkit.notation.HandHistory.currency.
currency_symbol – The currency symbol. For more information, please refer to pokerkit.notation.HandHistory.currency_symbol.
time_limit – The time limit. For more information, please refer to pokerkit.notation.HandHistory.time_limit.
time_banks – The time banks. For more information, please refer to pokerkit.notation.HandHistory.time_banks.
user_defined_fields – The user-defined fields. For more information, please refer to pokerkit.notation.HandHistory.user_defined_fields.
automations – The automations. For more information, please refer to pokerkit.notation.HandHistory.automations.
divmod – The divmod function. For more information, please refer to pokerkit.notation.HandHistory.divmod.
rake – The rake function. For more information, please refer to pokerkit.notation.HandHistory.rake.
parse_value – The value parsing function. For more information, please refer to pokerkit.notation.HandHistory.parse_value.

ACPC_PROTOCOL_VARIANTS: ClassVar[set[str]] = {'FT', 'NT'}: The variant codes supported by the ACPC protocol.

PLURIBUS_PROTOCOL_VARIANTS: ClassVar[set[str]] = {'NT'}: The variant codes supported by the Pluribus protocol.

actions: list[str]: The actions.

address: str | None = None: The address.

ante_trimming_status: bool = False: The ante trimming status.

antes: list[int]: The antes.

author: str | None = None: The author.

automations: tuple[Automation, ...] = (Automation.ANTE_POSTING, Automation.BET_COLLECTION, Automation.BLIND_OR_STRADDLE_POSTING, Automation.CARD_BURNING, Automation.RUNOUT_COUNT_SELECTION, Automation.HAND_KILLING, Automation.CHIPS_PUSHING, Automation.CHIPS_PULLING): The automations.

big_bet: int | None = None: The big bet.

blinds_or_straddles: list[int] | None = None: The blinds or straddles.

bring_in: int | None = None: The bring-in.

city: str | None = None: The city.

country: str | None = None: The country.

create_game() → Poker

Create the game.

Returns:: The game.

create_state() → State

Create the initial state.

Returns:: The initial state.

currency: str | None = None: The currency.

currency_symbol: str | None = None: The currency symbol.

day: int | None = None: The day.

divmod(divisor: int) → tuple[int, int]: The divmod function.

dump(fp: BinaryIO) → None

Dump PHH to a file pointer.

Parameters:: fp – The file pointer.
Returns:: None.

classmethod dump_all(phhs: Iterable[HandHistory], fp: BinaryIO) → None

Dump PHH to a file pointer.

Parameters:: fp – The file pointer.
Returns:: None.

dumps() → str

Dump PHH as a str object.

Returns:: a str object.

classmethod dumps_all(phhs: Iterable[HandHistory]) → str

Dump PHHs as a str object.

Returns:: a str object.

event: str | None = None: The event.

finishing_stacks: list[int] | None = None: The finishing stacks.

classmethod from_absolute_poker(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from Absolute Poker.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_acpc_protocol(game: ~pokerkit.games.Poker, starting_stack: int, s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs in ACPC Protocol.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_full_tilt_poker(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from Full Tilt Poker.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_game_state(game: Poker, state: State, compression_status: bool = True, **kwargs: Any) → HandHistory

Create a hand history from game state.

Parameters:

game – The game.
state – The state.
compression_status – The compression status.
kwargs – The metadata.

Returns:

The hand history.

classmethod from_ipoker_network(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from iPoker Network.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_ongame_network(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from Ongame Network.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_partypoker(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from PartyPoker.

If an error is encountered, an error is raised. The error can be disabled by setting error_status to be True. Then, errors will be warned.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to skip errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

classmethod from_pokerstars(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, error_status: bool = False) → Generator[HandHistory, None, int]

Parse hand history logs from PokerStars.

If an error is encountered, an error is raised if error_status is passed as True (by default, it is False). If False, only warnings are shown.

Parameters:

s – The hand history logs.
parse_value – The value parser.
error_status – Set True to raise errors, otherwise False.

Returns:

The generator that iterates yields hand histories and returns the total number of hands parsed.

property game_type: type[Poker]

Return the game type.

Returns:: The game type.

game_types: ClassVar[dict[str, type[Poker]]] = {'F2L3D': <class 'pokerkit.games.FixedLimitDeuceToSevenLowballTripleDraw'>, 'F7S': <class 'pokerkit.games.FixedLimitSevenCardStud'>, 'F7S/8': <class 'pokerkit.games.FixedLimitSevenCardStudHighLowSplitEightOrBetter'>, 'FB': <class 'pokerkit.games.FixedLimitBadugi'>, 'FO/8': <class 'pokerkit.games.FixedLimitOmahaHoldemHighLowSplitEightOrBetter'>, 'FR': <class 'pokerkit.games.FixedLimitRazz'>, 'FT': <class 'pokerkit.games.FixedLimitTexasHoldem'>, 'N2L1D': <class 'pokerkit.games.NoLimitDeuceToSevenLowballSingleDraw'>, 'NS': <class 'pokerkit.games.NoLimitShortDeckHoldem'>, 'NT': <class 'pokerkit.games.NoLimitTexasHoldem'>, 'PO': <class 'pokerkit.games.PotLimitOmahaHoldem'>}: The game codes and the corresponding game types.

hand: str | int | None = None: The hand name or number.

level: int | None = None: The level.

classmethod load(fp: BinaryIO, **kwargs: Any) → HandHistory

Load PHH from a file pointer.

Parameters:

fp – The file pointer.
kwargs – The metadata.

Returns:

The hand history object.

classmethod load_all(fp: BinaryIO, **kwargs: Any) → Iterator[HandHistory]

Load PHHs from a file pointer.

Parameters:

fp – The file pointer.
kwargs – The metadata.

Returns:

The hand history object.

classmethod loads(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, **kwargs: ~typing.Any) → HandHistory

Load PHH from a str object.

Parameters:

s – The str object.
parse_value – The value parsing function.
kwargs – The metadata.

Returns:

The hand history object.

classmethod loads_all(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, **kwargs: ~typing.Any) → Iterator[HandHistory]

Load PHHs from a str object.

Parameters:

s – The str object.
parse_value – The value parsing function.
kwargs – The metadata.

Returns:

The hand history object.

min_bet: int | None = None: The minimum bet.

month: int | None = None: The month.

optional_field_names: ClassVar[tuple[str, ...]] = ('author', 'event', 'url', 'venue', 'address', 'city', 'region', 'postal_code', 'country', 'time', 'time_zone', 'day', 'month', 'year', 'hand', 'level', 'seats', 'seat_count', 'table', 'players', 'finishing_stacks', 'winnings', 'currency', 'currency_symbol', 'ante_trimming_status', 'time_limit', 'time_banks'): The optional field names.

parse_value() → int: The value parsing function.

players: list[str] | None = None: The player names.

postal_code: str | None = None: The postal code.

rake(state: State | None = None, *, percentage: float = 0, cap: float = inf, no_flop_no_drop: bool = False) → tuple[int, int]: The rake function.

region: str | None = None: The region.

required_field_names: ClassVar[dict[str, tuple[str, ...]]] = {'F2L3D': ('variant', 'antes', 'blinds_or_straddles', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'F7S': ('variant', 'antes', 'bring_in', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'F7S/8': ('variant', 'antes', 'bring_in', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'FB': ('variant', 'antes', 'blinds_or_straddles', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'FO/8': ('variant', 'antes', 'blinds_or_straddles', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'FR': ('variant', 'antes', 'bring_in', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'FT': ('variant', 'antes', 'blinds_or_straddles', 'small_bet', 'big_bet', 'starting_stacks', 'actions'), 'N2L1D': ('variant', 'antes', 'blinds_or_straddles', 'min_bet', 'starting_stacks', 'actions'), 'NS': ('variant', 'antes', 'blinds_or_straddles', 'min_bet', 'starting_stacks', 'actions'), 'NT': ('variant', 'antes', 'blinds_or_straddles', 'min_bet', 'starting_stacks', 'actions'), 'PO': ('variant', 'antes', 'blinds_or_straddles', 'min_bet', 'starting_stacks', 'actions')}: The required field names.

seat_count: int | None = None: The number of seats.

seats: list[int] | None = None: The seat numbers.

small_bet: int | None = None: The small bet.

starting_stacks: list[int]: The starting stacks.

property state_actions: Iterator[tuple[State, str | None]]

Iterate through state-actions.

If an action from the pokerkit.notation.HandHistory.actions field was just applied, the str representation of the action is yielded alongside the newly transitioned state. Otherwise, the corresponding second value of the pair is None.

Returns:: The state actions.

table: str | int | None = None: The table name or number.

time: time | None = None: The time.

time_banks: list[int] | None = None: The time banks.

time_limit: int | None = None: The time limit.

time_zone: str | None = None: The time zone.

to_acpc_protocol(position: int, hand_number: int | None = None) → Iterator[tuple[str, str]]

Convert to the ACPC protocol.

Only the fixed-limit/no-limit Texas hold’em variants are supported.

Parameters:

position – The client position.
hand_number – The optional hand number. If None, it is inferred from the field.

Returns:

The hand histories in the ACPC protocol.

Raises:

ValueError – If the game is not supported or the hand number cannot be determined.

to_pluribus_protocol(hand_number: int | None = None) → str

Convert to the Pluribus protocol.

Only the no-limit Texas hold’em variant is supported.

Parameters:: hand_number – The optional hand number. If None, it is inferred from the field.
Returns:: The hand histories in the Pluribus protocol.
Raises:: ValueError – If the game is not supported or the hand number cannot be determined.

url: str | None = None: The url.

user_defined_fields: dict[str, Any]: The user-defined fields.

variant: str: The variant name.

variants: ClassVar[dict[type[Poker], str]] = {<class 'pokerkit.games.FixedLimitBadugi'>: 'FB', <class 'pokerkit.games.FixedLimitDeuceToSevenLowballTripleDraw'>: 'F2L3D', <class 'pokerkit.games.FixedLimitOmahaHoldemHighLowSplitEightOrBetter'>: 'FO/8', <class 'pokerkit.games.FixedLimitRazz'>: 'FR', <class 'pokerkit.games.FixedLimitSevenCardStud'>: 'F7S', <class 'pokerkit.games.FixedLimitSevenCardStudHighLowSplitEightOrBetter'>: 'F7S/8', <class 'pokerkit.games.FixedLimitTexasHoldem'>: 'FT', <class 'pokerkit.games.NoLimitDeuceToSevenLowballSingleDraw'>: 'N2L1D', <class 'pokerkit.games.NoLimitShortDeckHoldem'>: 'NS', <class 'pokerkit.games.NoLimitTexasHoldem'>: 'NT', <class 'pokerkit.games.PotLimitOmahaHoldem'>: 'PO'}: The game types and the corresponding game codes.

venue: str | None = None: The venue.

winnings: list[int] | None = None: The winnings.

year: int | None = None: The year.

class pokerkit.notation.IPokerNetworkParser

Bases: REParser

A class for iPoker Network hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?!)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('<action.*\\bplayer="(?P<player>.+?)".*\\btype="(1|2)".*\\bsum="\\D?(?P<blind_or_straddle>[0-9.,]+)".*/>'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('<cards\\b.*\\btype="(Flop|Turn|River)".*>(?P<cards>[0-9TJQKAcdhs ]+)</cards>'): Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('<action\\b.*\\bplayer="(?P<player>.+?)".*\\btype="(3|4)".*/>'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('<action\\b.*\\bplayer="(?P<player>.+?)".*\\btype="(5|6|23)".*\\bsum="\\D?(?P<amount>[0-9.,]+)".*/>'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'iPoker Network'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile('<startdate>(?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2})</startdate>'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile('<player\\b.*\\bseat="(?P<final_seat>\\d+)".*\\bdealer="1".*/>'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('<action\\b.*\\bplayer="(?P<player>.+?)".*\\btype="0".*/>'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^<game gamecode=".+?</game>', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('(?!)'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('<cards\\b.*\\btype="Pocket".*\\bplayer="(?P<player>.+?)".*>(?P<cards>[0-9TJQKAcdhs ]+)</cards>'): Hole dealing pattern.

PLACEHOLDER_STARTING_STACK: ClassVar[int] = 10000000

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'winnings': (re.compile('<player\\b.*\\bname="(?P<player>.+)".*\\bwin="\\D?(?P<winnings>[0-9.,]+)".*/>'), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('<player\\b.*\\bseat="(?P<seat>\\d+)".*\\bname="(?P<player>.+?)".*/>'): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('<player\\b.*\\bname="(?P<player>.+?)".*\\bchips="\\D?(?P<starting_stack>[0-9.,]+)".*\\bbet="\\D?(?P<bet>[0-9.,]+)".*/>'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency': (re.compile('<currency>(?P<currency>\\w+)</currency>'), <class 'str'>), 'currency_symbol': (re.compile('chips="(?P<currency_symbol>\\D?)[0-9.,]+"'), <class 'str'>), 'day': (re.compile('<startdate>(?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2})</startdate>'), <class 'int'>), 'hand': (re.compile('gamecode="(?P<hand>\\d+)"'), <class 'int'>), 'month': (re.compile('<startdate>(?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2})</startdate>'), <class 'int'>), 'table': (re.compile('<tablename>(?P<table>.+)</tablename>'), <class 'str'>), 'time': (re.compile('<startdate>(?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2})</startdate>'), <function parse_time>), 'year': (re.compile('<startdate>(?P<year>\\d+)-(?P<month>\\d+)-(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2})</startdate>'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile('(?P<variant>)'): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {'': 'NT'}: Variant conversion lookup.

class pokerkit.notation.OngameNetworkParser

Bases: REParser

A class for Ongame Network hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?!)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) posts (small|big) blind \$\\D?(?P<blind_or_straddle>[0-9.,]+)\$'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('--- Dealing (flop|turn|river) \\[(?P<cards>[1-9TJQKAcdhs ,]+)\\]'): Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) c(all|heck)s'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) (bet|raise)s \\D?(?P<amount>[0-9.,]+)'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'Ongame Network'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile('Button: seat (?P<final_seat>\\d+)'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) folds'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^\\*\\*\\*\\*\\* History for hand .+?(?=^\\n{2,})', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('Seat \\d+: (?P<player>.+) \$\\D?[0-9.,]+\$, net: (\\+|-)?\\D?[0-9.,]+, \\[(?P<cards>[1-9TJQKAcdhs ,]+)\\]'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('(?!)'): Hole dealing pattern.

MONTHS: ClassVar[dict[str, int]] = {'Apr': 4, 'Aug': 8, 'Dec': 12, 'Feb': 2, 'Jan': 1, 'Jul': 7, 'Jun': 6, 'Mar': 3, 'May': 5, 'Nov': 11, 'Oct': 10, 'Sep': 9}: Months as written in Ongame network hand logs.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'finishing_stacks': (re.compile('Seat \\d+: (?P<player>.+) \$\\D?(?P<finishing_stacks>[0-9.,]+)\$, net: (\\+|-)?\\D?[0-9.,]+'), None, <class 'int'>, <built-in function add>), 'winnings': (re.compile('pot: \\D?[0-9.,]+ won by (?P<player>.+) \$\\D?(?P<winnings>[0-9.,]+)\$'), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('Seat (?P<seat>\\d+): (?P<player>.+) \$\\D?[0-9.,]+\$[^,]'): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('Seat \\d+: (?P<player>.+) \$\\D?(?P<starting_stack>[0-9.,]+)\$[^,]'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency_symbol': (re.compile('\$(?P<currency_symbol>\\D?)[0-9.,]+\$'), <class 'str'>), 'day': (re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'int'>), 'hand': (re.compile('\\*\\*\\*\\*\\* History for hand (?P<hand>.+) \\*\\*\\*\\*\\*'), <class 'str'>), 'month': (re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <built-in method get of dict object>), 'table': (re.compile('Table: (?P<table>\\S+) \\['), <class 'str'>), 'time': (re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <function parse_time>), 'time_zone_abbreviation': (re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'str'>), 'year': (re.compile('Start hand: \\w+ (?P<month>\\w+) (?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile('\\((?P<variant>NO_LIMIT TEXAS_HOLDEM) '): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {'NO_LIMIT TEXAS_HOLDEM': 'NT'}: Variant conversion lookup.

class pokerkit.notation.Parser

Bases: ABC

An abstract base class for hand history parser.

Parsers, when called with raw hand history log string, return a generator of poker hand histories.

class pokerkit.notation.PartyPokerParser

Bases: REParser

A class for PartyPoker hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?!)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) posts (small|big) blind \\[\\D?(?P<blind_or_straddle>[0-9.,]+) \\w+\\]\\.'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('\\*\\* Dealing (Flop|Turn|River) \\*\\* \\[(?P<cards>[1-9TJQKAcdhs ,]+)\\]'): Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) c(all|heck)s'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) (bets|raises|is all-In ) \\[\\D?(?P<amount>[0-9.,]+) \\w+\\]'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'PartyPoker'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile('Seat (?P<final_seat>\\d+) is the button'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) folds'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^Game #.+?(?=^\\n{2,})', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+) shows \\[(?P<cards>[1-9TJQKAcdhs ,]+)\\]'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('(?!)'): Hole dealing pattern.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'winnings': (re.compile('^(?P<player>\\S+) wins \\D?(?P<winnings>[0-9.,]+)', re.MULTILINE), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('Seat (?P<seat>\\d+): (?P<player>.+) \\('): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('Seat \\d+: (?P<player>.+) \$ \\D?(?P<starting_stack>[0-9.,]+) \\w+ \$'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency': (re.compile('\$ \\D?[0-9.,]+ (?P<currency>\\w+) \$'), <class 'str'>), 'currency_symbol': (re.compile('\$ (?P<currency_symbol>\\D?)[0-9.,]+ \\w+ \$'), <class 'str'>), 'day': (re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'int'>), 'hand': (re.compile('\\*\\*\\*\\*\\* Hand History for Game (?P<hand>\\d+) \\*\\*\\*\\*\\*'), <class 'int'>), 'month': (re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <function parse_month>), 'table': (re.compile('Table (?P<table>.+?) \\('), <class 'str'>), 'time': (re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <function parse_time>), 'time_zone_abbreviation': (re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'str'>), 'year': (re.compile(' - \\w+, (?P<month>\\w+) (?P<day>\\d+), (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+) (?P<year>\\d+)'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile(" (?P<variant>NL Texas Hold'em) - "): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {"NL Texas Hold'em": 'NT'}: Variant conversion lookup.

class pokerkit.notation.PokerStarsParser

Bases: REParser

A class for PokerStars hand history parser.

ANTE_POSTING: ClassVar[Pattern[str]] = re.compile('(?!)'): Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+): posts (small|big) blind \\D?(?P<blind_or_straddle>[0-9.]+)'): Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]] = re.compile('\\*\\*\\*( (FLOP) \\*\\*\\*| (TURN|RIVER) \\*\\*\\* \\[[1-9TJQKAcdhs ]+\\]) \\[(?P<cards>[1-9TJQKAcdhs ]+)\\]'): Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+): c(all|heck)s'): Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+): (bet|raise)s \\D?(?P<amount>[0-9.]+)'): Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {'venue': 'PokerStars'}: Constants.

DATETIME: ClassVar[Pattern[str]] = re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'): The datetime pattern.

FINAL_SEAT: ClassVar[Pattern[str]] = re.compile('#(?P<final_seat>\\d+) is the button'): Final seat pattern.

FOLDING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+): folds'): Folding pattern.

HAND: ClassVar[Pattern[str]] = re.compile('^PokerStars .+?(?=^\\n{2,})', re.MULTILINE|re.DOTALL): The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]] = re.compile('(?P<player>.+): shows \\[(?P<cards>[1-9TJQKAcdhs ]+)\\] (.+)'): Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]] = re.compile('Dealt to (?P<player>.+) \\[(?P<cards>[1-9TJQKAcdhs ]+)\\]'): Hole dealing pattern.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]] = {'winnings': (re.compile('(Seat \\d+:)? (?P<player>.+) collected \$?\\D?(?P<winnings>[0-9.,]+)\$?( from pot)?'), None, <class 'int'>, <built-in function add>)}: Player variables.

SEATS: ClassVar[Pattern[str]] = re.compile('Seat (?P<seat>\\d+): (?P<player>.+) \\('): Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]] = re.compile('Seat \\d+: (?P<player>.+) \$\\D?(?P<starting_stack>[0-9.]+) in chips\$'): Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]] = {'currency_symbol': (re.compile('\$(?P<currency_symbol>\\D?)[0-9.,]+ in chips\$'), <class 'str'>), 'day': (re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'), <class 'int'>), 'hand': (re.compile('PokerStars (Hand|Game) #(?P<hand>\\d+):'), <class 'int'>), 'month': (re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'), <class 'int'>), 'seat_count': (re.compile(' (?P<seat_count>\\d+)-max '), <class 'int'>), 'table': (re.compile("Table '(?P<table>.+)'"), <class 'str'>), 'time': (re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'), <function parse_time>), 'time_zone_abbreviation': (re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'), <class 'str'>), 'year': (re.compile(' - (?P<year>\\d+)/(?P<month>\\d+)/(?P<day>\\d+) (?P<time>\\d{1,2}:\\d{2}:\\d{2}) (?P<time_zone_abbreviation>\\S+)'), <class 'int'>)}: Variables.

VARIANT: ClassVar[Pattern[str]] = re.compile(": (?P<variant>Hold'em No Limit) \\("): Variant pattern.

VARIANTS: ClassVar[dict[str, str]] = {"Hold'em No Limit": 'NT'}: Variant conversion lookup.

class pokerkit.notation.REParser

Bases: Parser, ABC

An abstract base class for hand history parser using regular expressions.

ANTE_POSTING: ClassVar[Pattern[str]]: Ante posting pattern.

BLIND_OR_STRADDLE_POSTING: ClassVar[Pattern[str]]: Blind or straddle posting pattern.

BOARD_DEALING: ClassVar[Pattern[str]]: Board dealing pattern.

CHECKING_OR_CALLING: ClassVar[Pattern[str]]: Checking or calling pattern.

COMPLETION_BETTING_OR_RAISING: ClassVar[Pattern[str]]: Completion, betting, or raising to pattern.

CONSTANTS: ClassVar[dict[str, Any]] = {}: Constants.

FINAL_SEAT: ClassVar[Pattern[str]]: Final seat pattern.

FOLDING: ClassVar[Pattern[str]]: Folding pattern.

HAND: ClassVar[Pattern[str]]: The hand pattern.

HOLE_CARDS_SHOWING: ClassVar[Pattern[str]]: Hole cards showing pattern.

HOLE_DEALING: ClassVar[Pattern[str]]: Hole dealing pattern.

PLAYER_VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None, Callable[[], Any], Callable[[Any, Any], Any]]]]: Player variables.

SEATS: ClassVar[Pattern[str]]: Seats pattern.

STARTING_STACKS: ClassVar[Pattern[str]]: Starting stacks pattern.

VARIABLES: ClassVar[dict[str, tuple[Pattern[str], Callable[[str], Any] | None]]]: Variables.

VARIANT: ClassVar[Pattern[str]]: Variant pattern.

VARIANTS: ClassVar[dict[str, str]]: Variant conversion lookup.

pokerkit.notation.parse_action(state: ~pokerkit.state.State, action: str, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>) → None

Parse the action.

Parameters:

state – The state.
action – The string action.
parse_value – The value parsing function.

Returns:

None.

pokerkit.state module

pokerkit.state implements classes related to poker states.

class pokerkit.state.AntePosting(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for ante postings.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.Automation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for automations.

Each member of this enum specify what specific capability in PokerKit the user is not interested in handling manually and therefore should be automatically (and reasonably) handled by the library.

>>> Automation.ANTE_POSTING
<Automation.ANTE_POSTING: 'Ante posting'>
>>> Automation.CARD_BURNING
<Automation.CARD_BURNING: 'Card burning'>

ANTE_POSTING: str = 'Ante posting'

The ante posting automation.

By default, the players’ antes are posted in order of their player indices.

BET_COLLECTION: str = 'Bet collection'

The bet collection automation.

This is performed typically after a betting round or ante postings.

BLIND_OR_STRADDLE_POSTING: str = 'Blind or straddle posting'

The blind or straddle posting automation.

On automation, the players’ blinds or straddles are posted in order of their player indices.

BOARD_DEALING: str = 'Board dealing'

The board dealing automation.

The automated dealing behavior is simply drawing from the deck.

If there are multiple boards, the boards are dealt in the order of increasing board indices (from the zeroth board).

CARD_BURNING: str = 'Card burning'

The card burning automation.

When automated, the burnt card is dealt from the deck.

CHIPS_PULLING: str = 'Chips pulling'

The chips pulling automation.

When automated, the chips-pulling is done in the order of player indices.

CHIPS_PUSHING: str = 'Chips pushing'

The chips pushing automation.

When automated, the chips pushing is done one by one, for each split main/side pot.

HAND_KILLING: str = 'Hand killing'

The hand killing automation.

When automated, the hand killing is done in the order of player indices.

HOLE_CARDS_SHOWING_OR_MUCKING: str = 'Hole cards showing or mucking'

The hole cards showing or mucking automation.

By default, proper showdown order is followed and players show only when necessary.

HOLE_DEALING: str = 'Hole dealing'

The hole dealing automation.

When automated, the hole cards are dealt from the deck, in proper hole card dealing order (in accordance to player indices).

RUNOUT_COUNT_SELECTION: str = 'Runout-count selection'

The runout-count selection automation.

This automation is useless in tournament mode, as tournament mode automatically skips runout-count selection phase since only a single runout is performed by rule.

class pokerkit.state.BetCollection(bets: tuple[int, ...], *, commentary: str | None = None)

Bases: Operation

The class for bet collections.

bets: tuple[int, ...]: The bets.

property total_bets: int

Return the total bets.

>>> bet_collection = BetCollection((1, 2, 3))
>>> bet_collection.total_bets
6

Returns:: The total bets.

class pokerkit.state.BettingStructure(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for betting structures.

>>> BettingStructure.FIXED_LIMIT
<BettingStructure.FIXED_LIMIT: 'Fixed-limit'>
>>> BettingStructure.NO_LIMIT
<BettingStructure.NO_LIMIT: 'No-limit'>

Betting structures tell PokerKit what betting limit (e.g., No-Limit, Pot-Limit, etc.) the variant uses.

The limit may set the limitations on the maximum bet/raise amounts.

Some commentators put cap-limit as a possible betting structure, but we disagree in such a designation since the “cap-limit” is equivalent to simply pretending to have lesser starting stack values.

The number of maximum bet/raises and the min-bet are set by streets’ pokerkit.state.Street.max_completion_betting_or_raising_count and pokerkit.state.Street.min_completion_betting_or_raising_amount attributes.

FIXED_LIMIT: str = 'Fixed-limit'

The fixed-limit.

Here, min and max completion, bet, and raise amounts are identical.

Typically, the number of bet/raises permitted is also limited. This is not the case in some tournament settings when heads-up play is reached.

NO_LIMIT: str = 'No-limit'

The no-limit.

This denotes unlimited bet/raises in both the amounts (limited by the stack/cap).

The number of them per betting round is typically unlimited in no-limit games.

POT_LIMIT: str = 'Pot-limit'

The pot-limit.

This limits the bet/raise amount to the pot bet amount, following the following formula M = (3L + T) + S where M is the maximum bet, L is the last wager, T is the trail (action prior to the previous bet), and S the starting pot (source: https://en.wikipedia.org/wiki/Betting_in_poker).

The number of bet/raises is typically unlimited when this limit is used.

class pokerkit.state.BlindOrStraddlePosting(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for blind or straddle postings.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.BoardDealing(cards: tuple[Card, ...], *, commentary: str | None = None)

Bases: Operation

The class for board dealings.

cards: tuple[Card, ...]: The cards.

class pokerkit.state.BringInPosting(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for bring-in postings.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.CardBurning(card: Card, *, commentary: str | None = None)

Bases: Operation

The class for card burnings.

card: Card: The card.

class pokerkit.state.CheckingOrCalling(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for checking or callings.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.ChipsPulling(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for chips pullings.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.ChipsPushing(amounts: tuple[int, ...], pot_index: int, board_index: int | None, hand_type_index: int | None, *, commentary: str | None = None)

Bases: Operation

The class for chips pushings.

amounts: tuple[int, ...]: The amounts.

board_index: int | None

The optional index of the board used to evaluate players’ hands.

If the push was during a folded or mucked pot, this value is None.

hand_type_index: int | None

The optional index of the hand type used to evaluate players’ hands.

If the push was during a folded or mucked pot, this value is None.

pot_index: int: The index of the pot (or portion of the pot) that was pushed.

property total_amount: int

Return the amount that was not raked and therefore pushed.

This is identical to the sum of values in pokerkit.state.ChipsPushing.amounts.

Returns:: The unraked amount.

class pokerkit.state.CompletionBettingOrRaisingTo(player_index: int, amount: int, *, commentary: str | None = None)

Bases: Operation

The class for completion, betting, or raising tos.

amount: int: The amount.

player_index: int: The player index.

class pokerkit.state.Folding(player_index: int, *, commentary: str | None = None)

Bases: Operation

The class for foldings.

player_index: int: The player index.

class pokerkit.state.HandKilling(player_index: int, *, commentary: str | None = None)

Bases: Operation

The class for hand killings.

player_index: int: The player index.

class pokerkit.state.HoleCardsShowingOrMucking(player_index: int, hole_cards: tuple[Card, ...], *, commentary: str | None = None)

Bases: Operation

The class for hole cards showing or muckings.

hole_cards: tuple[Card, ...]: The hole cards.

player_index: int: The player index.

class pokerkit.state.HoleDealing(player_index: int, cards: tuple[Card, ...], statuses: tuple[bool, ...], *, commentary: str | None = None)

Bases: Operation

The class for hole dealings.

cards: tuple[Card, ...]: The cards.

player_index: int: The player index.

statuses: tuple[bool, ...]: The statuses.

class pokerkit.state.Mode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for poker state types.

Depending on whether the poker state is of a tournament or a cash-game, its behavior is different. Tournament settings tend to be stricter as it sets limitations on various operations:

The number of runouts in all-in situations is always 1.
In all-in situations, hole cards must be shown.
When showing hole cards, all hole cards must be shown.

>>> Mode.TOURNAMENT
<Mode.TOURNAMENT: 'Tournament'>
>>> Mode.CASH_GAME
<Mode.CASH_GAME: 'Cash-game'>

CASH_GAME = 'Cash-game': The cash-game poker state type.

TOURNAMENT = 'Tournament': The tournament poker state type.

class pokerkit.state.NoOperation(*, commentary: str | None = None)

Bases: Operation

The class for no-operations.

class pokerkit.state.Opening(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for openings.

Openings describe how the opener of the betting round should be chosen. Typically they are chosen by their position, up hand, or an up card.

>>> Opening.POSITION
<Opening.POSITION: 'Position'>
>>> Opening.LOW_HAND
<Opening.LOW_HAND: 'Low hand'>

HIGH_CARD: str = 'High card': The opener is decided by having the highest exposed card.

HIGH_HAND: str = 'High hand': The opener is decided by having the highest exposed hand, then position.

LOW_CARD: str = 'Low card': The opener is decided by having the lowest exposed card.

LOW_HAND: str = 'Low hand': The opener is decided by having the lowest exposed hand, then position.

POSITION: str = 'Position'

The opener is decided by position.

If blinds or straddles are present, they are taken account of.

class pokerkit.state.Operation(*, commentary: str | None = None)

Bases: ABC

The abstract base class for operations.

Each operation describes a single update or change that took place in the poker state.

commentary: str | None = None: The optional commentary (i.e., comments).

class pokerkit.state.Pot(raked_amount: int, unraked_amount: int, player_indices: tuple[int, ...])

Bases: object

The class for pots.

Each pot amount is composed of the raked and the unraked amounts and belongs to a set of players.

Parameters:

raked_amount – The raked amount. For more details, please refer to pokerkit.state.Pot.raked_amount.
unraked_amount – The unraked amount. For more details, please refer to pokerkit.state.Pot.unraked_amount.
player_indices – The player indices. For more details, please refer to pokerkit.state.Pot.player_indices.

Raises:

ValueError – If the arguments are invalid.

property amount: int

Return the pot amount.

This is the sum of the pot’s raked and unraked portions.

Returns:: The pot amount.

player_indices: tuple[int, ...]

The player indices of those who are eligible to win.

This means that they contributed to this pot and they are still active (i.e., in the hand).

raked_amount: int

The raked amount (from the original amount pokerkit.state.Pot).

This value must be non-negative.

unraked_amount: int

The unraked amount (remaining from the original amount pokerkit.state.Pot).

This vealue must be non-negative.

class pokerkit.state.RunoutCountSelection(player_index: int, runout_count: int | None, *, commentary: str | None = None)

Bases: Operation

The class for runout-count selection.

player_index: int: The player index.

runout_count: int | None: The runout-count.

class pokerkit.state.StandingPatOrDiscarding(player_index: int, cards: tuple[Card, ...], *, commentary: str | None = None)

Bases: Operation

The class for standing pat or discardings.

cards: tuple[Card, ...]: The discarded cards, empty if stood pat.

player_index: int: The player index.

class pokerkit.state.State(automations: tuple[~pokerkit.state.Automation, ...], deck: ~pokerkit.utilities.Deck, hand_types: tuple[type[~pokerkit.hands.Hand], ...], streets: tuple[~pokerkit.state.Street, ...], betting_structure: ~pokerkit.state.BettingStructure, ante_trimming_status: bool, raw_antes: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int], raw_blinds_or_straddles: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int], bring_in: int, raw_starting_stacks: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int], player_count: int, *, mode: ~pokerkit.state.Mode = Mode.TOURNAMENT, starting_board_count: int = 1, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int, ~pokerkit.state.State], tuple[int, int]] = <function rake>)

Bases: object

The class for poker states.

Below code shows an example Kuhn poker game with all non-player actions and showdown automated.

>>> from pokerkit import KuhnPokerHand
>>> state = State(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (1,) * 2,
...     (0,) * 2,
...     0,
...     (2,) * 2,
...     2,
... )

The game is active with the following stacks, bets, and hole cards.

>>> state.status
True
>>> state.stacks
[1, 1]
>>> state.bets
[0, 0]
>>> state.hole_cards  
[[...s], [...s]]

First player checks.

>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.stacks
[1, 1]
>>> state.bets
[0, 0]

The second player bets 1.

>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=1)
>>> state.stacks
[1, 0]
>>> state.bets
[0, 1]

The first player folds.

>>> state.fold()
Folding(commentary=None, player_index=0)
>>> state.stacks
[1, 3]
>>> state.bets
[0, 0]
>>> state.total_pot_amount
0
>>> state.status
False

Below shows the identical game, but without any automation.

>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (1,) * 2,
...     (0,) * 2,
...     0,
...     (2,) * 2,
...     2,
... )
>>> state.status
True

Antes are collected.

>>> state.post_ante(0)
AntePosting(commentary=None, player_index=0, amount=1)
>>> state.post_ante(1)
AntePosting(commentary=None, player_index=1, amount=1)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(1, 1))

Hole cards are dealt.

>>> state.deal_hole('Js')  
HoleDealing(commentary=None, player_index=0, cards=(Js,), statuses=(Fals...
>>> state.deal_hole()  
HoleDealing(commentary=None, player_index=1, cards=(...s,), statuses=(Fa...

The actions are carried out.

>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=1)
>>> state.fold()
Folding(commentary=None, player_index=0)

The bets are collected and distributed to the winner.

>>> state.collect_bets()
BetCollection(commentary=None, bets=(0, 0))
>>> state.push_chips()  
ChipsPushing(commentary=None, amounts=(0, 2), pot_index=0, board_index=N...
>>> state.pull_chips(1)
ChipsPulling(commentary=None, player_index=1, amount=3)

The game has terminated.

>>> state.status
False

Parameters:

automations – The automations. For more details, please refer to pokerkit.state.State.automations.
deck – The deck. For more details, please refer to pokerkit.state.State.deck.
hand_types – The hand types. For more details, please refer to pokerkit.state.State.hand_types.
streets – The streets. For more details, please refer to pokerkit.state.State.streets.
betting_structure – The betting structure. For more details, please refer to pokerkit.state.State.betting_structure.
ante_trimming_status – The ante trimming status. For more details, please refer to pokerkit.state.State.ante_trimming_status.
raw_antes – The “raw” antes. For more details, please refer to pokerkit.state.State.raw_antes.
raw_blinds_or_straddles – The “raw” blinds/straddles. For more details, please refer to pokerkit.state.State.raw_blinds_or_straddles.
bring_in – The bring-in. For more details, please refer to pokerkit.state.State.bring_in.
raw_starting_stacks – The “raw” starting stacks. For more details, please refer to pokerkit.state.State.raw_starting_stacks.
player_count – The number of players. For more details, please refer to pokerkit.state.State.player_count.
mode – The mode. Defaults to tournament mode. For more details, please refer to pokerkit.state.State.mode.
starting_board_count – The number of boards at the start of the game. For more details, please refer to pokerkit.state.State.starting_board_count.
divmod – The divmod function. For more details, please refer to pokerkit.state.State.divmod.
rake – The rake function. For more details, please refer to pokerkit.state.State.rake.

Raises:

ValueError – If the arguments are invalid.

acted_player_indices: set[int]: The indices of players who acted.

property actor_index: int | None

Return the actor index.

The returned index denotes the index of the current actor (in turn to act).

Returns:: The actor index if applicable, otherwise None.

actor_indices: deque[int]

The actor indices.

The order of actors to act (i.e., turn indices). The first item denotes who is in action.

all_in_status: bool = False

The all-in status.

Simply put, are all active players all-in? True if yes, False otherwise.

property ante_poster_indices: Iterator[int]

Iterate through players who can post antes.

The yielded indices are sorted by player indices.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.ante_poster_indices  
<generator object State.ante_poster_indices at 0x...>
>>> tuple(state.ante_poster_indices)
(0,)

>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     2,
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> tuple(state.ante_poster_indices)
(0, 1)
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> tuple(state.ante_poster_indices)
()

Returns:: The ante posters.

ante_posting_statuses: list[bool]

The player ante posting statuses.

Each item denotes whether a player at that index can post the ante (True) or cannot (False).

Each ante posting operation swithces one True item to False.

ante_trimming_status: bool

The ante trimming status.

It denotes whether or not to activate the trimming behavior during bet collection immediately after the antes are posted.

Usually, if you want uniform antes, set this to True. If you want non-uniform antes like big blind antes, set this to False.

antes: tuple[int, ...]

The antes.

This value is the “interpreted” version of the “raw” antes.

automations: tuple[Automation, ...]

The automations.

Allows the user to specify what steps they do not care about and therefore should be automatically handled by PokerKit.

bet_collection_status: bool = False

The bet collection status.

If True, then a bet collection is pending. The corresponding operation, when performed, will set this attribute to False.

bets: list[int]: The player bets.

betting_structure: BettingStructure

The betting structure.

This class attribute determines the betting limits of a particular game (e.g., no-limit, pot-limit, or fixed-limit).

property blind_or_straddle_poster_indices: Iterator[int]

Iterate through indices of players who can post blinds or straddles.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     4,
... )
>>> state.blind_or_straddle_poster_indices  
<generator object State.blind_or_straddle_poster_indices at 0x...>
>>> tuple(state.blind_or_straddle_poster_indices)
()
>>> state.post_ante(1)
AntePosting(commentary=None, player_index=1, amount=2)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(0, 2, 0, 0))
>>> tuple(state.blind_or_straddle_poster_indices)
(0, 1)

Returns:: The blind or straddle poster indices.

blind_or_straddle_posting_statuses: list[bool]

The player blind or straddle statuses.

Each item denotes whether a player at that index can post the blind/straddle (True) or cannot (False).

Each blind/straddle posting operation swithces one True item to False.

blinds_or_straddles: tuple[int, ...]

The blinds or straddles.

This value is the “interpreted” version of the “raw” blinds/straddles.

board_cards: list[list[Card]]

The board cards.

This is a 2D list as cards may be parallel to each other for games with multiple boards or in the case of multiple runouts (during all-ins).

property board_count: int

Return the number of boards.

It should be equal to the number of runouts, if set, at the end of the game.

If no card was dealt to the board, the pokerkit.state.State.starting_board_count is returned.

Returns:: The number of boards.

property board_dealing_count: int | None

Return the number of pending board dealings.

Returns:: The number of board dealings.

board_dealing_counts: list[int]

The board dealing counts.

This is a list, as there may be multiple pending board dealings (due to multiple boards).

property board_indices: range

Return the board indices.

Returns:: The board indices.

bring_in: int

The bring-in.

Some poker games do not have the bring-in, in which case 0 should be its value.

This value must be non-negative. If all ante and blind/straddle values are zero, the bring-in must be positive. If any of the blind/straddle values are non-zero, the bring-in must be zero.

It must be less than the min-bet.

bring_in_status: bool = False

The bring-in status.

If True, the player should at least post a bring-in (therefore cannot fold).

burn_card(card: Iterable[Card] | Card | str | None = None, *, commentary: str | None = None) → CardBurning

Burn a card.

If the card is not specified, a card is drawn from the deck. The deck, if empty, will be replenished from the reserve.

If a string representation is used, only a single card must be described.

Parameters:

card – The optional card.
commentary – The optional commentary.

Returns:

The card burning.

Raises:

ValueError – If the card burning cannot be done.

burn_cards: list[Card]

The burn cards.

Cards that are burned are added here. These may be used later to replenish the deck (should it run out).

can_burn_card(card: Iterable[Card] | Card | str | None = None) → bool

Return whether the card burning can be done.

For more details on this operation, please consult the method pokerkit.state.State.burn_card().

Parameters:: card – The optional card.
Returns:: True if the card burning can be done, otherwise False.

can_check_or_call() → bool

Return whether the checking or calling can be done.

For more details on this operation, please consult the method pokerkit.state.State.check_or_call().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (100, 100, 200),
...     3,
... )
>>> state.can_check_or_call()
True
>>> state.fold()
Folding(commentary=None, player_index=2)
>>> state.can_check_or_call()
True
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> state.status
False
>>> state.can_check_or_call()
False

Returns:: True if the checking or calling can be done, otherwise False.

can_collect_bets() → bool

Return whether the bet collection can be done.

For more details on this operation, please consult the method pokerkit.state.State.collect_bets().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.can_collect_bets()
False
>>> state.post_ante()
AntePosting(commentary=None, player_index=0, amount=2)
>>> state.can_collect_bets()
True

Returns:: True if the bet collection can be done, otherwise False.

can_complete_bet_or_raise_to(amount: int | None = None) → bool

Return whether the completion, betting, or raising can be done.

For more details on this operation, please consult the method pokerkit.state.State.complete_bet_or_raise_to().

>>> from pokerkit import (
...     NoLimitTexasHoldem,
...     FixedLimitDeuceToSevenLowballTripleDraw,
... )
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (100, 100, 200),
...     3,
... )
>>> state.can_complete_bet_or_raise_to()
True
>>> state.can_complete_bet_or_raise_to(4)
True
>>> state.can_complete_bet_or_raise_to(200)
True
>>> state.can_complete_bet_or_raise_to(3)
False
>>> state.can_complete_bet_or_raise_to(201)
False
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=2)
>>> state.complete_bet_or_raise_to(100)  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.fold()
Folding(commentary=None, player_index=1)
>>> state.can_complete_bet_or_raise_to(200)
False
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=98)
>>> state.status
False
>>> state.can_complete_bet_or_raise_to()
False

>>> state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     4,
...     200,
...     6,
... )
>>> state.can_complete_bet_or_raise_to()
True
>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount=4)
>>> state.can_complete_bet_or_raise_to()
True
>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=3, amount=6)
>>> state.can_complete_bet_or_raise_to()
True
>>> state.complete_bet_or_raise_to()
CompletionBettingOrRaisingTo(commentary=None, player_index=4, amount=8)
>>> state.can_complete_bet_or_raise_to()
True
>>> state.complete_bet_or_raise_to()  
CompletionBettingOrRaisingTo(commentary=None, player_index=5, amount...
>>> state.can_complete_bet_or_raise_to()
False
>>> state.complete_bet_or_raise_to()
Traceback (most recent call last):
    ...
ValueError: No more completion, betting, or raising is permitted.

Parameters:: amount – The optional completion, betting, or raising to amount.
Returns:: True if the completion, betting, or raising can be done, otherwise False.

can_deal_board(cards: Iterable[Card] | Card | str | int | None = None) → bool

Return whether the board dealing can be done.

For more details on this operation, please consult the method pokerkit.state.State.deal_board().

Parameters:

cards – The optional cards.
player_index – The optional player index.

Returns:

True if the board dealing can be done, otherwise False.

Return whether the hole dealing can be done.

For more details on this operation, please consult the method pokerkit.state.State.deal_hole().

Parameters:

cards – The optional cards.
player_index – The optional target dealee.

Returns:

True if the hole dealing can be done, otherwise False.

can_fold() → bool

Return whether theing fold can be done.

For more details on this operation, please consult the method pokerkit.state.State.fold().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (100, 100, 200),
...     3,
... )
>>> state.can_fold()
True
>>> state.fold()
Folding(commentary=None, player_index=2)
>>> state.can_fold()
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=1)
>>> state.can_fold()
False
>>> state.complete_bet_or_raise_to(4)
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount=4)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> state.status
False
>>> state.can_fold()
False

Returns:: True if the folding can be done, otherwise False.

can_kill_hand(player_index: int | None = None) → bool

Return whether the hand killing can be done.

For more details on this operation, please consult the method pokerkit.state.State.kill_hand().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     3,
... )

Pre-flop.

>>> state.deal_hole('JcJd')  
HoleDealing(commentary=None, player_index=0, cards=(Jc, Jd), statuse...
>>> state.deal_hole('QcQd')  
HoleDealing(commentary=None, player_index=1, cards=(Qc, Qd), statuse...
>>> state.deal_hole('KcKd')  
HoleDealing(commentary=None, player_index=2, cards=(Kc, Kd), statuse...
>>> state.complete_bet_or_raise_to(200)  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=199)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=198)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('AcAdAh')
BoardDealing(commentary=None, cards=(Ac, Ad, Ah))

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2c')
BoardDealing(commentary=None, cards=(2c,))
>>> state.can_kill_hand()
False

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2d')
BoardDealing(commentary=None, cards=(2d,))
>>> state.can_kill_hand()
True
>>> state.can_kill_hand(0)
True
>>> state.can_kill_hand(1)
True
>>> state.can_kill_hand(2)
False

Parameters:: player_index – The optional player index.
Returns:: True if the hand killing can be done, otherwise False.

can_no_operate() → bool

Return whether the no-operation can be done. Always True.

For more details on this operation, please consult the method pokerkit.state.State.no_operate().

Returns:: True.

can_post_ante(player_index: int | None = None) → bool

Return whether the ante posting can be done.

For more details on this operation, please consult the method pokerkit.state.State.post_ante().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.can_post_ante()
True
>>> state.can_post_ante(0)
True
>>> state.can_post_ante(1)
False

>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.can_post_ante()
False
>>> state.can_post_ante(0)
False
>>> state.can_post_ante(1)
False

Parameters:: player_index – The optional player index.
Returns:: True if the ante posting can be done, otherwise False.

can_post_blind_or_straddle(player_index: int | None = None) → bool

Return whether the blind or straddle posting can be done.

For more details on this operation, please consult the method pokerkit.state.State.post_blind_or_straddle().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     4,
... )
>>> state.can_post_blind_or_straddle()
False
>>> state.post_ante(1)
AntePosting(commentary=None, player_index=1, amount=2)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(0, 2, 0, 0))
>>> state.can_post_blind_or_straddle()
True
>>> state.can_post_blind_or_straddle(0)
True
>>> state.can_post_blind_or_straddle(1)
True
>>> state.can_post_blind_or_straddle(2)
False
>>> state.can_post_blind_or_straddle(3)
False

Parameters:: player_index – The optional player index.
Returns:: True if the blind or straddle posting can be done, otherwise False.

can_post_bring_in() → bool

Return whether the bring-in posting can be done.

For more details on this operation, please consult the method pokerkit.state.State.post_bring_in().

Returns:: True if the bring-in posting can be done, otherwise False.

can_pull_chips(player_index: int | None = None) → bool

Return whether the chips pulling can be done.

For more details on this operation, please consult the method pokerkit.state.State.pull_chips().

>>> from pokerkit import FixedLimitDeuceToSevenLowballTripleDraw
>>> state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     4,
...     200,
...     3,
... )
>>> state.can_pull_chips()
False
>>> state.fold()
Folding(commentary=None, player_index=2)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> state.can_pull_chips()
True
>>> state.can_pull_chips(0)
False
>>> state.can_pull_chips(1)
True
>>> state.can_pull_chips(2)
False

Parameters:: player_index – The optional player index.
Returns:: True if the chips pulling can be done, otherwise False.

can_push_chips() → bool

Return whether the chips pushing can be done.

For more details on this operation, please consult the method pokerkit.state.State.push_chips().

>>> from pokerkit import FixedLimitDeuceToSevenLowballTripleDraw
>>> state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     4,
...     200,
...     3,
... )
>>> state.can_push_chips()
False
>>> state.fold()
Folding(commentary=None, player_index=2)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> state.can_push_chips()
True

Returns:: True if the chips pushing can be done, otherwise False.

can_select_runout_count(runout_count: int | None = None, player_index: int | None = None) → bool

Return whether the runout-count selection can be done.

For more details on this operation, please consult the method pokerkit.state.State.select_runout_count().

Parameters:

runout_count – The number of runouts, defaults to None.
player_index – The optional player index.

Returns:

True if the runout-count selection can be done, otherwise False.

Return whether the hole card showing or mucking can be done.

For more details on this operation, please consult the method pokerkit.state.State.show_or_muck_hole_cards().

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     3,
... )

Pre-flop.

>>> state.deal_hole('JcJd')  
HoleDealing(commentary=None, player_index=0, cards=(Jc, Jd), statuse...
>>> state.deal_hole('KcKd')  
HoleDealing(commentary=None, player_index=1, cards=(Kc, Kd), statuse...
>>> state.deal_hole('QcQd')  
HoleDealing(commentary=None, player_index=2, cards=(Qc, Qd), statuse...
>>> state.complete_bet_or_raise_to(6)
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount=6)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=5)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=4)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('AcAdAh')
BoardDealing(commentary=None, cards=(Ac, Ad, Ah))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2c')
BoardDealing(commentary=None, cards=(2c,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2d')
BoardDealing(commentary=None, cards=(2d,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.can_show_or_muck_hole_cards()
False
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)

Showdown.

>>> state.can_show_or_muck_hole_cards()
True
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=0, hole_card...
>>> state.can_show_or_muck_hole_cards(False)
True
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...
>>> state.can_show_or_muck_hole_cards(True)
True
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=2, hole_card...

Parameters:

status_or_hole_cards – The optional status or hole cards.
player_index – The optional player index to override the showdown order.

Returns:

True if the hole crad showing or mucking can be done, otherwise False.

can_stand_pat_or_discard(cards: Iterable[Card] | Card | str = ()) → bool

Return whether the discard can be done.

For more details on this operation, please consult the method pokerkit.state.State.stand_pat_or_discard().

Parameters:: cards – The optional discarded cards, defaults to empty.
Returns:: True if the discard can be done, otherwise False.

can_win_now(player_index: int) → bool

Return whether if the player might win something based on the available information to a player.

This basically means that nobody has yet shown a hand that prevents the player from winning even a tiny portion of any main/side pots.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100),
...     2,
... )

Pre-flop.

>>> state.deal_hole('KhQh')  
HoleDealing(commentary=None, player_index=0, cards=(Kh, Qh), statuse...
>>> state.deal_hole('AcKc')  
HoleDealing(commentary=None, player_index=1, cards=(Ac, Kc), statuse...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('JsTs2c')
BoardDealing(commentary=None, cards=(Js, Ts, 2c))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ah')
BoardDealing(commentary=None, cards=(Ah,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('As')
BoardDealing(commentary=None, cards=(As,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Showdown.

>>> state.can_win_now(0)
True
>>> state.can_win_now(1)
True
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=0, hole_card...
>>> state.can_win_now(0)
True
>>> state.can_win_now(1)
False
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...

Parameters:: player_index – The player index.
Returns:: True if the player can win, otherwise False.

card_burning_status: bool = False

The card burning status.

If True, a card burning is pending.

property cards_in_play: Iterator[Card]

Iterate through the cards in play.

These are visible by at least one player still in the pot and hence are either in the board or holes.

Returns:: The cards in play.

property cards_not_in_play: Iterator[Card]

Iterate through the cards not in play.

These are invisible by players still in the pot and hence are either in the deck, burns, muck, or discards.

Returns:: The cards not in play.

check_or_call(*, commentary: str | None = None) → CheckingOrCalling

Check or call.

This entails matching or trying to match the largest outstanding bet by others. If nobody has yet bet in the current betting round, the player is said to check.

The actor can be accessed through pokerkit.state.State.actor_index.

Parameters:: commentary – The optional commentary.
Returns:: The checking or calling.
Raises:: ValueError – If the checking or calling cannot be done.

property checking_or_calling_amount: int | None

Return the checking or calling amount.

Returns:: The checking or calling amount if applicable, otherwise None.

property chips_pulling_indices: Iterator[int]

Iterate through players who can pull chips.

>>> from pokerkit import FixedLimitDeuceToSevenLowballTripleDraw
>>> state = FixedLimitDeuceToSevenLowballTripleDraw.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     4,
...     200,
...     3,
... )
>>> state.chips_pulling_indices  
<generator object State.chips_pulling_indices at 0x...>
>>> tuple(state.chips_pulling_indices)
()
>>> state.fold()
Folding(commentary=None, player_index=2)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> tuple(state.chips_pulling_indices)
(1,)

Returns:: The chips pullers.

chips_pulling_statuses: list[bool]: The chips pulling statuses.

collect_bets(*, commentary: str | None = None) → BetCollection

Collect the bets.

In this operation, the outstanding bets are collected into the pot.

Note that, when the hand is folded, the last aggressor’s bet is returned to his/her stack. The rest of the outstanding bets are collected to the pot.

Parameters:: commentary – The optional commentary.
Returns:: The bet collection.
Raises:: ValueError – If the bet collection cannot be done.

complete_bet_or_raise_to(amount: int | None = None, *, commentary: str | None = None) → CompletionBettingOrRaisingTo

Complete, bet, or raise to an amount.

This opens the new betting round where the active players are forced to match the new bet (or go all-in) to stay in the pot.

The actor can be accessed through pokerkit.state.State.actor_index.

Parameters:

amount – The optional completion, betting, or raising to amount.
commentary – The optional commentary.

Returns:

The completion, betting, or raising to.

Raises:

ValueError – If the completion, betting, or raising cannot be done.

completion_betting_or_raising_amount: int = 0

The last completion, betting, or raising amount.

This attribute is updated with each completion/bet/raises.

completion_betting_or_raising_count: int = 0

The number of completions, bettings, or raisings.

This attribute is incremented with each completion/bet/raises.

completion_status: bool = False

The completion status.

If True, the player is facing a bring-in and hence a completion is pending.

consecutive_all_in_completion_betting_or_raising_amounts: list[int]

The consecutive completion, betting, or raising amounts.

This is used to track whether successive non-full wagers combine to form a full one, in which case a new betting round is started.

Deal the board.

The cards, if unspecified, will be drawn from the deck (and possibly replenished from the reserve).

Parameters:

cards – The optional cards.
commentary – The optional commentary.

Returns:

The board dealing.

Raises:

ValueError – If the board dealing cannot be done.

Deal the hole.

The number of dealt hole cards should be less than or equal to the number of pending hole dealings to the player.

If the cards to be dealt are unspecified, they will be drawn from the deck (and possibly replenished from the reserve).

If the player is not specified, they will be automatically determined. The automatic dealee is available at pokerkit.state.State.hole_dealee_index.

Parameters:

cards – The optional cards.
player_index – The optional target dealee.
commentary – The optional commentary.

Returns:

The hole dealing.

Raises:

ValueError – If the hole dealing cannot be done.

deck: Deck

The deck.

Different variants use different decks, which must be specified.

deck_cards: deque[Card]

The deck cards.

The cards in this deck are shuffled and removed from throughout the state’s lifespan.

discarded_cards: list[list[Card]]

The discards.

The discarded cards are added here. They may be used to replenish the deck when it runs out.

divmod(divisor: int) → tuple[int, int]

The divmod function. Defaults to PokerKit’s that detects integral or real values automatically.

This is used to denote how pots are divided up (for multiple boards, multiple winners, multiple hand types, etc.).

property draw_statuses: Iterator[bool]

Return a generator that iterates through draw statuses.

Each yielded item corresponds to the draw status of each street.

A draw status is True if discard/draw is performed for that street.

>>> from pokerkit import (
...     NoLimitTexasHoldem,
...     NoLimitDeuceToSevenLowballSingleDraw,
... )
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.draw_statuses  
<generator object State.draw_statuses at 0x...>
>>> tuple(state.draw_statuses)
(False, False, False, False)
>>> state = NoLimitDeuceToSevenLowballSingleDraw.create_state(
...     (),
...     True,
...     1,
...     (1, 2),
...     2,
...     200,
...     3,
... )
>>> tuple(state.draw_statuses)
(False, True)

Returns:: The draw statuses.

property effective_bring_in_amount: int | None

Return the effective bring-in.

Returns:: The effective bring-in amount if applicable, otherwise None.

fold(*, commentary: str | None = None) → Folding

Fold.

This mucks the player’s cards and signifies that the player relinquishes the right to win any of the pots.

The actor can be accessed through pokerkit.state.State.actor_index.

Parameters:: commentary – The optional commentary.
Returns:: The folding.
Raises:: ValueError – If the folding cannot be done.

get_board_cards(board_index: int) → Iterator[Card]

Return the board at the board_index (i.e. board_index’th board, accounting for runout).

In most games, there are only one board and runout, so, setting the board_index argument to 0 should do the job.

If multiple boards/runouts were used, one can supply a different argument.

Consider the following board: [[A, D], [B, E], [C, F], [G, H], [I, J, K, L]].

The alphabets denote cards dealt and defined to reflect the proper dealing order. Here, there are 4 boards. The zeroth is ABCGI, the first is ABCHJ, the second is DEFHK, and third (and the last) is DEFHL.

Param:: The board index.
Returns:: The board at the desired index.

get_censored_hole_cards(player_index: int) → Iterator[Card]

Return the censored hole cards of the player.

The hole cards that are face-down are yielded as an unknown card.

>>> from pokerkit import *
>>> state = (
...     FixedLimitSevenCardStudHighLowSplitEightOrBetter.create_state(
...         (
...             Automation.ANTE_POSTING,
...             Automation.BET_COLLECTION,
...             Automation.BLIND_OR_STRADDLE_POSTING,
...             Automation.CARD_BURNING,
...             Automation.BOARD_DEALING,
...             Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...             Automation.HAND_KILLING,
...             Automation.CHIPS_PUSHING,
...             Automation.CHIPS_PULLING,
...         ),
...         True,
...         0,
...         1,
...         2,
...         4,
...         (50, 100),
...         2,
...     )
... )
>>> state.deal_hole('AcAdAh')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad, Ah), sta...
>>> state.deal_hole('KcKdKh')  
HoleDealing(commentary=None, player_index=1, cards=(Kc, Kd, Kh), sta...
>>> state.get_down_cards(0)  
<generator object State.get_down_cards at 0x...>
>>> tuple(state.get_censored_hole_cards(0))
(??, ??, Ah)
>>> tuple(state.get_censored_hole_cards(1))
(??, ??, Kh)

Parameters:: player_index – The player index.
Returns:: The censored hole cards.

get_dealable_cards(deal_count: int | None = 0, warning_status: bool = True) → Iterator[Card]

Iterate through the available cards that can be dealt or burned.

The returned cards can be thought of as representing the cards “recommended” to be dealt. If only one card is to be dealt and there are multiple cards in the deck still remaining, then, one should select one of the cards in the deck (this is indeed one of the cards yielded by this generator).

Conversely, if one wants to deal 3 cards but there aren’t enough cards left, the deck and the reserve must both be considered since the deck will run out amid dealing them and will be replenished. Thus, in this scenario, the merger of the deck and reserve are returned.

In general, if any dealing is performed with cards not part of the value returned by this method, a warning is issued by PokerKit.

Parameters:

deal_count – The number of dealt cards, may be None to denote an arbitrary number of cards.
warning_status – Show warnings when relevant.

Returns:

The “recommended” dealable cards, from deck and maybe reserve.

get_down_cards(player_index: int) → Iterator[Card]

Return the down cards of the player.

>>> from pokerkit import FixedLimitSevenCardStud
>>> state = FixedLimitSevenCardStud.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     1,
...     2,
...     4,
...     (50, 100),
...     2,
... )
>>> state.deal_hole('AcAdAh')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad, Ah), sta...
>>> state.deal_hole('KcKdKh')  
HoleDealing(commentary=None, player_index=1, cards=(Kc, Kd, Kh), sta...
>>> state.get_down_cards(0)  
<generator object State.get_down_cards at 0x...>
>>> tuple(state.get_down_cards(0))
(Ac, Ad)
>>> tuple(state.get_down_cards(1))
(Kc, Kd)
>>> state.post_bring_in()
BringInPosting(commentary=None, player_index=1, amount=1)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> tuple(state.get_down_cards(0))
()
>>> tuple(state.get_down_cards(1))
(Kc, Kd)

Parameters:: player_index – The player index.
Returns:: The down cards of the player.

get_effective_ante(player_index: int) → int

Return the effective ante of the player.

The “effective” ante is effective in that it considers players’ stacks being too low to post the full ante. In other words, this value represents the actual value that the player will ante.

Parameters:: player_index – The player index.
Returns:: The effective ante.

get_effective_blind_or_straddle(player_index: int) → int

Return the “effective” blind or straddle of the player.

The “effective” blind/straddle is effective in that it considers players’ stacks being too low to post the full ante. In other words, this value represents the actual value that the player will post as blind or straddle.

Parameters:: player_index – The player index.
Returns:: The effective blind or straddle.

get_effective_stack(player_index: int) → int

Return the effective stack of the player.

It denotes the amount the player “can possibly lose”.

For example, if the player has the largest stack, then the second largest stack value owned by an active player will be returned.

Parameters:: player_index – The player index.
Returns:: The effective stack of the player.

get_hand(player_index: int, board_index: int, hand_type_index: int) → Hand | None

Return the corresponding hand of the player.

The player whose hand is to be evaluated must be provided through player_index. Which hand type to evaluate must be provided through hand_type_index. Since there may be multiple boards, so does board_index. For how boards are indexed, please refer to pokerkit.state.State.get_board_cards().

The down cards are considered here during hand evaluation.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100),
...     2,
... )
>>> state.get_hand(0, 0, 0) is None
True
>>> state.get_hand(1, 0, 0) is None
True

Pre-flop.

>>> state.deal_hole('AcAd')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad), statuse...
>>> state.deal_hole('KsQs')  
HoleDealing(commentary=None, player_index=1, cards=(Ks, Qs), statuse...
>>> state.get_hand(0, 0, 0) is None
True
>>> state.get_hand(1, 0, 0) is None
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('JsTs2c')
BoardDealing(commentary=None, cards=(Js, Ts, 2c))
>>> state.get_hand(0, 0, 0)
AcAdJsTs2c
>>> str(state.get_hand(0, 0, 0))
'One pair (AcAdJsTs2c)'
>>> str(state.get_hand(1, 0, 0))
'High card (KsQsJsTs2c)'
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ah')
BoardDealing(commentary=None, cards=(Ah,))
>>> str(state.get_hand(0, 0, 0))
'Three of a kind (AcAdJsTsAh)'
>>> str(state.get_hand(1, 0, 0))
'Straight (KsQsJsTsAh)'
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('As')
BoardDealing(commentary=None, cards=(As,))
>>> str(state.get_hand(0, 0, 0))
'Four of a kind (AcAdJsAhAs)'
>>> str(state.get_hand(1, 0, 0))
'Straight flush (KsQsJsTsAs)'
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.get_hand(0, 0, 0) is None
True
>>> str(state.get_hand(1, 0, 0))
'Straight flush (KsQsJsTsAs)'

Parameters:

player_index – The player index.
board_index – The board index.
hand_type_index – The hand type index.

Returns:

The corresponding hand of the player if applicable, otherwise None.

get_up_cards(player_index: int) → Iterator[Card]

Return the up cards of the player.

>>> from pokerkit import FixedLimitSevenCardStud
>>> state = FixedLimitSevenCardStud.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     1,
...     2,
...     4,
...     (50, 100),
...     2,
... )
>>> state.deal_hole('AcAdAh')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad, Ah), sta...
>>> state.deal_hole('KcKdKh')  
HoleDealing(commentary=None, player_index=1, cards=(Kc, Kd, Kh), sta...
>>> state.get_down_cards(0)  
<generator object State.get_down_cards at 0x...>
>>> tuple(state.get_up_cards(0))
(Ah,)
>>> tuple(state.get_up_cards(1))
(Kh,)
>>> state.post_bring_in()
BringInPosting(commentary=None, player_index=1, amount=1)
>>> state.fold()
Folding(commentary=None, player_index=0)
>>> tuple(state.get_up_cards(0))
()
>>> tuple(state.get_up_cards(1))
(Kh,)

Parameters:: player_index – The player index.
Returns:: The up cards of the player.

get_up_hand(player_index: int, board_index: int, hand_type_index: int) → Hand | None

Return the corresponding hand of the player from up cards.

The player whose hand is to be evaluated must be provided through player_index. Which hand type to evaluate must be provided through hand_type_index. Since there may be multiple boards, so does board_index. For how boards are indexed, please refer to pokerkit.state.State.get_board_cards().

The down cards are not considered here during hand evaluation.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100),
...     2,
... )
>>> state.get_up_hand(0, 0, 0) is None
True
>>> state.get_up_hand(1, 0, 0) is None
True

Pre-flop.

>>> state.deal_hole('AcAd')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad), statuse...
>>> state.deal_hole('KsQs')  
HoleDealing(commentary=None, player_index=1, cards=(Ks, Qs), statuse...
>>> state.get_up_hand(0, 0, 0) is None
True
>>> state.get_up_hand(1, 0, 0) is None
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('JsTs2c')
BoardDealing(commentary=None, cards=(Js, Ts, 2c))
>>> state.get_up_hand(0, 0, 0) is None
True
>>> state.get_up_hand(1, 0, 0) is None
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ah')
BoardDealing(commentary=None, cards=(Ah,))
>>> state.get_up_hand(0, 0, 0) is None
True
>>> state.get_up_hand(1, 0, 0) is None
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('As')
BoardDealing(commentary=None, cards=(As,))
>>> str(state.get_up_hand(0, 0, 0))
'One pair (JsTs2cAhAs)'
>>> str(state.get_up_hand(1, 0, 0))
'One pair (JsTs2cAhAs)'
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.get_up_hand(0, 0, 0) is None
True
>>> str(state.get_up_hand(1, 0, 0))
'Straight flush (KsQsJsTsAs)'

Parameters:

player_index – The player index.
board_index – The board index.
hand_type_index – The hand type index.

Returns:

The corresponding hand of the player.

get_up_hands(board_index: int, hand_type_index: int) → Iterator[Hand | None]

Return the optional corresponding hands from up cards.

Which hand type to evaluate must be provided through hand_type_index. Since they may be multiple boards, so does board_index. For how boards are indexed, please refer to pokerkit.state.State.get_board_cards().

The down cards are not considered here during hand evaluation.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100),
...     2,
... )
>>> state.get_up_hands(0, 0)  
<generator object State.get_up_hands at 0x...>
>>> tuple(state.get_up_hands(0, 0))
(None, None)

Pre-flop.

>>> state.deal_hole('AcAd')  
HoleDealing(commentary=None, player_index=0, cards=(Ac, Ad), statuse...
>>> state.deal_hole('KsQs')  
HoleDealing(commentary=None, player_index=1, cards=(Ks, Qs), statuse...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('JsTs2c')
BoardDealing(commentary=None, cards=(Js, Ts, 2c))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('Ah')
BoardDealing(commentary=None, cards=(Ah,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('As')
BoardDealing(commentary=None, cards=(As,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> tuple(state.get_up_hands(0, 0))
(JsTs2cAhAs, JsTs2cAhAs)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> tuple(state.get_up_hands(0, 0))
(None, KsQsJsTsAs)

Parameters:

board_index – The board index.
hand_type_index – The hand type index.

Returns:

The optional corresponding hands from up cards.

property hand_killing_indices: Iterator[int]

Iterate through players whose hands are to be killed.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     3,
... )

Pre-flop.

>>> state.deal_hole('JcJd')  
HoleDealing(commentary=None, player_index=0, cards=(Jc, Jd), statuse...
>>> state.deal_hole('QcQd')  
HoleDealing(commentary=None, player_index=1, cards=(Qc, Qd), statuse...
>>> state.deal_hole('KcKd')  
HoleDealing(commentary=None, player_index=2, cards=(Kc, Kd), statuse...
>>> state.complete_bet_or_raise_to(200)  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=199)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=198)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('AcAdAh')
BoardDealing(commentary=None, cards=(Ac, Ad, Ah))

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2c')
BoardDealing(commentary=None, cards=(2c,))
>>> state.hand_killing_indices  
<generator object State.hand_killing_indices at 0x...>
>>> tuple(state.hand_killing_indices)
()

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2d')
BoardDealing(commentary=None, cards=(2d,))
>>> tuple(state.hand_killing_indices)
(0, 1)

Returns:: The indices of players whose hands are to be killed.

hand_killing_statuses: list[bool]: The hand killing statuses.

property hand_type_count: int

Return the number of hand types.

Typically, this is 1. But, 2 hand types do get used for split-pot games.

>>> from pokerkit import (
...     FixedLimitOmahaHoldemHighLowSplitEightOrBetter,
...     NoLimitTexasHoldem,
... )
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.hand_type_count
1
>>> state = (
...     FixedLimitOmahaHoldemHighLowSplitEightOrBetter.create_state(
...         (),
...         True,
...         1,
...         (1, 2),
...         2,
...         4,
...         100,
...         3,
...     )
... )
>>> state.hand_type_count
2

Returns:: The number of hand types.

property hand_type_indices: range

Return the hand type indices.

>>> from pokerkit import (
...     FixedLimitOmahaHoldemHighLowSplitEightOrBetter,
...     NoLimitTexasHoldem,
... )
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.hand_type_indices
range(0, 1)
>>> state = (
...     FixedLimitOmahaHoldemHighLowSplitEightOrBetter.create_state(
...         (),
...         True,
...         1,
...         (1, 2),
...         2,
...         4,
...         100,
...         3,
...     )
... )
>>> state.hand_type_indices
range(0, 2)

Returns:: The hand type indices.

hand_types: tuple[type[Hand], ...]

The hand types.

While most poker games use just a single hand type, there exists variants where multiple hand types should be considered when evaluating hand strengths, namely in high/low-split contexts.

In PokerKit, each concept of high and low hands are separately considered, through the use of multiple hand types.

hole_card_statuses: list[list[bool]]

The player hole card statuses.

The corresponding hole card is an up card if True, and down if False.

hole_cards: list[list[Card]]

The player hole cards.

In PokerKit, the concept of hole cards is slightly warped as it includes both up and down cards (traditionally, only down cards are called interchangeably with hole cards).

property hole_dealee_index: int | None

Return the hole dealee index.

This index is that of the player in turn to be dealt the hole cards.

Of course, this may be overridden in the actual operation.

Returns:: The hole dealee index if applicable, otherwise None.

hole_dealing_statuses: list[deque[bool]]

The hole dealing statuses.

If an item is non-empty, hole dealings are pending for that player (up if True, down if False).

kill_hand(player_index: int | None = None, *, commentary: str | None = None) → HandKilling

Kill hand.

In real-life, this is performed by the dealer to “kill” and remove an irrelevant hand (i.e., cannot win anything) so that only the relevant hands (i.e., can win at least a portion of the pot) are left open prior to pushing the chips to the respective winner(s).

If the player is not specified, the first item of pokerkit.state.State.hand_killing_indices will be used.

Parameters:

player_index – The optional player index.
commentary – The optional commentary.

Returns:

The hand killing.

Raises:

ValueError – If the hand killing cannot be done.

property max_completion_betting_or_raising_to_amount: int | None

Return the maximum completion, betting, or raising to amount.

Returns:: The maximum completion, betting, or raising to amount if applicable, otherwise None.

property min_completion_betting_or_raising_to_amount: int | None

Return the minimum completion, betting, or raising to amount.

Returns:: The minimum completion, betting, or raising to amount if applicable, otherwise None.

mode: Mode = 'Tournament'

The mode. Defaults to tournament mode.

There are two modes available to be set: the tournament and cash-game mode. Tournaments use a stricter rule-set than typical cash-games. For more details, please consult pokerkit.state.Mode.

mucked_cards: list[Card]

The mucked cards.

Cards that are folded or mucked are added here. These may be used later to replenish the deck (should it run out).

no_operate(*, commentary: str | None = None) → NoOperation

No-operate.

Returns:: The no-operation.

opener_index: int | None = None

The opener index.

At the beginning of a betting round, this denotes who opened the round. If someone bets or raises, this attribute is updated to reflect who opened the betting round.

operations: list[Operation]

The operations that were applied to this state.

Each subsequent operation appends to this list.

payoffs: list[int]

The player payoffs.

Note that a payoff = stack - starting_stack for each player at the end of the hand.

Negated versions of these values can be thought of as contributions to the hand by the individual players.

player_count: int

The number of players.

This value must be at least 2.

property player_indices: range

Return the player indices.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.player_indices
range(0, 2)
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     True,
...     1,
...     (1, 2),
...     2,
...     200,
...     9,
... )
>>> state.player_indices
range(0, 9)

Returns:: The player indices.

post_ante(player_index: int | None = None, *, commentary: str | None = None) → AntePosting

Post the ante.

In this operation, a single player posts the ante.

The players who can post can be iterated through with pokerkit.state.State.ante_poster_indices. The first player in this iterable is posted if no player is specified.

Parameters:

player_index – The optional player index.
commentary – The optional commentary.

Returns:

The ante posting.

Raises:

ValueError – If the ante posting cannot be done.

post_blind_or_straddle(player_index: int | None = None, *, commentary: str | None = None) → BlindOrStraddlePosting

Post the blind or straddle of the player.

In this operation, a single player posts the blind/straddle.

The players who can post can be iterated through with pokerkit.state.State.blind_or_straddle_poster_indices. The first player in this iterable is posted if no player is specified.

Parameters:

player_index – The optional player index.
commentary – The optional commentary.

Returns:

The blind or straddle posting.

Raises:

ValueError – If the blind or straddle posting cannot be done.

post_bring_in(*, commentary: str | None = None) → BringInPosting

Post the bring-in.

The actor can be accessed through pokerkit.state.State.actor_index.

Parameters:: commentary – The optional commentary.
Returns:: The bring-in posting.
Raises:: ValueError – If the bring-in posting cannot be done.

property pot_amounts: Iterator[int]

Return the list of main and side pot amounts (if any).

The first pot (if any) is the main pot of this game. The subsequent pots are side pots.

The amounts returned are unraked.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100, 200, 1000, 200, 100),
...     6,
... )
>>> state.pot_amounts  
<generator object State.pot_amounts at 0x...>
>>> next(state.pot_amounts)
Traceback (most recent call last):
    ...
StopIteration
>>> tuple(state.pot_amounts)  
()

Pre-flop.

>>> state.complete_bet_or_raise_to(200)  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.complete_bet_or_raise_to(1000)  
Traceback (most recent call last):
    ...
ValueError: There is no reason to complete, bet, or raise since ever...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=3, amount=200)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=4, amount=200)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=5, amount=100)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=49)
>>> tuple(state.pot_amounts)
()
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=98)
>>> next(state.pot_amounts)
300
>>> pot_amounts = tuple(state.pot_amounts)
>>> len(pot_amounts)
3
>>> pot_amounts[0]
300
>>> pot_amounts[1]
250
>>> pot_amounts[2]
300

Flop.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(..., ..., ...))

Turn.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(...,))

River.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(...,))

Returns:: The list of main and side pot (if any) amounts.

property pot_completion_betting_or_raising_to_amount: int | None

Return the pot completion, betting, or raising to amount.

Returns:: The pot completion, betting, or raising to amount if applicable, otherwise None.

property pots: Iterator[Pot]

Return the list of main and side pots (if any).

The first pot (if any) is the main pot of this game. The subsequent pots are side pots (in the order they are formed).

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     True,
...     0,
...     (1, 2),
...     2,
...     (50, 100, 200, 1000, 200, 100),
...     6,
... )
>>> state.pots  
<generator object State.pots at 0x...>
>>> next(state.pots)
Traceback (most recent call last):
    ...
StopIteration
>>> tuple(state.pots)  
()

Pre-flop.

>>> state.complete_bet_or_raise_to(200)  
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount...
>>> state.complete_bet_or_raise_to(1000)  
Traceback (most recent call last):
    ...
ValueError: There is no reason to complete, bet, or raise since ever...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=3, amount=200)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=4, amount=200)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=5, amount=100)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=49)
>>> tuple(state.pots)
()
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=98)
>>> next(state.pots)  
Pot(raked_amount=0, unraked_amount=300, player_indices=(0, 1, 2, 3, ...
>>> pots = tuple(state.pots)
>>> len(pots)
3
>>> pots[0]  
Pot(raked_amount=0, unraked_amount=300, player_indices=(0, 1, 2, 3, ...
>>> pots[1]
Pot(raked_amount=0, unraked_amount=250, player_indices=(1, 2, 3, 4, 5))
>>> pots[2]
Pot(raked_amount=0, unraked_amount=300, player_indices=(2, 3, 4))

Flop.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(..., ..., ...))

Turn.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(...,))

River.

>>> state.deal_board()  
BoardDealing(commentary=None, cards=(...,))

Returns:: The list of main and side pots (if any).

pull_chips(player_index: int | None = None, *, commentary: str | None = None) → ChipsPulling

Pull chips.

Here, the won chips in front of a player is incorporated back into his/her stack.

If the player is not specified, the first item of pokerkit.state.State.chips_pulling_indices will be used.

Parameters:

player_index – The optional player index.
commentary – The optional commentary.

Returns:

The chips pulling.

Raises:

ValueError – If the chips pulling cannot be done.

push_chips(*, commentary: str | None = None) → ChipsPushing

Push chips.

Each call of this operation will push a single split main/side pot.

Parameters:: commentary – The optional commentary.
Returns:: The chips pushing.
Raises:: ValueError – If the chips pushing cannot be done.

rake(state: State | None = None, *, percentage: float = 0, cap: float = inf, no_flop_no_drop: bool = False) → tuple[int, int]

The rake function. Defaults to zero rake.

Rake functions are used in PokerKit to denote how the rakes are collected from the pot. Multiple pots may exist (side-pots) in which case the method is called for each pot.

The user may supply a custom rake function. This function must accept two positional arguments: the state and the amount to be raked. Its return value should be a tuple consisting of two values: the raked amount and the remaining, unraked amount.

raw_antes: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]

The “raw” antes.

In PokerKit, the term raw is used to denote the fact that they can be supplied in many forms and will be “parsed” or “evaluated” further to convert them into a more ideal form.

For instance, 0 will be interpreted as no ante for all players. A non-zero value will be interpreted as that value as the antes for all. [0, 2] and {1: 2} will be considered as the big blind ante whereas ``{-1: 2} will be considered as the button ante.

All ante values must be non-negative.

raw_blinds_or_straddles: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]

The “raw” blinds or straddles.

Just like for the antes, the blinds/straddles are also “interpreted” by PokerKit in the same fashion.

All blind/straddle values must be non-negative.

If the bring-in is non-zero, all blind/straddle values must be zero. If the bring-in and all of the antes are zero, there must be at least one positive blind/straddle value.

Negative value is interpreted as a post bet, used to denote what a player who just got seated pays to begin playing right away without waiting for the button.

raw_starting_stacks: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]

The “raw” starting stacks.

Similar to “raw” antes and “raw” blinds/straddles, the starting stacks can be represented in different ways which PokerKit interprets when creating the games. Not all representations (e.g., dict) explicitly defines the number of players and therefore this value is accepted as a separate parameter player_count.

All items must be positive and hence non-zero.

property reserved_cards: Iterator[Card]

Iterate through the reserved cards.

These are either in the burn, muck, or discards and used when the deck is empty.

Returns:: The reserved cards.

runout_count: int | None = None

The number of runouts.

This attribute reflects a concensus on the number of runouts selected by each player.

If no one selects a preference or the hand is never all-in by all those who are active, this value is None. If at least one person expresses a preference, a concensus is established and thus this value is not None.

runout_count_selection_flag: bool = False

The runout-count selector flag.

It is True if everyone had a chance to select the number of runouts.

property runout_count_selector_indices: Iterator[int]

Iterate through players who can select the runout-count.

Returns:: The runout-count selectors.

runout_count_selector_statuses: list[bool]

The runout-count selector statuses.

Each element denotes whether a player at that index is pending runout-count selection (True).

select_runout_count(runout_count: int | None = None, player_index: int | None = None, *, commentary: str | None = None) → RunoutCountSelection

Select the runout-count.

If the runout_count is None, it is considered to be “no-preference” (the decision is then deferred to other players).

The runout-count selection can be performed prior to or after the showing/mucking of the hole cards. Both are permitted by PokerKit.

If the player index is not specified, the first item of pokerkit.state.State.runout_count_selector_indices will be used.

Parameters:

runout_count – The number of runouts, defaults to None.
player_index – The optional player index.
commentary – The optional commentary.

Returns:

The runout-count selection.

Raises:

ValueError – If the runout-count selection cannot be done.

Show or muck hole cards.

If the status is of type bool, the hole cards of the showdown player will be mucked if it is False or shown if it is True.

if the cards are passed in, the known cards among them will be shown. Unknown cards or (incomplete known cards) means that some hole cards are to be kept face down. This is only valid in cash-game situations.

If the argument is not given (i.e., None), the hole cards will be shown if and only if there is a chance of winning the pot or it is an all-in situation. Otherwise, the hand will be mucked.

If the player index is not specified, it defaults to pokerkit.state.State.showdown_index.

Parameters:

status_or_hole_cards – The optional status or hole cards.
player_index – The optional player index to override the showdown order.
commentary – The optional commentary.

Returns:

The hole cards showing or mucking.

property showdown_index: int | None

Return the showdown index.

The index denotes who should show/muck their cards next.

Typically, in poker games, the showdown order is determined through action. The last bettor/raiser must show first.

In practice, it is encouraged for people who know they won for sure to show first. This means that the “ideal” (as in showing only when necessary) showdown order may deviate from the actually practiced showdown order.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...     ),
...     False,
...     0,
...     (1, 2),
...     2,
...     200,
...     3,
... )

Pre-flop.

>>> state.deal_hole('JcJd')  
HoleDealing(commentary=None, player_index=0, cards=(Jc, Jd), statuse...
>>> state.deal_hole('KcKd')  
HoleDealing(commentary=None, player_index=1, cards=(Kc, Kd), statuse...
>>> state.deal_hole('QcQd')  
HoleDealing(commentary=None, player_index=2, cards=(Qc, Qd), statuse...
>>> state.complete_bet_or_raise_to(6)
CompletionBettingOrRaisingTo(commentary=None, player_index=2, amount=6)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=5)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=4)

Flop.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('AcAdAh')
BoardDealing(commentary=None, cards=(Ac, Ad, Ah))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)

Turn.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2c')
BoardDealing(commentary=None, cards=(2c,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)

River.

>>> state.burn_card('??')
CardBurning(commentary=None, card=??)
>>> state.deal_board('2d')
BoardDealing(commentary=None, cards=(2d,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Showdown.

>>> state.showdown_index is None
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=2, amount=0)
>>> state.showdown_index
0
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=0, hole_card...
>>> state.showdown_index
1
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...
>>> state.showdown_index
2
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=2, hole_card...

Returns:: The showdown index if applicable, otherwise None.

showdown_indices: deque[int]

The showdown indices.

The items also reflect a showdown order.

stacks: list[int]: The player stacks.

stand_pat_or_discard(cards: Iterable[Card] | Card | str = (), *, commentary: str | None = None) → StandingPatOrDiscarding

Stand pat or discard hole cards.

The specified cards (if any) should be a subset of the player’s hole cards.

The player currently standing pat/discarding can be accessed via pokerkit.state.State.stander_pat_or_discarder_index.

After the standing pat or discarding is done for all pending players, their hole should be replenished by the subsequent hole dealing operations to each player.

Parameters:

cards – The optional discarded cards.
commentary – The optional commentary.

Returns:

The standing pat or discarding, defaults to empty.

Raises:

ValueError – If the discard cannot be done.

property stander_pat_or_discarder_index: int | None

Return the stander pat or discarder index.

Returns:: The stander pat or discarder index if applicable, otherwise None.

standing_pat_or_discarding_statuses: list[bool]

The standing pat or discarding statuses.

If an item is True, then the player should perform a draw action (or stand pat).

starting_board_count: int = 1

The number of boards at the start of the game. Defaults to 1.

For most poker games, it should be 1. Of course, for double board games, it should be 2. Triple/Quadruple/etc. board games are almost unheard of. Therefore, this value should mostly be 1 or sometimes 2.

The actual number of boards may change depending on the number of runouts (during all-ins).

This value must be positive.

starting_stacks: tuple[int, ...]

The starting stacks.

This value is the “interpreted” version of the “raw” starting stacks.

status: bool = True

The game status.

True if the state is not terminal. If it is not terminal, some operation can still be performed.

statuses: list[bool]

The player statuses.

If the corresponding item is True, the player at that index is still “in the hand”.

property street: Street | None

Return the current street.

None is returned if the state is terminal or in showdown.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.street is None
True

Setup.

>>> state.post_ante(0)
AntePosting(commentary=None, player_index=0, amount=2)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(2, 0))
>>> state.post_blind_or_straddle(0)
BlindOrStraddlePosting(commentary=None, player_index=0, amount=2)
>>> state.street is None
True
>>> state.post_blind_or_straddle(1)
BlindOrStraddlePosting(commentary=None, player_index=1, amount=1)
>>> state.street is state.streets[0]
True
>>> state.street  
Street(card_burning_status=False, hole_dealing_statuses=(False, Fals...

Pre-flop.

>>> state.deal_hole('Ac')  
HoleDealing(commentary=None, player_index=0, cards=(Ac,), statuses=(...
>>> state.deal_hole('Kc')  
HoleDealing(commentary=None, player_index=1, cards=(Kc,), statuses=(...
>>> state.deal_hole('Ad')  
HoleDealing(commentary=None, player_index=0, cards=(Ad,), statuses=(...
>>> state.deal_hole('Kd')  
HoleDealing(commentary=None, player_index=1, cards=(Kd,), statuses=(...
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.street is state.streets[0]
True
>>> state.collect_bets()
BetCollection(commentary=None, bets=(2, 2))
>>> state.street is state.streets[1]
True

Flop.

>>> state.burn_card('2c')
CardBurning(commentary=None, card=2c)
>>> state.deal_board('AhKhAs')
BoardDealing(commentary=None, cards=(Ah, Kh, As))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.street is state.streets[1]
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.street is state.streets[2]
True

Turn.

>>> state.burn_card('2d')
CardBurning(commentary=None, card=2d)
>>> state.deal_board('Ks')
BoardDealing(commentary=None, cards=(Ks,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.street is state.streets[2]
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.street is state.streets[3]
True

River.

>>> state.burn_card('2h')
CardBurning(commentary=None, card=2h)
>>> state.deal_board('2s')
BoardDealing(commentary=None, cards=(2s,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.street is state.streets[3]
True
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> state.street is state.streets[3]
True

Showdown.

>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=0, hole_card...
>>> state.street is state.streets[3]
True
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...
>>> state.street is None
True

Teardown.

>>> state.push_chips()  
ChipsPushing(commentary=None, amounts=(6, 0), pot_index=0, board_ind...
>>> state.street is None
True
>>> state.pull_chips()
ChipsPulling(commentary=None, player_index=0, amount=6)
>>> state.street is None
True

>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.street is state.streets[0]
True
>>> state.fold()
Folding(commentary=None, player_index=1)
>>> state.street is None
True

Returns:: The street if applicable, otherwise None.

property street_count: int

Return the number of streets.

Returns:: The number of streets.

street_index: int | None = None

The street index.

If it is not None, it denotes what street the state is at currently. The actual street instance can be accessed through pokerkit.state.State.street.

property street_indices: range

Return the street indices.

Returns:: The street indices.

street_return_count: int | None = 0

The street return count.

This is non-zero if there are pending runouts not underway already.

This value gets decremented before the start of each runout.

street_return_index: int | None = None

The street return index.

This is not None if and only if multiple runouts are performed/performing.

streets: tuple[Street, ...]

The streets.

Each street contains information about the corresponding betting round and corresponding dealing/draw stage before it occurs.

This attribute must be non-empty and its first item must be of hole-dealing.

property total_pot_amount: int

Return the total pot amount (unraked).

This value also includes the outstanding bets.

>>> from pokerkit import NoLimitTexasHoldem
>>> state = NoLimitTexasHoldem.create_state(
...     (),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.total_pot_amount
0

Setup.

>>> state.post_ante(0)
AntePosting(commentary=None, player_index=0, amount=2)
>>> state.total_pot_amount
2
>>> state.collect_bets()
BetCollection(commentary=None, bets=(2, 0))
>>> state.total_pot_amount
2
>>> state.post_blind_or_straddle(0)
BlindOrStraddlePosting(commentary=None, player_index=0, amount=2)
>>> state.total_pot_amount
4
>>> state.post_blind_or_straddle(1)
BlindOrStraddlePosting(commentary=None, player_index=1, amount=1)
>>> state.total_pot_amount
5

Pre-flop.

>>> state.deal_hole('Ac')  
HoleDealing(commentary=None, player_index=0, cards=(Ac,), statuses=(...
>>> state.deal_hole('Kc')  
HoleDealing(commentary=None, player_index=1, cards=(Kc,), statuses=(...
>>> state.deal_hole('Ad')  
HoleDealing(commentary=None, player_index=0, cards=(Ad,), statuses=(...
>>> state.deal_hole('Kd')  
HoleDealing(commentary=None, player_index=1, cards=(Kd,), statuses=(...
>>> state.total_pot_amount
5
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=1)
>>> state.total_pot_amount
6
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(2, 2))

Flop.

>>> state.burn_card('2c')
CardBurning(commentary=None, card=2c)
>>> state.deal_board('AhKhAs')
BoardDealing(commentary=None, cards=(Ah, Kh, As))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Turn.

>>> state.burn_card('2d')
CardBurning(commentary=None, card=2d)
>>> state.deal_board('Ks')
BoardDealing(commentary=None, cards=(Ks,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.total_pot_amount
6
>>> state.complete_bet_or_raise_to(10)  
CompletionBettingOrRaisingTo(commentary=None, player_index=1, amount...
>>> state.total_pot_amount
16
>>> state.complete_bet_or_raise_to(30)  
CompletionBettingOrRaisingTo(commentary=None, player_index=0, amount...
>>> state.total_pot_amount
46
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=20)
>>> state.collect_bets()
BetCollection(commentary=None, bets=(30, 30))
>>> state.total_pot_amount
66

River.

>>> state.burn_card('2h')
CardBurning(commentary=None, card=2h)
>>> state.deal_board('2s')
BoardDealing(commentary=None, cards=(2s,))
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=0, amount=0)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)

Showdown.

>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=0, hole_card...
>>> state.show_or_muck_hole_cards()  
HoleCardsShowingOrMucking(commentary=None, player_index=1, hole_card...

Teardown.

>>> state.push_chips()  
ChipsPushing(commentary=None, amounts=(66, 0), pot_index=0, board_in...
>>> state.total_pot_amount
66
>>> state.pull_chips()
ChipsPulling(commentary=None, player_index=0, amount=66)
>>> state.total_pot_amount
0

>>> state = NoLimitTexasHoldem.create_state(
...     (
...         Automation.ANTE_POSTING,
...         Automation.BET_COLLECTION,
...         Automation.BLIND_OR_STRADDLE_POSTING,
...         Automation.CARD_BURNING,
...         Automation.HOLE_DEALING,
...         Automation.BOARD_DEALING,
...         Automation.HOLE_CARDS_SHOWING_OR_MUCKING,
...         Automation.HAND_KILLING,
...         Automation.CHIPS_PUSHING,
...         Automation.CHIPS_PULLING,
...     ),
...     False,
...     (0, 2),
...     (1, 2),
...     2,
...     200,
...     2,
... )
>>> state.total_pot_amount
5
>>> state.fold()
Folding(commentary=None, player_index=1)
>>> state.total_pot_amount
0

Returns:: The total pot amount.

property turn_index: int | None

Return the turn index.

Regardless of what stage the state is in, whoever must make a decision will be returned, which is one of the following:

pokerkit.state.State.stander_pat_or_discarder_index
pokerkit.state.State.actor_index
pokerkit.state.State.showdown_index

This is a very useful property…. please use this!

Returns:: The index of the player who is in turn, or None if no one is in turn.

verify_ante_posting(player_index: int | None = None) → int

Verify the ante posting.

For more details on this operation, please consult the method pokerkit.state.State.post_ante().

Parameters:: player_index – The optional player index.
Returns:: The anteing player index.
Raises:: ValueError – If the ante posting cannot be done.

verify_bet_collection() → None

Verify the bet collection.

For more details on this operation, please consult the method pokerkit.state.State.collect_bets().

Returns:: None.
Raises:: ValueError – If the bet collection cannot be done.

verify_blind_or_straddle_posting(player_index: int | None = None) → int

Verify the blind or straddle posting.

For more details on this operation, please consult the method pokerkit.state.State.post_blind_or_straddle().

Parameters:: player_index – The optional player index.
Returns:: The blinding or straddling player index.
Raises:: ValueError – If blind or straddle posting cannot be done.

verify_board_dealing(cards: Iterable[Card] | Card | str | int | None = None) → tuple[Card, ...]

Verify the board dealing.

For more details on this operation, please consult the method pokerkit.state.State.deal_board().

Parameters:: cards – The optional cards.
Returns:: The dealt board cards.
Raises:: ValueError – If the board dealing cannot be done.

verify_bring_in_posting() → None

Verify the bring-in posting.

For more details on this operation, please consult the method pokerkit.state.State.post_bring_in().

Returns:: None.
Raises:: ValueError – If the bring-in posting cannot be done.

verify_card_burning(card: Iterable[Card] | Card | str | None = None) → Card

Verify the card burning.

For more details on this operation, please consult the method pokerkit.state.State.burn_card().

Parameters:: card – The optional card.
Returns:: The burn card.
Raises:: ValueError – If the card burning cannot be done.

verify_checking_or_calling() → None

Verify the checking or calling.

For more details on this operation, please consult the method pokerkit.state.State.check_or_call().

Returns:: None.
Raises:: ValueError – If the checking or calling cannot be done.

verify_chips_pulling(player_index: int | None = None) → int

Verify the chips pulling.

For more details on this operation, please consult the method pokerkit.state.State.pull_chips().

Parameters:: player_index – The optional player index.
Returns:: The chips pulling index.
Raises:: ValueError – If the chips pulling cannot be done.

verify_chips_pushing() → None

Verify the chips pushing.

For more details on this operation, please consult the method pokerkit.state.State.push_chips().

Returns:: None.
Raises:: ValueError – If the chips pushing cannot be done.

verify_completion_betting_or_raising_to(amount: int | None = None) → int

Verify the completion, betting, or raising to operation.

For more details on this operation, please consult the method pokerkit.state.State.complete_bet_or_raise_to().

Parameters:: amount – The optional completion, betting, or raising to amount.
Returns:: The completion, betting, or raising to amount.
Raises:: ValueError – If the completion, betting, or raising cannot be done.

verify_folding() → None

Verify the folding.

For more details on this operation, please consult the method pokerkit.state.State.fold().

Returns:: None.
Raises:: ValueError – If the folding cannot be done.

verify_hand_killing(player_index: int | None = None) → int

Verify the hand killing.

For more details on this operation, please consult the method pokerkit.state.State.kill_hand().

Parameters:: player_index – The optional player index.
Returns:: The hand killing index.
Raises:: ValueError – If the hand killing cannot be done.

Verify the hole card showing or mucking.

For more details on this operation, please consult the method pokerkit.state.State.show_or_muck_hole_cards().

Parameters:

status_or_hole_cards – The optional status or hole cards.
player_index – The optional player index to override the showdown order.

Returns:

The status, what cards are shown, new hole cards, new hole card statuses, and player index.

Raises:

ValueError – If hole card showing or mucking cannot be done.

Verify the hole dealing.

For more details on this operation, please consult the method pokerkit.state.State.deal_hole().

Parameters:

cards – The optional cards.
player_index – The optional target dealee.

Returns:

The dealt hole cards.

Raises:

ValueError – If the hole dealing cannot be done.

verify_no_operation() → None

Verify the no-operation.

For more details on this operation, please consult the method pokerkit.state.State.no_operate().

Returns:: None.

verify_runout_count_selection(runout_count: int | None = None, player_index: int | None = None) → int

Verify the runout-count selection.

For more details on this operation, please consult the method pokerkit.state.State.select_runout_count().

Parameters:

runout_count – The number of runouts, defaults to None.
player_index – The optional player index.

Returns:

The selecting player index.

Raises:

ValueError – If the runout-count selection cannot be done.

verify_standing_pat_or_discarding(cards: Iterable[Card] | Card | str = ()) → tuple[Card, ...]

Verify the discard.

For more details on this operation, please consult the method pokerkit.state.State.stand_pat_or_discard().

Parameters:: cards – The discarded cards, defaults to empty.
Returns:: The discarded cards.
Raises:: ValueError – If the discard cannot be done.

class pokerkit.state.Street(card_burning_status: bool, hole_dealing_statuses: tuple[bool, ...], board_dealing_count: int, draw_status: bool, opening: Opening, min_completion_betting_or_raising_amount: int, max_completion_betting_or_raising_count: int | None)

Bases: object

The class for streets.

Street encodes information about various properties of a corresponding betting round.

Each street must perform at least a draw or card dealings.

>>> street = Street(
...     False,  # no card burning
...     (False, False),  # deal 2 down cards
...     0,  # Deal no board card
...     False,  # No draws
...     Opening.POSITION,  # Opener decided by position
...     2,  # 2 is the min-bet
...     None,  # unlimited number of bet/raises
... )
>>> street.card_burning_status
False
>>> street.hole_dealing_statuses
(False, False)

Parameters:

card_burning_status – Whether to burn card (True if this is so). For more information, please refer to pokerkit.state.Street.card_burning_status.
hole_dealing_statuses – The statuses of dealt hole cards. For more information, please refer to pokerkit.state.Street.hole_dealing_statuses.
board_dealing_count – The number of dealt board cards (0 if none). For more information, please refer to pokerkit.state.Street.board_dealing_count.
draw_status – Whether to draw cards prior to betting (True if this is so). For more information, please refer to pokerkit.state.Street.draw_status.
opening – The opening. For more information, please refer to pokerkit.state.Street.opening.
min_completion_betting_or_raising_amount – The minimum completion, betting, or raising amount. For more information, please refer to pokerkit.state.Street.min_completion_betting_or_raising_amount.
max_completion_betting_or_raising_count – The maximum number of completions, bettings, or raisings. For more information, please refer to pokerkit.state.Street.max_completion_betting_or_raising_count.

Raises:

ValueError – If the arguments are invalid.

board_dealing_count: int

The number of dealt board cards (0 if none).

This number of cards is dealt for each board (for multi-board games).

If there is no hole dealing and no drawing, this value should be non-zero (i.e., positive).

card_burning_status: bool: Whether to burn a card (True if this is so).

draw_status: bool

Whether to draw cards prior to betting (True if this is so).

This flag is mutually exclusive with the enabling of hole dealings. In other words, if this is True, pokerkit.state.Street.hole_dealing_statuses should be ().

If there is no hole dealing and no board dealing, this value should be True.

hole_dealing_statuses: tuple[bool, ...]

The statuses of dealt hole cards.

The length of this tuple denotes the number of hole cards dealt in the current street. Each item denotes whether to deal a card as an up card (True) or a down card (False).

If there is no board dealing and no drawing, this value should be non-empty. If drawing, this should be left empty.

max_completion_betting_or_raising_count: int | None: The maximum number of completions, bettings, or raisings.

min_completion_betting_or_raising_amount: int: The minimum completion, betting, or raising amount.

opening: Opening

The opening.

It decides who acts first on each betting round.

pokerkit.utilities module

pokerkit.utilities implements classes related to poker utilities.

These utilities (helper constants, functions, classes, methods, etc.) are used throughout the PokerKit project.

class pokerkit.utilities.Card(rank: Rank, suit: Suit)

Bases: object

The class for cards.

Cards are described by their ranks and their suits.

Cards with higher ranks are considered stronger than those with lower ranks. Of course, the rank ordering is variant-dependant. Ties are broken by suits in some rare variants (for more details, please see pokerkit.utilities.Card.

>>> card = Card(Rank.ACE, Suit.SPADE)
>>> card
As
>>> str(card)
'ACE OF SPADES (As)'
>>> card.rank
<Rank.ACE: 'A'>
>>> card.suit
<Suit.SPADE: 's'>

In PokerKit, the card attributes are read-only (i.e., immutable)…

>>> card.rank = Rank.KING
Traceback (most recent call last):
    ...
dataclasses.FrozenInstanceError: cannot assign to field 'rank'

…and hence hashable.

>>> from collections.abc import Hashable
>>> isinstance(card, Hashable)
True

Parameters:

rank – The rank. For more details, please refer to pokerkit.utilities.Card.rank.
suit – The suit. For more details, please refer to pokerkit.utilities.Card.suit.

UNKNOWN: ClassVar[Card] = ??: An unknown card. This is a class variable.

classmethod are_paired(cards: Iterable[Card] | Card | str) → bool

Return the pairedness of the given cards.

The cards are paired if at least two of the cards share a common rank.

>>> Card.are_paired(())
False
>>> Card.are_paired('2sKh')
False
>>> Card.are_paired('2sKh2h')
True
>>> Card.are_paired('2s2c2h')
True

Parameters:: cards – The cards to determine the pairedness from.
Returns:: The pairedness of the cards.

classmethod are_rainbow(cards: Iterable[Card] | Card | str) → bool

Return whether the cards are rainbow.

The cards are rainbow if no two cards share a common suit.

>>> Card.are_rainbow(())
True
>>> Card.are_rainbow('2s')
True
>>> Card.are_rainbow('2sKh3c')
True
>>> Card.are_rainbow('2hKh3c')
False

Parameters:: cards – The cards to determine whether they are rainbow.
Returns:: True if the cards are rainbow, otherwise False.

classmethod are_suited(cards: Iterable[Card] | Card | str) → bool

Return the suitedness of the given cards.

The cards are suited if all of the cards share a common suit.

>>> Card.are_suited(())
True
>>> Card.are_suited('2s')
True
>>> Card.are_suited('2sKh3s')
False
>>> Card.are_suited('2hKh3h')
True

Parameters:: cards – The cards to determine the suitedness from.
Returns:: The suitedness of the cards.

classmethod clean(values: Iterable[Card] | Card | str) → tuple[Card, ...]

Clean the cards.

This method “cleans” any cards-like object (e.g., raw string representations, a single card instance, etc.) into a tuple of card instances.

>>> Card.clean('AsKs')
(As, Ks)
>>> Card.clean('AsKs')
(As, Ks)
>>> Card.clean(Card(Rank.ACE, Suit.SPADE))
(As,)
>>> Card.clean(None)
Traceback (most recent call last):
    ...
ValueError: The card values None are invalid.

Parameters:: values – The cards.
Returns:: The cleaned cards.

classmethod get_ranks(cards: Iterable[Card] | Card | str) → Iterator[Rank]

Return an iterator of the ranks of each card.

>>> Card.get_ranks('2sKh')  
<generator object Card.get_ranks at 0x...>
>>> list(Card.get_ranks('2sKh'))
[<Rank.DEUCE: '2'>, <Rank.KING: 'K'>]

Parameters:: cards – The cards to get ranks from.
Returns:: The iterator of the ranks of each card.

classmethod get_suits(cards: Iterable[Card] | Card | str) → Iterator[Suit]

Return an iterator of the suits of each card.

>>> Card.get_suits('2sKh')  
<generator object Card.get_suits at 0x...>
>>> list(Card.get_suits('2sKh'))
[<Suit.SPADE: 's'>, <Suit.HEART: 'h'>]

Parameters:: cards – The cards to get suits from.
Returns:: The iterator of the suits of each card.

classmethod parse(*raw_cards: str) → Iterator[Card]

Parse the string of the card representations.

This returns a generator of the parsed card instances.

>>> Card.parse('AsKsQsJsTs')  
<generator object Card.parse at 0x...>

The generator can be consumed completely to obtain a list of cards.

>>> list(Card.parse('2c8d5sKh'))
[2c, 8d, 5s, Kh]
>>> list(Card.parse('2c, 8d, 5s, Kh'))
[2c, 8d, 5s, Kh]

Calling next will consume a single element from the generator.

>>> next(Card.parse('AcAh'))
Ac

Errors are raised when invalid card representations are encountered.

>>> next(Card.parse('AcA'))  
Traceback (most recent call last):
    ...
ValueError: The sum of the lengths of valid card representations mus...
>>> next(Card.parse('1d'))
Traceback (most recent call last):
    ...
ValueError: '1' is not a valid Rank
>>> next(Card.parse('Ax'))
Traceback (most recent call last):
    ...
ValueError: 'x' is not a valid Suit

Parameters:: raw_cards – The string of the card representations.
Returns:: The generator yielding the parsed cards.
Raises:: ValueError – If any card representation is invalid.

rank: Rank: The rank of the card.

suit: Suit: The suit of the card.

property unknown_status: bool

Return the unknown-ness of the card.

A card is “unknown” if both or either one of its rank or suit is unknown.

Returns:: The unknown-ness of the card.

pokerkit.utilities.CardsLike = collections.abc.Iterable[pokerkit.utilities.Card] | pokerkit.utilities.Card | str: A union of cards-like types. Each of these types can be “cleaned” by the pokerkit.utilities.Card.clean() class method.

class pokerkit.utilities.Deck(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: tuple[Card, …], Enum

The enum class for a tuple of cards representing decks.

Most poker games use the 52-card standard deck, denoted as Deck.STANDARD.

>>> len(Deck.STANDARD)
52
>>> Deck.STANDARD[:6]
(2c, 2d, 2h, 2s, 3c, 3d)

However, short-deck hold’em uses a 36-card short deck where cards with ranks from 2 to 5 (inclusive) are missing. This particular deck is accessible via Deck.SHORT_DECK_HOLDEM.

>>> len(Deck.SHORT_DECK_HOLDEM)
36
>>> Deck.SHORT_DECK_HOLDEM[:6]
(6c, 6d, 6h, 6s, 7c, 7d)

The members of Deck are tuples and cannot be modified. To use it effectively, you must make a copy with a different data type like list or deque.

>>> Deck.STANDARD[3] = Card(Rank.ACE, Suit.SPADE)
Traceback (most recent call last):
    ...
TypeError: 'Deck' object does not support item assignment
>>> deck = list(Deck.STANDARD)
>>> deck[3] = Card(Rank.ACE, Suit.SPADE)
>>> deck[:6]
[2c, 2d, 2h, As, 3c, 3d]

The standard and regular decks have identical contents; however, the ordering of the cards are different.

>>> len(Deck.STANDARD)
52
>>> len(Deck.REGULAR)
52
>>> Deck.STANDARD[:6]
(2c, 2d, 2h, 2s, 3c, 3d)
>>> Deck.REGULAR[:6]
(Ac, Ad, Ah, As, 2c, 2d)

KUHN_POKER: tuple[Card, ...] = (Js, Qs, Ks)

The 3-card Kuhn poker deck cards.

The cards in it are jack of spades, queen of spades, and king of spades.

REGULAR: tuple[Card, ...] = (Ac, Ad, Ah, As, 2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks)

The 52-card regular deck cards.

The ranks are ordered from aces to kings.

ROYAL_POKER: tuple[Card, ...] = (Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The 20-card royal poker deck cards.

The cards in it are ten, jack, queen, king, and ace of each suit.

SHORT_DECK_HOLDEM: tuple[Card, ...] = (6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The 36-card short-deck hold’em cards.

In this deck, deuces to fives are stripped away.

STANDARD: tuple[Card, ...] = (2c, 2d, 2h, 2s, 3c, 3d, 3h, 3s, 4c, 4d, 4h, 4s, 5c, 5d, 5h, 5s, 6c, 6d, 6h, 6s, 7c, 7d, 7h, 7s, 8c, 8d, 8h, 8s, 9c, 9d, 9h, 9s, Tc, Td, Th, Ts, Jc, Jd, Jh, Js, Qc, Qd, Qh, Qs, Kc, Kd, Kh, Ks, Ac, Ad, Ah, As)

The 52-card standard deck cards.

The ranks are ordered from deuces to aces.

class pokerkit.utilities.Rank(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for ranks.

The ordering of the ranks is decided in accordance to the rules of the poker variant being played. A card of lower rank is said to be less than that of a higher rank.

An enum element can be accessed through the following two ways:

>>> Rank.DEUCE
<Rank.DEUCE: '2'>
>>> Rank('2')
<Rank.DEUCE: '2'>

A rank’s single-character representation and full name can also be accessed.

>>> Rank.DEUCE.name
'DEUCE'
>>> Rank.DEUCE.value
'2'

ACE: str = 'A': The rank of aces.

DEUCE: str = '2': The rank of deuces.

EIGHT: str = '8': The rank of eights.

FIVE: str = '5': The rank of fives.

FOUR: str = '4': The rank of fours.

JACK: str = 'J': The rank of Jacks.

KING: str = 'K': The rank of Kings.

NINE: str = '9': The rank of nines.

QUEEN: str = 'Q': The rank of Queens.

SEVEN: str = '7': The rank of sevens.

SIX: str = '6': The rank of sixes.

TEN: str = 'T': The rank of tens.

TREY: str = '3': The rank of treys.

UNKNOWN: str = '?': The unknown rank.

class pokerkit.utilities.RankOrder(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: tuple[Rank, …], Enum

The enum class for ordering of ranks.

Poker variants order the ranks differently between each other. Most games use deuce to ace ordering which is defined here as RankOrder.STANDARD.

>>> len(RankOrder.STANDARD)
13
>>> RankOrder.STANDARD[0]
<Rank.DEUCE: '2'>
>>> RankOrder.STANDARD[-1]
<Rank.ACE: 'A'>

Short-deck hold’em uses its own ranking which eliminates deuces, treys, fours, and fives, defined here as RankOrder.SHORT_DECK_HOLDEM.

>>> len(RankOrder.SHORT_DECK_HOLDEM)
9
>>> RankOrder.SHORT_DECK_HOLDEM[0]
<Rank.SIX: '6'>
>>> RankOrder.SHORT_DECK_HOLDEM[-1]
<Rank.ACE: 'A'>

In some draw or low games, Ace is considered to be the lowest rank. This ordering is accessible via RankOrder.REGULAR.

>>> len(RankOrder.REGULAR)
13
>>> RankOrder.REGULAR[0]
<Rank.ACE: 'A'>
>>> RankOrder.REGULAR[-1]
<Rank.KING: 'K'>

Eight-or-better low ranks are used for some split-pot games.

>>> len(RankOrder.EIGHT_OR_BETTER_LOW)
8
>>> RankOrder.EIGHT_OR_BETTER_LOW[0]
<Rank.ACE: 'A'>
>>> RankOrder.EIGHT_OR_BETTER_LOW[-1]
<Rank.EIGHT: '8'>

EIGHT_OR_BETTER_LOW: tuple[Rank, ...] = (Rank.ACE, Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT): The eight or better low ranks (from ace to eight).

KUHN_POKER: tuple[Rank, ...] = (Rank.JACK, Rank.QUEEN, Rank.KING): The Kuhn poker ranks (from jack to king).

REGULAR: tuple[Rank, ...] = (Rank.ACE, Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING): The regular ranks (from ace to king).

ROYAL_POKER: tuple[Rank, ...] = (Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The royal poker ranks (from ten to king).

SHORT_DECK_HOLDEM: tuple[Rank, ...] = (Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The short-deck hold’em ranks (from six to ace).

STANDARD: tuple[Rank, ...] = (Rank.DEUCE, Rank.TREY, Rank.FOUR, Rank.FIVE, Rank.SIX, Rank.SEVEN, Rank.EIGHT, Rank.NINE, Rank.TEN, Rank.JACK, Rank.QUEEN, Rank.KING, Rank.ACE): The standard ranks (from deuce to ace).

class pokerkit.utilities.Suit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

The enum class for suits.

As in the case of every poker games, the suit’s ordering is clubs, diamonds, hearts, and spades, which is also alphabetical.

In most poker variants, suits are completely irrelevant and are never used to break ties or to decide the winner (this is the case for PokerKit).

In stud games, suits are used to break ties when deciding the opener when there are multiple up cards with the same rank.

An enum element can be accessed through the following two ways:

>>> Suit.CLUB
<Suit.CLUB: 'c'>
>>> Suit('c')
<Suit.CLUB: 'c'>

A suit’s single-character representation and full name can also be accessed.

>>> Suit.CLUB.name
'CLUB'
>>> Suit.CLUB.value
'c'

CLUB: str = 'c': The suit of clubs.

DIAMOND: str = 'd': The suit of diamonds.

HEART: str = 'h': The suit of hearts.

SPADE: str = 's': The suit of spades.

UNKNOWN: str = '?': The unknown suit.

pokerkit.utilities.UNMATCHABLE_PATTERN: Pattern[str] = re.compile('(?!)'): A regular expression pattern that can never be matched.

pokerkit.utilities.ValuesLike = collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int: A union of values-like types. Each of these types can be “cleaned” by the pokerkit.utilities.clean_values() function.

pokerkit.utilities.clean_values(values: Iterable[int] | Mapping[int, int] | int, count: int) → tuple[int, ...]

Clean the numerical values.

This function “cleans” any values-like object (e.g., iterables, mappings, an number, etc.) into a tuple of numerical values.

>>> clean_values([1, 2, 3, 4], 4)
(1, 2, 3, 4)
>>> clean_values([1, 2, 3, 4], 6)
(1, 2, 3, 4, 0, 0)
>>> clean_values({0: 1, -1: 2}, 4)
(1, 0, 0, 2)
>>> clean_values(4, 4)
(4, 4, 4, 4)
>>> clean_values((1, 2, 3), 2)
(1, 2)
>>> clean_values(None, 2)
Traceback (most recent call last):
    ...
ValueError: The values None are invalid.

Parameters:

values – The values.
count – The number of values.

Returns:

The cleaned numerical values.

Raises:

ValueError – If the values are invalid.

pokerkit.utilities.divmod(dividend: int, divisor: int) → tuple[int, int]

Divide the amount and get its quotient and remainder.

>>> divmod(11, 3)
(3, 2)
>>> divmod(11.0, 3)  
(3.666666666666666..., 0.0)

Parameters:

dividend – The pot amount.
divisor – The number of players.

Returns:

The quotient and the remainder.

pokerkit.utilities.filter_none(values: Iterable[Any]) → Any

Filter out None from an iterable of values.

>>> filter_none([1, 2, None, 3])  
<filter object at 0x...>
>>> list(filter_none([1, 2, None, 3]))
[1, 2, 3]

Parameters:: values – The optional values.
Returns:: The filtered values.

pokerkit.utilities.max_or_none(values: Iterable[Any], key: Any = None) → Any

Get the maximum value while ignoring None values.

If the iterable of values are empty, None is returned.

>>> max_or_none([1, 2, 3, -2, -1])
3
>>> max_or_none([1, None, 2, None, 3, -2, -1, None])
3
>>> max_or_none([]) is None
True

Parameters:

values – The optional values.
key – The optional key function.

Returns:

The maximum value. If the values are empty, None.

pokerkit.utilities.min_or_none(values: Iterable[Any], key: Any = None) → Any

Get the minimum value while ignoring None values.

If the iterable of values are empty, None is returned.

>>> min_or_none([1, 2, 3, -2, -1])
-2
>>> min_or_none([1, None, 2, None, 3, -2, -1, None])
-2
>>> min_or_none([]) is None
True

Parameters:

values – The optional values.
key – The optional key function.

Returns:

The minimum value. If the values are empty, None.

pokerkit.utilities.parse_month(raw_month: str) → int

Convert str to a month (int).

>>> parse_month('July')
7
>>> parse_month('december')
12

Parameters:: raw_month – The raw month.
Returns:: The converted month.

pokerkit.utilities.parse_time(raw_time: str) → time

Convert str to a datetime.time.

>>> parse_time('12:34:56')
datetime.time(12, 34, 56)

Parameters:: raw_time – The raw time.
Returns:: The converted time.

pokerkit.utilities.parse_value(raw_value: str) → int

Convert str to a numerical value.

If integral, an int instance is returned. Otherwise, a decimal.Decimal instance is returned.

>>> parse_value('3')
3
>>> parse_value('3.0')
Decimal('3.0')
>>> parse_value('3.5')
Decimal('3.5')
>>> parse_value('9,999.99')
Decimal('9999.99')

Parameters:: raw_value – The raw numerical value.
Returns:: The converted numerical value.

pokerkit.utilities.rake(amount: int, state: State | None = None, *, percentage: float = 0, cap: float = inf, no_flop_no_drop: bool = False) → tuple[int, int]

Rake the amount.

This is a default raking function used by PokerKit (which defaults to not raking anything). Through methods like functools.partial, parameters like the rake percentage, cap, and no-flop-no-drop can be overridden.

Note that the percentage value is expected to be within range [0, 1]. For instance, 0.1 represents 10%.

If no_flop_no_drop is enabled, this means that a rake will only be collected if a flop is dealt. Since PokerKit caters to many variants, we interpret this as being that there exists at least one card on the board. Some variants do not involve board cards, so if this parameter is set to True, no rake will be raked whatsoever.

>>> rake(100)
(0, 100)
>>> rake(1000, percentage=0.1)
(100, 900)
>>> rake(10, percentage=0.11)
(1, 9)
>>> rake(10.0, percentage=0.11)
(1.1, 8.9)
>>> rake(10.0, percentage=0.11, cap=1.0)
(1.0, 9.0)
>>> rake(100, percentage=0.1, no_flop_no_drop=True)  
Traceback (most recent call last):
    ...
ValueError: If no-flop-no-drop is enabled, the state must be checked, bu...

When this function is actually called, the state parameter will not be None as it is by default. This argument can be used to encode a more complicated raking logic.

During state creation, user can supply their own rake function, corresponding with the accepted type signature.

Parameters:

amount – The pot amount.
state – The optional poker state whose pot is being raked.
percentage – The rake percentage, defaults to 0. It should be between 0 (0%) and 1 (100%).
cap – The maximum raked amount, defaults to math.inf (unlimited).
no_flop_no_drop – True to only rake when there are cards on the board, False otherwise. Defaults to False.

Returns:

The raked amount and the unraked amount.

pokerkit.utilities.rotated(values: Iterable[_T], count: int) → deque[_T]

Rotate the values.

The rotation is performed out-of-place (i.e., not done in-place).

>>> rotated(['a', 'b', 'c', 'd'], 2)
deque(['c', 'd', 'a', 'b'])
>>> rotated(range(5), -3)
deque([3, 4, 0, 1, 2])

Parameters:

values – The values to rotate.
count – The rotation.

Returns:

The rotated values.

pokerkit.utilities.shuffled(values: Iterable[_T]) → list[_T]

Return the shuffled values.

The shuffling is performed out-of-place (i.e., not done in-place).

>>> cards = shuffled(Card.parse('AcAdAhAs'))
>>> cards  
[A..., A..., A..., A...]

Parameters:: values – The values to shuffle.
Returns:: The shuffled values.

pokerkit.utilities.sign(value: int) → int

Get sign of a numerical value.

>>> sign(-5)
-1
>>> sign(10)
1
>>> sign(0)
0

Parameters:: value – The numerical value to get a sign from.
Returns:: The sign of a numerical value.