Course 1.2Lesson 5 of 5

Project: a deck of cards

In this project we build a deck of playing cards. A Card knows its rank and suit, and has special methods so that two cards can be compared for equality, put in order by rank and then by suit, and shown as text. A Deck has fifty-two Cards, which is composition, and can say how many cards are left, shuffle, and deal a number of cards, refusing when there are not enough. We plan the expected results by hand, build the classes, test the order of cards and the refused deal, and extend the project with a hand class and a simple game.

about 25 min1 simulation2 practice questions

Lesson 5 of 5Show all lessons

Try the code and the simulations beside the lesson.

What you will be able to do

After this lesson you can

combine special methods and composition in one program,
compare objects by two keys,
test a class that uses chance, with a seed, and
design the classes of a small game.

The goal

A card game needs cards and a deck. We want:

a Card with a rank (2 to ace) and a suit, that prints as A of spades, that can be compared (==, <) so that a hand can be sorted, and that knows its value,
a Deck of 52 cards that can say how many cards are left, be shuffled, and deal a hand,
a deck that refuses to deal more cards than it has.

Step 1: find the classes and the plan

Class	It knows	It does
`Card`	rank, suit	`value()`, `==`, `<`, text
`Deck`	a list of `Card` objects	`len`, `shuffle`, `deal`

Deck has Card objects: composition. A card is not a kind of deck, and a deck is not a kind of card.

Step 2: the expected answers

Work out by hand.

A new deck has 52 cards: 4 suits times 13 ranks.
The ranks in order are 2, 3, ..., 10, J, Q, K, A. So A is the highest (value 12) and 2 the lowest (value 0).
For two cards of the same rank, the suit decides: clubs, then diamonds, then hearts, then spades. So the 2 of clubs is less than the 2 of hearts.
After dealing 5 cards, the deck has 47.
Dealing 100 cards from a deck is refused.

Step 3: the program

Run it. The seed 4 makes the shuffle the same each time, so you can compare your output with a friend's.

Look at the design.

- RANKS and SUITS are lists at the top. The position of a rank in RANKS is its value: RANKS.index(self.rank). This turns the order of the ranks into numbers, without a long if.

- Card.__lt__ compares two tuples: (value, suit position). Tuples are compared item by item, so the value decides, and the suit decides only when the values are equal. This is the same trick as sorting by two keys.

- Card.__eq__ says two cards are equal when both rank and suit are equal.

- __str__ gives A of spades, and __repr__ gives Card('A', 'spades'). The first is for the player, and the second is for the programmer. Printing a list of cards would use __repr__.

- Deck.__init__ builds all 52 cards with a list comprehension with two loops: one for the suits, one for the ranks.

- __len__ lets you write len(deck).

- deal takes cards off the top and removes them from the deck. It checks the rule first, and raises a ValueError if there are not enough cards.

- sorted(hand) and max(hand) work, because Card has __lt__.

Step 4: test

Test	Expected
a new deck	52 cards, no repeated card
deal 5	the hand has 5 cards, the deck has 47, and no card of the hand is still in the deck
deal 100	refused, and the deck is unchanged
deal 0	an empty hand, the deck is unchanged
`Card("A", "spades") == Card("A", "spades")`	`True`
2 of clubs against 2 of hearts	the 2 of clubs is less
3 of clubs against 2 of spades	the 3 is greater, because the rank decides first
the same seed twice	the same hand

The last row tests chance: the same seed must give the same shuffle.

len(deck) works because Deck has __len__. A shuffle would mix the suits, but the count would be the same.

Extend it

Pick one or two, and do them without looking at a solution. Write the expected results first.

A hand class. Hand has a list of cards, shows them sorted, and tells the total value.
A pair. Does a hand have two cards of the same rank?
War. Two players deal one card each, and the higher card wins. Play 10 rounds, and count the wins.
Jokers. Add two jokers. What must value and the comparison do?
A better __eq__. Return NotImplemented for an object that is not a Card.

Common mistakes

Dealing without removing the cards from the deck. The same card would be dealt twice.
Checking the rule after changing the deck. Check first.
Comparing the suit before the rank. The order of the tuple matters.
A __str__ that prints. It must return.
Testing a shuffle without a seed. You cannot repeat the result.

Practice

Start with two quick questions. Each New numbers gives you a fresh one, so you can practise as long as you like.

Then the labs and the problems:

Warm-up. Open the lab Project: a deck of cards. The checker deals hands with a seed, and tests the refused deal.
Build. Do Step 4 for one extension.
Stretch. Open the lab A Vector class, and compare how its special methods and the card's special methods work.