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.

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_stdev: float

Return the payoff standard deviation.

Returns:: The payoff stdev.

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.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.

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → State

Create a fixed-limit badugi game.

Below shows an example badugi hand from Wikipedia.

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

>>> 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,
...     200,
...     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
[196, 220, 200, 184]

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.
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.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.BadugiHand'>,): The 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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.RegularLowHand'>,): The 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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardHighHand'>,): The 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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.StandardHighHand'>, <class 'pokerkit.hands.EightOrBetterLowHand'>): The 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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

hand_types: ClassVar[tuple[type[Hand], ...]] = (<class 'pokerkit.hands.ShortDeckHoldemHand'>,): The 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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → State

Create a no-limit Texas hold’em game.

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, 2000000, 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 show the final stacks.

>>> state.stacks
[572100, 1997500, 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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

Bases: ABC

The abstract base class for poker games.

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.
divmod – The divmod function.
rake – The rake function.

ante_trimming_status: bool

The ante trimming status.

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.

betting_structure: ClassVar[BettingStructure]: The betting structure.

property big_bet: int

Return the big bet.

Returns:: The big bet.

bring_in: int: The bring-in.

property button_status: bool

Return the button status.

>>> 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.

divmod: Callable[[int, int], tuple[int, int]]: The divmod function.

hand_types: ClassVar[tuple[type[Hand], ...]]: The hand types.

property max_board_card_count: int

Return the maximum number of board cards.

>>> 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.

>>> 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.

>>> 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.

>>> 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.

rake: Callable[[int], tuple[int, int]]: The rake function.

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

Return the rank orders.

>>> 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.

raw_blinds_or_straddles: Iterable[int] | Mapping[int, int] | int: The raw blinds or straddles.

property small_bet: int

Return the small bet.

Returns:: The small bet.

streets: tuple[Street, ...]: The streets.

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0)) → 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.
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.

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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.
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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[int, int]] = functools.partial(<function rake>, rake=0))

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.
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.

>>> 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

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.

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.

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

The hands are hashable.

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

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.

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.

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.

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.

class pokerkit.lookups.BadugiLookup

Bases: Lookup

The class for badugi hand lookups.

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'>

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.

>>> 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.

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.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, 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: 'int | None' = None, level: 'int | None' = None, seats: 'list[int] | None' = None, seat_count: 'int | None' = None, table: 'int | None' = None, players: 'list[str] | None' = None, finishing_stacks: 'list[int] | None' = None, currency: 'str | None' = None, time_limit: 'int | None' = None, time_banks: 'list[int] | None' = None, user_defined_fields: 'dict[str, Any]' = <factory>, automations: 'tuple[Automation, ...]' = (<Automation.ANTE_POSTING: 'Ante posting'>, <Automation.BET_COLLECTION: 'Bet collection'>, <Automation.BLIND_OR_STRADDLE_POSTING: 'Blind or straddle posting'>, <Automation.CARD_BURNING: 'Card burning'>, <Automation.HAND_KILLING: 'Hand killing'>, <Automation.CHIPS_PUSHING: 'Chips pushing'>, <Automation.CHIPS_PULLING: 'Chips pulling'>), divmod: 'Callable[[int, int], tuple[int, int]]' = <function divmod at 0x7ff18d3f2ac0>, rake: 'Callable[[int], tuple[int, int]]' = functools.partial(<function rake at 0x7ff18d3f2b60>, rake=0), parse_value: 'Callable[[str], int]' = <function parse_value at 0x7ff18d3f2c00>)

Bases: Iterable[State]

ACPC_PROTOCOL_VARIANTS = {'FT', 'NT'}: The variant codes supported by the ACPC protocol.

PLURIBUS_PROTOCOL_VARIANTS = {'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.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.

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.

dumps() → str

Dump PHH 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_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.

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: int | None = None: The hand number.

iter_state_actions() → Iterator[tuple[State, str | None]]

Iterate through state-actions.

Returns:: The state actions.

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 loads(s: str, *, parse_value: ~collections.abc.Callable[[str], int] = <function parse_value>, **kwargs: ~typing.Any) → HandHistory

Load PHH from 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', 'address', 'city', 'region', 'postal_code', 'country', 'time', 'time_zone', 'day', 'month', 'year', 'hand', 'level', 'seats', 'seat_count', 'table', 'players', 'finishing_stacks', 'currency', '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(*, rake: float = 0) → 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.

table: int | None = None: The table 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.

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

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 automation.

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

ANTE_POSTING = 'Ante posting': The ante posting automation.

BET_COLLECTION = 'Bet collection': The bet collection automation.

BLIND_OR_STRADDLE_POSTING = 'Blind or straddle posting': The blind or straddle posting automation.

BOARD_DEALING = 'Board dealing': The board dealing automation.

CARD_BURNING = 'Card burning': The card burning automation.

CHIPS_PULLING = 'Chips pulling': The chips pulling automation.

CHIPS_PUSHING = 'Chips pushing': The chips pushing automation.

HAND_KILLING = 'Hand killing': The hand killing automation.

HOLE_CARDS_SHOWING_OR_MUCKING = 'Hole cards showing or mucking': The hole cards showing or mucking automation.

HOLE_DEALING = 'Hole dealing': The hole dealing automation.

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'>

FIXED_LIMIT = 'Fixed-limit': The fixed-limit.

NO_LIMIT = 'No-limit': The no-limit.

POT_LIMIT = 'Pot-limit': The pot-limit.

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, ...], rake: int, *, commentary: str | None = None)

Bases: Operation

The class for chips pushings.

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

rake: int: The rake.

property total_amount: int

Return the total amount.

>>> chips_pushing = ChipsPushing((1, 2, 3), 0)
>>> chips_pushing.total_amount
6

Returns:: The total 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.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.

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

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

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

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

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

POSITION = '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.

commentary: str | None = None: The optional commentary.

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

Bases: object

The class for pots.

>>> pot = Pot(100, (1, 3))
>>> pot.amount
100
>>> pot.player_indices
(1, 3)

>>> pot = Pot(-1, (1, 3))
Traceback (most recent call last):
    ...
ValueError: The pot amount -1 is negative.

amount: int: The amount.

player_indices: tuple[int, ...]: The player indices of those who contributed.

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, divmod: ~collections.abc.Callable[[int, int], tuple[int, int]] = <function divmod>, rake: ~collections.abc.Callable[[int], tuple[~typing.Any, int]] = functools.partial(<function rake>, rake=0))

Bases: object

The class for 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), rake=0)
>>> state.pull_chips(1)
ChipsPulling(commentary=None, player_index=1, amount=3)

The game has terminated.

>>> state.status
False

>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (1,) * 2,
...     (0,) * 2,
...     0,
...     (2,) * 2,
...     2,
... )
Traceback (most recent call last):
    ...
ValueError: The streets are empty.
>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             True,
...             (),
...             3,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (1,) * 2,
...     (0,) * 2,
...     0,
...     (2,) * 2,
...     2,
... )
Traceback (most recent call last):
    ...
ValueError: The first street must be of hole dealing.
>>> 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,
... )
Traceback (most recent call last):
    ...
ValueError: Negative antes, blinds, straddles, or bring-in was supplied.
>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (0,) * 2,
...     (0,) * 2,
...     0,
...     (2,) * 2,
...     2,
... )
Traceback (most recent call last):
    ...
ValueError: No antes, blinds, straddles, or bring-in was supplied.
>>> 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, 0),
...     2,
... )
Traceback (most recent call last):
    ...
ValueError: Non-positive starting stacks was supplied.
>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (0,) * 2,
...     (1,) * 2,
...     1,
...     (2,) * 2,
...     2,
... )  
Traceback (most recent call last):
    ...
ValueError: Only one of bring-in or (blinds or straddles) must specified...
>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (0,) * 2,
...     (0,) * 2,
...     1,
...     (2,) * 2,
...     2,
... )
Traceback (most recent call last):
    ...
ValueError: The bring-in must be less than the min bet.
>>> state = State(
...     (),
...     Deck.KUHN_POKER,
...     (KuhnPokerHand,),
...     (
...         Street(
...             False,
...             (False,),
...             0,
...             False,
...             Opening.POSITION,
...             1,
...             None,
...         ),
...     ),
...     BettingStructure.FIXED_LIMIT,
...     True,
...     (1,),
...     (0,),
...     0,
...     (2,),
...     1,
... )
Traceback (most recent call last):
    ...
ValueError: There must be at least 2 players (currently 1).

property actor_index: int | None

Return the actor index.

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

actor_indices: deque[int]: The actor indices.

all_in_status: bool = False: The all-in status.

property ante_poster_indices: Iterator[int]

Iterate through players who can post antes.

>>> 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.

ante_trimming_status: bool

The ante trimming status.

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.

automations: tuple[Automation, ...]: The automations.

bet_collection_status: bool = False: The bet collection status.

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

betting_structure: BettingStructure: The betting structure.

property blind_or_straddle_poster_indices: Iterator[int]

Iterate through 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 posters.

blind_or_straddle_posting_statuses: list[bool]: The player blind or straddle statuses.

blinds_or_straddles: tuple[int, ...]: The blinds or straddles.

board_cards: list[Card]: The board cards.

board_dealing_count: int = 0: The board dealing count.

bring_in: int: The bring-in.

bring_in_status: bool = False: The bring-in status.

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

Burn a card.

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.

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

Return whether the card burning can be done.

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.

>>> 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.

>>> 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.

>>> 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.

Parameters:

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

Returns:

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

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

Return whether the hole dealing can be done.

Parameters:: cards – The optional cards.
Returns:: True if the hole dealing can be done, otherwise False.

can_fold() → bool

Return whether theing fold can be done.

>>> 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.

>>> 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.

Returns:: True.

can_post_ante(player_index: int | None = None) → bool

Return whether the ante posting can be done.

>>> 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.

>>> 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.

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.

>>> 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.

>>> 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_show_or_muck_hole_cards(status_or_hole_cards: bool | Iterable[Card] | Card | str | None = None) → bool

Return whether the hole card showing or mucking can be done.

>>> 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.
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.

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 pots based on the available information to a player.

It is assumed that no more card is dealt.

>>> 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.

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

Iterate through the cards in play.

These are visible by players still in the pot.

These are either in the board or holes.

Returns:: The cards in play.

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

Iterate through the cards not in play.

These are invisible by players still in the pot.

These 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.

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.

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.

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.

completion_betting_or_raising_count: int = 0: The number of completions, bettings, or raisings.

completion_status: bool = False: The completion status.

Deal the board.

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.

Parameters:

cards – The optional cards.
commentary – The optional commentary.

Returns:

The hole dealing.

Raises:

ValueError – If the hole dealing cannot be done.

deck: Deck: The deck.

deck_cards: deque[Card]: The deck cards.

discarded_cards: list[list[Card]]: The discards.

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

property draw_statuses: Iterator[bool]

Return the draw statuses.

>>> 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.

Parameters:: commentary – The optional commentary.
Returns:: The folding.
Raises:: ValueError – If the folding cannot be done.

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)

Returns:: The censored hole cards.

get_dealable_cards(deal_count: int | None = None) → tuple[Card, ...]

Iterate through the available cards that can be dealt or burned.

Parameters:: deal_count – The number of dealt cards.
Returns:: The recommended dealable cards, from deck and backup.

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.

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.

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.

Parameters:: player_index – The player index.
Returns:: The effective stack of the player.

get_hand(player_index: int, hand_type_index: int) → Hand | None

Return the corresponding hand of the player.

>>> 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) is None
True
>>> state.get_hand(1, 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) is None
True
>>> state.get_hand(1, 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)
AcAdJsTs2c
>>> str(state.get_hand(0, 0))
'One pair (AcAdJsTs2c)'
>>> str(state.get_hand(1, 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))
'Three of a kind (AcAdJsTsAh)'
>>> str(state.get_hand(1, 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))
'Four of a kind (AcAdJsAhAs)'
>>> str(state.get_hand(1, 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) is None
True
>>> str(state.get_hand(1, 0))
'Straight flush (KsQsJsTsAs)'

Parameters:

player_index – The player 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, hand_type_index: int) → Hand | None

Return the corresponding hand of the player from up cards.

>>> 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) is None
True
>>> state.get_up_hand(1, 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) is None
True
>>> state.get_up_hand(1, 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) is None
True
>>> state.get_up_hand(1, 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) is None
True
>>> state.get_up_hand(1, 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))
'One pair (JsTs2cAhAs)'
>>> str(state.get_up_hand(1, 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) is None
True
>>> str(state.get_up_hand(1, 0))
'Straight flush (KsQsJsTsAs)'

Parameters:

player_index – The player index.
hand_type_index – The hand type index.

Returns:

The corresponding hand of the player.

get_up_hands(hand_type_index: int) → Iterator[Hand | None]

Return the optional corresponding hands from up cards.

>>> 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)  
<generator object State.get_up_hands at 0x...>
>>> tuple(state.get_up_hands(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))
(JsTs2cAhAs, JsTs2cAhAs)
>>> state.check_or_call()
CheckingOrCalling(commentary=None, player_index=1, amount=0)
>>> tuple(state.get_up_hands(0))
(None, KsQsJsTsAs)

Parameters:: hand_type_index – The hand type index.
Returns:: The optional corresponding hands from up cards.

property hand_killing_indices: Iterator[int]

Iterate through players who can post antes.

>>> 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 ante posters.

hand_killing_statuses: list[bool]: The hand killing statuses.

property hand_type_count: int

Return the number of hand types.

>>> 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.

hole_card_statuses: list[list[bool]]: The player hole card statuses.

hole_cards: list[list[Card]]: The player hole cards.

property hole_dealee_index: int | None

Return the hole dealee index.

Returns:: The hole dealee index if applicable, otherwise None.

hole_dealing_statuses: list[deque[bool]]: The hole dealing statuses.

kill_hand(player_index: int | None = None, *, commentary: str | None = None) → HandKilling

Kill hand.

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.

mucked_cards: list[Card]: The mucked cards.

no_operate(*, commentary: str | None = None) → NoOperation

No-operate.

Returns:: The no-operation.

opener_index: int | None = None: The opener index.

operations: list[Operation]: The operations.

player_count: int: The number of players.

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.

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.

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.

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.

>>> 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.
>>> 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=(...,))
>>> next(state.pot_amounts)
Traceback (most recent call last):
    ...
StopIteration
>>> tuple(state.pot_amounts)
()

Returns:: The list of main and side pots (if any).

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.

>>> 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.
>>> 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(amount=300, player_indices=(0, 1, 2, 3, 4, 5))
>>> pots = tuple(state.pots)
>>> len(pots)
3
>>> pots[0]
Pot(amount=300, player_indices=(0, 1, 2, 3, 4, 5))
>>> pots[1]
Pot(amount=250, player_indices=(1, 2, 3, 4, 5))
>>> pots[2]
Pot(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=(...,))
>>> next(state.pots)
Traceback (most recent call last):
    ...
StopIteration
>>> tuple(state.pots)
()

Returns:: The list of main and side pots (if any).

pull_chips(player_index: int | None = None, *, commentary: str | None = None) → ChipsPulling

Pull chips.

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.

Parameters:: commentary – The optional commentary.
Returns:: The chips pushing.
Raises:: ValueError – If the chips pushing cannot be done.

rake(*, rake: float = 0) → tuple[int, int]: The rake function.

raw_antes: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]: The raw antes.

raw_blinds_or_straddles: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]: The raw blinds or straddles.

raw_starting_stacks: dataclasses.InitVar[collections.abc.Iterable[int] | collections.abc.Mapping[int, int] | int]: The raw starting stacks.

property reserved_cards: tuple[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.

Show or muck hole cards.

If the status is not given, the hole cards will be shown if and only if there is chance of winning the pot. Otherwise, the hand will be mucked.

Parameters:

status_or_hole_cards – The optional status or hole cards.
commentary – The optional commentary.

Returns:

The hole cards showing or mucking.

property showdown_index: int | None

Return the showdown index.

>>> 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.

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

stand_pat_or_discard(cards: Iterable[Card] | Card | str = (), *, commentary: str | None = None) → StandingPatOrDiscarding

Discard hole cards.

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.

starting_stacks: tuple[int, ...]: The starting stacks.

status: bool = True: The game status.

statuses: list[bool]: The player statuses.

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), rake=0)
>>> 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.

property street_indices: range

Return the street indices.

Returns:: The street indices.

streets: tuple[Street, ...]: The streets.

property total_pot_amount: int

Return the total pot amount.

This value also includes the 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), rake=0)
>>> 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

Returns:: The index of the player whose turn it is or None if no one is in turn.

verify_ante_posting(player_index: int | None = None) → int

Verify the ante posting.

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.

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.

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.

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.

Returns:: None.
Raises:: ValueError – If the bring-in posting cannot be done.

verify_card_burning(card: Card | str | None = None) → Card

Verify the card burning.

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.

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.

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.

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.

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.

Returns:: None.
Raises:: ValueError – If the folding cannot be done.

verify_hand_killing(player_index: int | None = None) → int

Verify the hand killing.

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.

Parameters:: status_or_hole_cards – The optional status or hole cards.
Returns:: The status.
Raises:: ValueError – If hole card showing or mucking cannot be done.

verify_hole_dealing(cards: Iterable[Card] | Card | str | int | None = None) → tuple[Card, ...]

Verify the hole dealing.

Parameters:: cards – The optional cards.
Returns:: The dealt hole cards.
Raises:: ValueError – If the hole dealing cannot be done.

verify_no_operation() → None

Verify the no-operation.

Returns:: None.

verify_standing_pat_or_discarding(cards: Iterable[Card] | Card | str = ()) → tuple[Card, ...]

Verify the 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 = Street(
...     False,
...     (False, False),
...     0,
...     False,
...     Opening.POSITION,
...     2,
...     None,
... )
>>> street.card_burning_status
False
>>> street.hole_dealing_statuses
(False, False)

>>> street = Street(
...     False,
...     (False, False),
...     -1,
...     False,
...     Opening.POSITION,
...     2,
...     None,
... )
Traceback (most recent call last):
    ...
ValueError: The number of dealt cards -1 is negative.
>>> street = Street(
...     True,
...     (False, False),
...     0,
...     False,
...     Opening.POSITION,
...     0,
...     None,
... )  
Traceback (most recent call last):
    ...
ValueError: Non-positive minimum completion, betting, or raising amount ...
>>> street = Street(
...     True,
...     (False, False),
...     0,
...     False,
...     Opening.POSITION,
...     2,
...     -1,
... )  
Traceback (most recent call last):
    ...
ValueError: Negative maximum number of completion, bets, or raises -1 wa...

board_dealing_count: int: The number of dealt board cards.

card_burning_status: bool: Whether to burn card.

draw_status: bool: Whether to draw cards prior to betting.

hole_dealing_statuses: tuple[bool, ...]: The statuses of dealt hole cards.

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.

pokerkit.utilities module

pokerkit.utilities implements classes related to poker utilities.

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.

>>> card = Card(Rank.ACE, Suit.SPADE)
>>> card
As
>>> str(card)
'ACE OF SPADES (As)'
>>> card.rank
<Rank.ACE: 'A'>
>>> card.suit
<Suit.SPADE: 's'>

Note that the card attributes are read-only.

>>> card.rank = Rank.KING
Traceback (most recent call last):
    ...
dataclasses.FrozenInstanceError: cannot assign to field 'rank'

The card is also hashable.

>>> from collections.abc import Hashable
>>> isinstance(card, Hashable)
True

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.

>>> 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.

>>> Card.parse('AsKsQsJsTs')  
<generator object Card.parse at 0x...>
>>> list(Card.parse('2c8d5sKh'))
[2c, 8d, 5s, Kh]
>>> next(Card.parse('AcAh'))
Ac
>>> next(Card.parse('AcA'))  
Traceback (most recent call last):
    ...
ValueError: The lengths of valid card representations must be multip...
>>> 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.

suit: Suit: The suit.

property unknown_status: bool

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. The ordering of the cards are different, however.

>>> 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.

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.

A card of lower rank is said to be less than that of a higher rank. The ordering of the ranks is decided in accordance to the rules of the poker variant being played.

>>> Rank.DEUCE
<Rank.DEUCE: '2'>
>>> Rank('2')
<Rank.DEUCE: '2'>
>>> Rank.DEUCE.value
'2'
>>> Rank.DEUCE.name
'DEUCE'

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 tuples 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 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: 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).

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.

In stud games, suits are used to break ties when deciding the opener when there are multiple up cards with the same rank.

>>> Suit.CLUB
<Suit.CLUB: 'c'>
>>> Suit('c')
<Suit.CLUB: 'c'>
>>> 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.clean_values(values: Iterable[int] | Mapping[int, int] | int, count: int) → tuple[int, ...]

Clean the integers.

>>> 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 integers.

pokerkit.utilities.divmod(dividend: int, divisor: int) → tuple[int, int]

Divide the amount.

>>> 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 None from 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.

>>> 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 any, otherwise None.

pokerkit.utilities.min_or_none(values: Iterable[Any], key: Any = None) → Any

Get the minimum value while ignoring None values.

>>> 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 any, otherwise None.

pokerkit.utilities.parse_value(raw_value: str) → int

Convert str to a number.

>>> parse_value('3')
3
>>> parse_value('3.0')
3.0
>>> parse_value('3.5')
3.5

Parameters:: raw_value – The raw value.
Returns:: The converted value.

pokerkit.utilities.rake(amount: int, rake: float) → tuple[int, int]

Rake the amount.

>>> rake(100, 0)
(0, 100)
>>> rake(1000, 0.1)
(100, 900)
>>> rake(10, 0.11)
(1, 9)
>>> rake(10.0, 0.11)
(1.1, 8.9)

Parameters:

amount – The pot amount.
rake – The rake.

Returns:

The raked amount and the remaining amount.

pokerkit.utilities.shuffled(values: Iterable[_T]) → list[_T]

Return the shuffled values.

The shuffling is not done in-place.

>>> cards = shuffled(Card.parse('AcAdAhAs'))
>>> cards  
[A..., A..., A..., A...]

Parameters:: values – The values to shuffle.
Returns:: The shuffled values.