Project Review: Countdown Letters

A simulation of the letters game on the TV show, Countdown

Summary
Introduction

The Countdown Letters project uses the logic from the letters game on Countdown to enable a player to play against the computer (which I call Susie) attempting to get the longest word that they can.

Features

  • Generates a list of random vowels and consonants based upon the number of vowels that the player chooses to use
  • Validates that the word chosen by the player is one within the 'words.txt' file
  • Validates that the word chosen by the player uses only letters from the randomly generated selection of letters
  • Validates that the word chosen by the user exists as an entry in the Oxford English Dictionary's API (British English)
  • Returns a game result and score displaying the winner
  • Looks up the dictionary definition of the word using the Oxford English Dictionary's API (British English). Sometimes this means looking up the associated lemma version of the word.
  • Creates a database entry recording the details of the game.
  • Unlike the TV game show, there is no 30 second clock. This is intended so that recruiters and hiring managers don't have to wait for a countdown timer to expire. I could build in a JavaScript countdown timer if I wanted to have this functionality.

Objectives

The idea for simulating this game came when I had previously used a dataset that I obtained from Kaggle.com when I was doing some data science analysis when learning Pandas. It was a list of 113,809 English words, so I wondered if I could build a simulation of the Countdown Letters game using the word list.

Since then, I have replaced the list with a more suitable one that contains 40,424 words. The new list reduces the number of requests to the API since there are less words in the list that the API considers an invalid word due to the word being an American spelling variant of a word.

The Approach & Solution

My opening goal was to build something that was far simpler than the final product turned out. It was originally designed with the intention of just having a player's word and a computer's answer, however as I thought about the game show's format, I wondered if I could somehow integrate a definition for the game's word when the results of the game are displayed.

This led me to research an API for a dictionary and discover the Oxford Dictionary API which allows me to have 1,000 requests per month using a free 'prototype' account.

I inspected the API using a Jupyter Notebook (the best method I have found yet) and discovered that I would need to perform additional game validation such as confirming that the word chosen by the player appears in the dictionary.

I would also need to retrieve the dictionary definition within the results page.

I wrote out all of the logic and validations that would be required in English and then proceeded to write individual functions that would fulfil each individual part of the game's logic and validation.

At a later stage, following redevelopment of my portfolio, I refactored the project extracting the functions and classes into separate files depending upon whether they were genuine Django views, game logic functions, or validations. This seemed like a sensible approach to refactor the game's code making it more maintainable in the future.

A further development led me to create a database model to store the results of each of the games for reference and later retrieval. This is an example of using a database table to store a program's logic rather than to capture user-defined input from forms.

Evaluation

I am largely happy with the game. I would like to get a definitive list of permissible words from the Oxford Dictionaries API as that could reduce the number of API calls to check for a word's presence in the dictionary.

Languages, Technologies & Skills Used

In approximate order of frequency used...
Languages: Python, HTML, Sass
Frameworks / Services: Django, Bootstrap, Font Awesome
Software: VS Code
Libraries: os, random, urllib, requests
Notable Packages: N/A
API: Oxford Dictionaries
Infrastructure: GitHub, Docker, Poetry

Sources

Information and rules of the game was sourced from http://wiki.apterous.org/Letters_game