paul
/
poker-ranking-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
API to compute the rank of an individual poker hand.
16 Commits 2 Branches 0 Tags 100 KiB
Python 89%
Makefile 8.8%
Dockerfile 2.2%
Go to file
Paul Harrison c114366357 feat: Dockerize API 2022-12-15 16:43:09 +00:00
poker feat: Hand ranking API 2022-12-15 16:02:14 +00:00
tests feat: Hand ranking API 2022-12-15 16:02:14 +00:00
.gitignore chore: Initial project setup 2022-12-15 16:02:01 +00:00
Dockerfile feat: Dockerize API 2022-12-15 16:43:09 +00:00
Makefile feat: Dockerize API 2022-12-15 16:43:09 +00:00
README.md feat: Dockerize API 2022-12-15 16:43:09 +00:00
compose.yml feat: Dockerize API 2022-12-15 16:43:09 +00:00
poetry.lock feat: Hand ranking API 2022-12-15 16:02:14 +00:00
pyproject.toml feat: Hand ranking API 2022-12-15 16:02:14 +00:00
setup.cfg chore: Add coverage 2022-12-15 16:02:14 +00:00

README.md

Single Poker Hand Ranking Service

Project Scope

This service comprises an API to compute the rank of an individual poker hand. The scope of this project is to:

  • Write an algorithm that takes a hand of cards and identifies the ranking of the given hand.
  • Expose an API to serve this algorithm via an endpoint /rank, that accepts a valid poker hand and returns its ranking.
  • Rank information should be formatted as <rank_name>: <description>, see description format for each different rank below.

Poker Rules

A poker hand consists of 5 cards dealt from a deck. A deck is composed of 52 cards ordered as 2 through 10, J (Jack), Q (Queen), K (King), and A (Ace); and split across 4 suits: ♠ Spades (black), ♦ Diamonds (red), ♣ Clubs (black), and ♥ Hearts (red).

Poker hands are ranked by the following partial order from highest to lowest:

1. Royal Flush ~ [ A♥ K♥ Q♥ J♥ 10♥ ]

The best hand possible, a royal flush consists of A, K, Q, J and 10, all of the same suit.

Description format: <suit>

2. Straight Flush ~ [ 6♥ 7♥ 8♥ 9♥ 10♥ ]

Also very rare, a straight flush consists of any straight that is all the same suit. Note Ace can act as value 1 to form a straight with values 2 3 4 5.

Description format: <highest_value>-high <suit>

3. Four of a Kind ~ [ A♥ A♣ A♦ A♠ K♥ ]

Four of a kind, or 'quads', consists of four cards of equal value along with another card known as a side card.

Description format: <quads value>

4. Full House ~ [ A♥ A♣ A♦ K♠ K♥ ]

A full house consists of three cards of one value and two cards of another.

Description format: <trips_value> over <pair_value>

5. FLush ~ [ K♣ 10♣ 8♣ 7♣ 5♣ ]

A flush is a hand which has all cards of the same suit.

Description format: <suit>

6. Straight ~ [ 10♥ 9♣ 8♦ 7♠ 6♥ ]

A straight has five cards of consecutive value that are not all the same suit. Note Ace can act as value 1 to form a straight with values 2 3 4 5.

Description format: <highest_value>-high

7. Three of a Kind ~ [ A♥ A♣ A♦ K♠ Q♥ ]

Also known as 'trips', three of a kind is 3 cards of the same value and 2 side cards of different values.

Description format: <trips value>

8. Two Pair ~ [ A♥ A♣ K♦ K♠ 7♥ ]

Two pair cosists of two cards of the same value, and three extra cards.

Description format: <high_pair_value> and <low_pair_value>

9. Pair ~ [ A♥ A♣ K♦ J♠ 7♥ ]

One pair consists of two cards of the same value, and three extra cards.

Description format: <pair_value>

10. High Card ~ [ A♥ K♣ Q♦ 9♠ 7♥ ]

Five cards that do not interact with each other to make any of the above hands.

Description format: <value>

Examples

Query: "2H 3D 5S 9C KD"
Result: "high card: King"

~

Query: "2H 4D 4S 2C 4H"
Result: "full house: 4 over 2"

~

Query: "6H 7H 8H 9H 10H"
Result: "straight flush: 10-high diamonds"

Requirements

Usage

  • Install with make install.
  • Run linting and tests with make quality test coverage clean.
  • Build the API container with make build, then run API with docker compose up -d.
  • Check API health with curl localhost:8000
  • Query API for rank with e.g. 
    curl -X POST -d '2H 3D 5S 10C KD' localhost:8000/rank