CS303E Project2: Evaluating Poker Hands

Instructor: Dr. Bill Young
Due Date: Monday, April 13, 2026 at 11:59pm

It is common, and smart, in computing to build upon work that you or others have done previously, rather than re-inventing the wheel. In this project, you will build on some classes described in the class slides, but modified for the current assignment. You'll have to add your own code as well. Of course, in this course you should never use work that you find on the internet or was done by someone (or something) other than yourself, except as specifically allowed, as in this case! To be very clear, for this assignment you can use the code provided, but not code from the internet, AI, classmates, or anybody else.

Evaluating Poker Hands

In slidesets 7 and 9, we introduced Python classes implementing playing cards, a deck of cards, and a hand of 5 cards as you might find in Poker. In this assignment, you will be building on three classes: Card, Deck and Hand. The code for the Card and Deck classes is here: Card and Deck. These implementations are slightly different than what's in the slides. You should start this assignment by playing with these and familiarizing yourself with this code. In the sample output below are some examples of using this code. You will also receive a partial version of the Hand class here: Hand (partial).

Your assignment is to put it all together and write code that will generate hands (5 cards) and evaluate them as Poker hands. Note that a hand can be created in two different ways:

by dealing five cards from a pre-existing deck;
by specifying the five cards as a list of "card specifiers"; this functionality is already in the Card class.

Within the same file as your Hand class (but outside the class definition), you will write a function evaluateHand( hand ) which will print the hand and the evaluation of the hand: pair, two pair, full house, straight, etc. These are defined below.

A user of your code should be able to import Hand, create a new deck (since Hand imports Card and Deck), shuffle it, deal a hand or create a hand from a list of card specs, evaluate the hand. See the examples below.

A Big Hint for Evaluating Hands

The relevant Poker evaluations are the following:

pair: two cards of the same rank, e.g., two Kings;
two pairs: two pairs, but not all the same rank, e.g., two 3s and two Kings;
three of a kind: three cards of the same rank, e.g., three 10s;
four of a kind: four cards of the same rank, e.g., four Aces
full house: one pair and three of a kind;
flush: five cards all in one suit, e.g, five Spades;
straight: five cards in consecutive rank order, e.g., 7, 8, 9, 10, Jack (of any suit). Notice that Ace can be high or low.;
straight flush: a straight, all of the same suit;
Royal flush: 10, Jack, Queen, King, Ace all of the same suit;
nothing: none of the above.

This assignment can be pretty straightforward if you handle it correctly. The first thing to do is to preprocess the hand to extract the relevant information. Here's how to do that.

Recall the ordering of ranks and suits defined in the Card class by the two lists:

CARDRANKS = ['2', '3', '4', '5', '6', '7', '8', '9', 'T', 'J', 'Q', 'K', 'A']
CARDSUITS = ['S', 'D', 'H', 'C']

Now, define two new lists, full of zeros:

 myRanks = [0] * 13    # a list of 13 zeros
 mySuits = [0] * 4     # a list of 4 zeros

You interpret each position in myRanks as recording the number of cards in the hand being evaluated of the corresponding rank in CARDRANKS. Do a similar thing with mySuits. For example, suppose you have the following cards in your hand:

Ace of Spades
3 of Diamonds
King of Spades
3 of Hearts
Ace of Hearts

You record this information in myRanks and mySuits by incrementing the appropriate positions in these two arrays. For the hand above, this yields:

  # two Aces, two 3's, one King           
  myRanks: [ 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2 ] 
  # two Spades, one Diamond, two Hearts, no Clubs
  mySuits: [ 2, 1, 2, 0 ]

Once you've pre-processed the hand, it's very easy to evaluate it by using the information in myRanks and mySuits. For example, you have:

a pair: if there's a 2 anywhere in myRanks;
three of a kind: if there's a 3 anywhere in myRanks;
two pairs: if there are two 2's in myRanks;
a full house: if there is a 2 and a 3 in myRanks;
a flush: if there's a 5 in mySuits;
a straight: if there are 5 consecutive 1's in myranks (allowing Ace to be either high or low);
a straight flush: if you have both a straight and a flush;
etc.

It's very important to evaluate things in the right order; you don't want to report a pair, if you actually have two pairs, three of a kind, or a full house. Below is possible code for the evaluateHand function that checks things in the right order. Of course, you'll have to write the subsidiary functions like hasPair, hasStraight, etc. But most of those are pretty simple.

def evaluateHand( hand ):
    myHands, mySuits = processHand( hand )
    print( hand )
    if hasRoyalFlush( myHands, mySuits ):
        print( "Royal Flush" )
    elif hasStraightFlush( myHands, mySuits ):
        print( "Straight Flush" )
    elif hasFourOfAKind( myHands, mySuits ):
        print( "Four of a kind" )
    elif hasFullHouse( myHands, mySuits ):
        print( "Full House" )
    elif hasFlush( myHands, mySuits ):
        print( "Flush" )
    elif hasStraight( myHands, mySuits ):
        print( "Straight" )
    elif hasThreeOfAKind( myHands, mySuits ):
        print( "Three of a kind" )
    elif hasTwoPair( myHands, mySuits ):
        print( "Two pair" )
    elif hasPair( myHands, mySuits ):
        print( "Pair" )
    else:
        print( "Nothing" )

Driver Program

In addition to your class files Card.py, Deck.py, Hand.py, you'll need to have a main function in file Poker.py. Your main function should ask the user to input a positive integer n, create a new Deck object, and deal and evaluate n Hands. When dealing any hand, if the size of the deck falls below 5 cards, you'll need to create a new Deck.

Some Sample Output

Your output should match what is here, except that the hands drawn will differ. We should be able to type python Poker.py to generate and evaluate N Hands. Below is some output from testing the Card, Deck and Hand classes in interactive mode. Below that is output testing your main (driver) function.

>>> from Hand import *
>>> c1 = Card("2H")               # checking that Card works correctly
>>> print(c1)
2 of Hearts
>>> c2 = Card("TS")
>>> print(c2)
10 of Spades
>>> c1.getRank()
'2'
>>> c2.getSuit()
'S'
>>> c1 < c2
True
>>> c2 <= c2
True
>>> c1 == c2
False
>>> d = Deck()                   # we'll need a deck
>>> print(d)
2 of Spades                      # 52 Cards in order
3 of Spades
..
10 of Clubs
Jack of Clubs
Queen of Clubs
King of Clubs
Ace of Clubs

>>> d.shuffle()
>>> print(d)
4 of Spades                      # 52 cards, now shuffled
Queen of Spades
8 of Clubs
4 of Hearts
...
6 of Hearts
4 of Diamonds

>>> h1 = Hand(d, True)           # deal a hand from the deck
>>> print( h1 )
4 of Spades                      # notice: first 5 cards from d
Queen of Spades
8 of Clubs
4 of Hearts
3 of Hearts

>>> h2 = Hand(d, True)           # next 5 cards from d
>>> print( h2 )
7 of Hearts
King of Clubs
6 of Clubs
2 of Hearts
Jack of Hearts
                                 # generate some hands, specifying cards
>>> cardSpec = ("AS", "AD", "AH", "AC", "2D")
>>> h3 = Hand(cardSpec, False)
>>> evaluateHand( h3 )           # list hand and evaluation
Ace of Spades
Ace of Diamonds
Ace of Hearts
Ace of Clubs
2 of Diamonds

Four of a kind                   
>>> cardSpec = ("AS", "2S", "3C", "4H", "5D")
>>> h4 = Hand(cardSpec, False)
>>> evaluateHand( h4 )
Ace of Spades
2 of Spades
3 of Clubs
4 of Hearts
5 of Diamonds

Straight
>>> cardSpec = ("2S", "9S", "TC", "AH", "4D")
>>> h5 = Hand(cardSpec, False)
>>> evaluateHand( h5 )
2 of Spades
9 of Spades
10 of Clubs
Ace of Hearts
4 of Diamonds

Nothing
>>> h6 = Hand(d, True)              # back to dealing from the deck d
>>> evaluateHand( h6 )
9 of Spades
King of Hearts
3 of Spades
King of Diamonds
7 of Spades

Pair 
>>>

What you see above is testing the Card, Deck, and Hand classes in the interactive loop. You should also be able to run your overall program from a file named Poker.py. It asks the user to input an integer n meaning to deal n hands. Then in a loop, deal and evaluate those n hands. Your code will need to generate a new deck if the card count ever drops below 5. Here's how that might look.

> python Poker.py
How many hands should I deal? -10
 Positive number required. Try again!
How many hands should I deal? 12

Hand drawn (1): 
5 of Hearts
7 of Clubs
9 of Clubs
King of Spades
3 of Hearts

Nothing

Hand drawn (2): 
6 of Spades
Queen of Diamonds
8 of Spades
Jack of Clubs
5 of Spades

Nothing

Hand drawn (3): 
4 of Diamonds
Ace of Diamonds
Ace of Hearts
8 of Clubs
10 of Hearts

Pair

Hand drawn (4): 
2 of Hearts
5 of Diamonds
2 of Spades
7 of Spades
4 of Spades

Pair

Hand drawn (5): 
3 of Spades
Queen of Clubs
Ace of Clubs
Queen of Spades
9 of Spades

Pair

Hand drawn (6): 
2 of Clubs
5 of Clubs
Ace of Spades
6 of Hearts
8 of Diamonds

Nothing

Hand drawn (7): 
10 of Clubs
2 of Diamonds
6 of Clubs
7 of Diamonds
4 of Hearts

Nothing

Hand drawn (8): 
9 of Diamonds
7 of Hearts
King of Clubs
Jack of Spades
6 of Diamonds

Nothing

Hand drawn (9): 
10 of Diamonds
Jack of Diamonds
10 of Spades
King of Diamonds
8 of Hearts

Pair

Hand drawn (10): 
4 of Clubs
King of Hearts
9 of Hearts
3 of Diamonds
Queen of Hearts

Nothing

Dealing a new deck.

Hand drawn (11): 
7 of Diamonds
Jack of Clubs
10 of Spades
Ace of Spades
8 of Hearts

Nothing

Hand drawn (12): 
2 of Spades
Jack of Hearts
5 of Spades
2 of Diamonds
10 of Diamonds

Pair

>

Turning in the Assignment:

The driver program should be in a file named Poker.py. You can put all of classes in a single file, or break it into separated files for Card.py, Deck, etc. Submit your files via Canvas before the deadline shown at the top of this page. Submit it to the assignment project2 under the assignments sections by uploading your python file(s).

Your file(s) must compile and run before submission. It must also contain a header with the following format:

# Assignment: Project2
# File: Poker.py
# Student: 
# UT EID:
# Course Name: CS303E
# 
# Date:
# Description of Program:

Programming Tips:

Program incrementally: Writing any complex program should be done in pieces. It's crazy to do the entire thing and then try to debug it. Yet that's what I frequently see students do. Instead, write the simplest version first and test it before you move on. For this assignment, make sure you can use the Card and Deck classes before moving on. Then flesh out the Hand class and test that. Then write the code to preprocess the hand. Finally, work on the code for evaluating the hand. Any extra time will more than pay off in greatly reduced frustration!

Use functions: If you see that you're doing some computation multiple times write a function to handle that. Always test the function before you move on.

Use print for debugging: If you don't quite see what's going wrong at any point, add print statements. Often seeing what values are being generated as you go is enough to understand your error. Just remember to comment out or remove the extra print statement before you submit.