treys

Treys

A pure Python poker hand evaluation library

::

[ 3 ❤ ] , [ 3 ♠ ]

Installation

::

$ pip install treys

Implementation notes

Treys is a Python 3 port of Deuces <https://github.com/worldveil/deuces>__ based on the initial work in msaindon’s <https://github.com/msaindon/deuces>__ fork. Deuces was written by Will Drevo <http://willdrevo.com/>__ for the MIT Pokerbots Competition.

Treys is lightweight and fast. All lookups are done with bit arithmetic and dictionary lookups. That said, Treys won’t beat a C implemenation (~250k eval/s) but it is useful for situations where Python is required or where bots are allocated reasonable thinking time (human time scale).

Treys handles 5, 6, and 7 card hand lookups. The 6 and 7 card lookups are done by combinatorially evaluating the 5 card choices.

Usage

Treys is easy to set up and use.

.. code:: python

from treys import Card card = Card.new('Qh')

Card objects are represented as integers to keep Treys performant and lightweight.

Now let’s create the board and an example Texas Hold’em hand:

.. code:: python

board = [ Card.new('Ah'), Card.new('Kd'), Card.new('Jc') ] hand = [ Card.new('Qs'), Card.new('Th') ]

Pretty print card integers to the terminal:

::

Card.print_pretty_cards(board + hand) [ A ❤ ] , [ K ♦ ] , [ J ♣ ] , [ Q ♠ ] , [ T ❤ ]

If you have termcolor <http://pypi.python.org/pypi/termcolor>__ installed, they will be colored as well.

Otherwise move straight to evaluating your hand strength:

.. code:: python

from treys import Evaluator evaluator = Evaluator() print(evaluator.evaluate(board, hand)) 1600

Hand strength is valued on a scale of 1 to 7462, where 1 is a Royal Flush and 7462 is unsuited 7-5-4-3-2, as there are only 7642 distinctly ranked hands in poker.

If you want to deal out cards randomly from a deck, you can also do that with Treys:

.. code:: python

from treys import Deck deck = Deck() board = deck.draw(5) player1_hand = deck.draw(2) player2_hand = deck.draw(2)

and print them:

::

Card.print_pretty_cards(board) [ 4 ♣ ] , [ A ♠ ] , [ 5 ♦ ] , [ K ♣ ] , [ 2 ♠ ] Card.print_pretty_cards(player1_hand) [ 6 ♣ ] , [ 7 ❤ ] Card.print_pretty_cards(player2_hand) [ A ♣ ] , [ 3 ❤ ]

Let’s evaluate both hands strength, and then bin them into classes, one for each hand type (High Card, Pair, etc)

.. code:: python

p1_score = evaluator.evaluate(board, player1_hand) p2_score = evaluator.evaluate(board, player2_hand) p1_class = evaluator.get_rank_class(p1_score) p2_class = evaluator.get_rank_class(p2_score)

or get a human-friendly string to describe the score,

::

print("Player 1 hand rank = %d (%s)\n" % (p1_score, evaluator.class_to_string(p1_class))) Player 1 hand rank = 6330 (High Card)

print("Player 2 hand rank = %d (%s)\n" % (p2_score, evaluator.class_to_string(p2_class))) Player 2 hand rank = 1609 (Straight)

or, coolest of all, get a blow-by-blow analysis of the stages of the game with relation to hand strength:

::

hands = [player1_hand, player2_hand] evaluator.hand_summary(board, hands)

========== FLOP ========== Player 1 hand = High Card, percentage rank among all hands = 0.893192 Player 2 hand = Pair, percentage rank among all hands = 0.474672 Player 2 hand is currently winning.

========== TURN ========== Player 1 hand = High Card, percentage rank among all hands = 0.848298 Player 2 hand = Pair, percentage rank among all hands = 0.452292 Player 2 hand is currently winning.

========== RIVER ========== Player 1 hand = High Card, percentage rank among all hands = 0.848298 Player 2 hand = Straight, percentage rank among all hands = 0.215626

========== HAND OVER ========== Player 2 is the winner with a Straight