API reference¶

Card evaluation¶

Module evaluating cards.

phevaluator.evaluator.evaluate_5cards(a, b, c, d, e)[source]¶

Evaluate exactly five cards and return their rank.

Parameters:

a (int | str | Card) – The five cards.
b (int | str | Card) – The five cards.
c (int | str | Card) – The five cards.
d (int | str | Card) – The five cards.
e (int | str | Card) – The five cards.

Returns:

The rank of the hand. Smaller is stronger (1 is the strongest).

Return type:

int

Examples

>>> evaluate_5cards("Ac", "Ad", "Ah", "As", "Kc")
11

phevaluator.evaluator.evaluate_6cards(a, b, c, d, e, f)[source]¶

Evaluate the best five of six cards and return their rank.

Parameters:

a (int | str | Card) – The six cards.
b (int | str | Card) – The six cards.
c (int | str | Card) – The six cards.
d (int | str | Card) – The six cards.
e (int | str | Card) – The six cards.
f (int | str | Card) – The six cards.

Returns:

The rank of the best five-card hand. Smaller is stronger.

Return type:

int

phevaluator.evaluator.evaluate_7cards(a, b, c, d, e, f, g)[source]¶

Evaluate the best five of seven cards and return their rank.

Parameters:

a (int | str | Card) – The seven cards.
b (int | str | Card) – The seven cards.
c (int | str | Card) – The seven cards.
d (int | str | Card) – The seven cards.
e (int | str | Card) – The seven cards.
f (int | str | Card) – The seven cards.
g (int | str | Card) – The seven cards.

Returns:

The rank of the best five-card hand. Smaller is stronger.

Return type:

int

phevaluator.evaluator.evaluate_cards(*cards)[source]¶

Evaluate cards for the best five cards.

This function selects the best combination of the five cards from given cards and return its rank. The number of cards must be between 5 and 7.

Parameters:: cards (int | str | Card) – List of cards
Raises:: ValueError – Unsupported size of the cards
Returns:: The rank of the given cards with the best five cards. Smaller is stronger.
Return type:: int

Examples

>>> rank1 = evaluate_cards("Ac", "Ad", "Ah", "As", "Kc")
>>> rank2 = evaluate_cards("Ac", "Ad", "Ah", "As", "Kd")
>>> rank3 = evaluate_cards("Ac", "Ad", "Ah", "As", "Kc", "Qh")
>>> rank1 == rank2 == rank3  # Those three are evaluated by `A A A A K`
True

Omaha / Pot Limit Omaha evaluation¶

Module evaluating cards in Omaha game.

phevaluator.evaluator_omaha.evaluate_omaha_cards(*cards)[source]¶

Evaluate cards in Omaha game.

In the Omaha rule, players can make hand with 3 cards from the 5 community cards and 2 cards from their own 4 hole cards, then totally 5 cards. This function selects the best combination and return its rank.

Parameters:: cards (int | str | Card]) – List of cards The first five parameters are the community cards. The later four parameters are the player hole cards.
Raises:: ValueError – Unsupported size of the cards
Returns:: The rank of the given cards with the best five cards.
Return type:: int

Examples

>>> rank1 = evaluate_omaha_cards(
        "3c", "9c", "3h", "9h", "6h", # ["9c", "9h", "6h"]
        "Ac", "Kc", "Qc", "Jc"        # ["Ac", "Kc"]
    )

>>> rank2 = evaluate_omaha_cards(
        "3c", "9c", "3h", "9h", "6h", # ["9c", "9h", "6h"]
        "Ad", "Kd", "Qd", "Jd"        # ["Ad", "Kd"]
    )

>>> rank1 == rank2  # Both of them are evaluated by `A K 9 9 6`
True

phevaluator.evaluator_omaha.evaluate_plo4_cards(*cards)[source]¶

Evaluate a Pot Limit Omaha (4 hole cards) hand.

This is equivalent to evaluate_omaha_cards().

Parameters:: cards (int | str | Card) – Five community cards followed by four hole cards.
Raises:: ValueError – The number of cards is not 9.
Returns:: The rank of the hand. Smaller is stronger.
Return type:: int

phevaluator.evaluator_omaha.evaluate_plo5_cards(*cards)[source]¶

Evaluate a 5-card Pot Limit Omaha (PLO5) hand.

Requires the package to be built with PLO5 support (see PHEVALUATOR_BUILD_PLO).

Parameters:

cards (int | str | Card) – Five community cards followed by five hole cards.

Raises:

ValueError – The number of cards is not 10.
NotImplementedError – The package was not built with PLO5 support.

Returns:

The rank of the hand. Smaller is stronger.

Return type:

int

phevaluator.evaluator_omaha.evaluate_plo6_cards(*cards)[source]¶

Evaluate a 6-card Pot Limit Omaha (PLO6) hand.

Requires the package to be built with PLO6 support (see PHEVALUATOR_BUILD_PLO).

Parameters:

cards (int | str | Card) – Five community cards followed by six hole cards.

Raises:

ValueError – The number of cards is not 11.
NotImplementedError – The package was not built with PLO6 support.

Returns:

The rank of the hand. Smaller is stronger.

Return type:

int

Card¶

Module for card.

class phevaluator.card.Card(other)[source]¶

Bases: object

An immutable card object.

__id¶

The integer that identifies the card. We can use an integer to represent a card. The two least significant bits represent the 4 suits, ranged from 0-3. The rest of it represent the 13 ranks, ranged from 0-12.

More specifically, the ranks are:

deuce = 0, trey = 1, four = 2, five = 3, six = 4, seven = 5, eight = 6, nine = 7, ten = 8, jack = 9, queen = 10, king = 11, ace = 12.

And the suits are: club = 0, diamond = 1, heart = 2, spade = 3

So that you can use rank * 4 + suit to get the card ID.

The complete card Id mapping can be found below. The rows are the ranks from 2 to Ace, and the columns are the suits: club, diamond, heart and spade.

| C | D | H | S |

—: | —: | —: | —: | —: |

2 |    0 |    1 |    2 |    3 |
3 |    4 |    5 |    6 |    7 |
4 |    8 |    9 |   10 |   11 |
5 |   12 |   13 |   14 |   15 |
6 |   16 |   17 |   18 |   19 |
7 |   20 |   21 |   22 |   23 |
8 |   24 |   25 |   26 |   27 |
9 |   28 |   29 |   30 |   31 |
T |   32 |   33 |   34 |   35 |
J |   36 |   37 |   38 |   39 |
Q |   40 |   41 |   42 |   43 |
K |   44 |   45 |   46 |   47 |
A |   48 |   49 |   50 |   51 |

Type:: int

__slots__¶

Explicitly declare data members

Type:: list[str]

Raises:

ValueError – Construction with invalid string The string parameter of the constructor should be exactly 2 characters. >>> Card(“9h”) # OK >>> Card(“9h “) # ERROR
TypeError – Construction with unsupported type The parameter of the constructor should be one of the following types: [int, str, Card]. >>> Card(0) # OK. The 0 stands 2 of Clubs >>> Card(“2c”) # OK >>> Card(“2C”) # OK. Capital letter is also accepted. >>> Card(Card(0)) # OK >>> Card(0.0) # ERROR. float is not allowed
TypeError – Setting attribute >>> c = Card(“2c”) >>> c.__id = 1 # ERROR >>> c._Card__id = 1 # ERROR
TypeError – Deliting attribute >>> c = Card(“2c”) >>> del c.__id # ERROR >>> del c._Card__id # ERROR

Parameters:

other (int | str | Card)

describe_card()[source]¶

Return card description.

Returns:: The card description.
Return type:: str

Examples

>>> c1 = Card("2c")
>>> c1.describe_card()
"2c"

>>> c2 = Card("AH")
>>> c2.describe_suit()
"Ah"

describe_rank()[source]¶

Calculate card rank.

Returns:: The card rank
Return type:: str

Examples

>>> c1 = Card("2c")
>>> c1.describe_rank()
"2"

>>> c2 = Card("Ah")
>>> c2.describe_rank()
"A"

describe_suit()[source]¶

Calculate suit. It’s lowercased.

Returns:: The suit of the card
Return type:: str

Examples

>>> c1 = Card("2c")
>>> c1.describe_suit()
"c"

>>> c2 = Card("2H")
>>> c2.describe_suit()
"h"

property id_: int¶

Return self.__id.

Return type:: int

static to_id(other)[source]¶

Return the Card ID integer as API.

If the passed argument is integer, it’s returned with doing nothing. If the passed argument is string, its id is calculated. If the passed argument is Card, other.id_ is returned.

Parameters:

other (Card) – The integer that identifies the card.
other – The description of the card. e.g. “2c”, “Ah”
other – The other card to copy.

Raises:

ValueError – Passed invalid string
TypeError – Passed unsupported type

Returns:

Card ID

Return type:

int

Utilities¶

Utilities.

phevaluator.utils.sample_cards(size)[source]¶

Sample random cards with size.

Parameters:: size (int) – The size of the sample.
Returns:: The list of the sampled cards.
Return type:: list[int]