Skip to content

Programming Assignment(PA) 2: Squared


Letter Boxed(links to the original game) is a word puzzle game created by The New York Times. In this game, letters are arranged on the sides of a square. Imagine a square, and each side of the square has some different letters on it.

Letter Boxed
credit: The New York Times

How to Play

We are creating a solo version of the game, that we will call Squared. Your goal is to make words using these letters. You can jump from one side of the square to another to pick your letters, but there are a few rules:

You can use the same letter again in a single word, however you can't pick two letters in a row from the same side. Example: "TAROT" is accepted, "PARROT" is not. Your word has to be at least three letters long and the word must start with the last letter of the previous word if available.

Plus, it has to be a valid word!

In this PA, we will create Python modules and functions to develop a text-based version of Squared.

But, how do we get a collection of valid words in Python?

The Natural Language Toolkit (NLTK) is used in Python programs to work with natural language data. It provides easy-to-use interfaces to over 50 corpora and lexical resources, such as WordNet.

To use NLTK:

  • Install NLTK using pip with the command "pip install nltk".
  • Import nltk package in your script
  • Some functionalities of NLTK require additional datasets or corpora. Download the necessary resources using
    • For instance, to download resources like the collection of English words, use'words').
  • NLTK provides access to many text corpora.
    • For example, to explore the Words corpus, you can start by importing it with from nltk.corpus import words and then use words.words() to get a list of words.

Available Files:

  • (Docstrings and Constants provided – Part A)
  • (Docstrings and some functions provided – Part B)
  • square.txt (Sample text file for side letters)

You will primarily be working with functions within two modules-

On opening the file, you'll notice four key constants that set the foundation for our game's rules:

MIN_WORD_LENGTH: The shortest word players are allowed to submit, set to 3 for our game. NUM_SIDES: The total number of sides on the letter box, which is 4, representing a square. LENGTH_EACH_SIDE: Number of letters each side of the box has, with our game using 3. MAX_ATTEMPTS: The limit on word submissions per player, which will be 6 in our version.

The module further contains 2 functions.

get_all_valid_words function creates a file of unique, non-repeating words using the NLTK package. Each word is written on a new line, ensuring no duplicate words.

get_sides function reads a file that contains lines of text (four lines in this case) and extracts letters from each line. These letters are grouped into separate lists, representing the four sides of a square. Make sure there are no newline characters. Check this sample file square.txt to understand the format of the content that will be processed.

for the content in square.txt, get_sides("square.txt") returns [ ['L', 'E', 'S'], ['Z', 'Y', 'N'], ['I', 'T', 'C'], ['J', 'O', 'A'] ]


The file includes a range of utility functions designed to facilitate the Squared game play:

get_valid_words_collection function retrieves a collection of valid words from a specified file. It utilizes word_file.get_all_valid_words() function to collect the valid words into a set, which it returns. It reads the words from the file, strips any trailing newline characters, and collects the valid distinct words. It finally returns this collection as a set.

get_side_letters processes a file and extracts letters representing each side of the game board. It utilizes word_file.get_sides() function to get the sides and then collects all the letters from each side into a set, which it returns. This set represents all unique letters available for forming words in the game.

validate_sides_letters function checks the validity of the sides of the game board based on conditions: number of sides must match the NUM_SIDES constant each side length must equal to LENGTH_EACH_SIDE no letter appears more than once across all sides. The function returns True if all conditions are met, otherwise False.

is_word_valid function determines whether a given word is valid for the game. It checks the word length against MIN_WORD_LENGTH, ensures the word has not been previously used in the same round, and verifies that the word starts with the last letter of the previous word (if any). It also ensures that the word exists in the collection of valid words and that no two consecutive letters in the word come from the same side of the game board(square). The function returns a tuple containing a boolean indicating validity and a message stating the result.

get_used_letters function calculates which letters from the game board sides have been used. Given a valid word(be sure to check the validity using is_word_valid), it adds each letter that are also in the game board sides to a set. The function returns a set of those letters from accepted words.

get_scores function checks for the total score after each round. It checks the validity of a word considering the game rules, such as word length, uniqueness, and adherence to the board's letter arrangement. Additionally, it verifies the use of all game board sides (letters) within a set number of attempts. Returns a 0, to indicate that there are more attempts left but not all letters in the sides have been used. It then returns a -1 indicating that the player has failed, i.e., not used all the letters in the sides of the square to create valid words by the maximum allowed attempts. Or if they’ve used all words within the allowed attempts, the function then returns the score accordingly:

  • Used all the letters within 2 or less attempts: Score is 100
  • Used all the letters between 3 - 4 attempts(inclusive): Score is 80
  • Used all the letters between 4-5 attempts: Score is 60
  • Used maximum attempts: Score is 50

play_squared_game (provided - do not change the code), the main function simulating playing our version of the game. It initializes the game by loading the valid words and the board configuration, and it prompts the player to enter words until they reach the maximum number of attempts allowed. It validates each word according to the game rules, tracks used letters and sides, and determines if the player has successfully used letters from all sides to win the game using the utility functions that you wrote.

You can use play_squared_game() to check if your functions are working as intended.

print_board function (provided - do not change the code) is responsible for displaying the game board, used letters and the score.

Ensure your program follows the instructions provided in the docstrings within both the and

Part A - Readiness Quiz + (20 points)

1) Readiness Quiz (10 points) in Canvas.

Make sure to read this document and check the starter code docstring before Part A's deadline. Understand what's required for the assignment and then take the Readiness Quiz on Canvas for 10 points.

The quiz is graded as full points or none; missing any question means you get a 0. You will need to pass the quiz, to get credit for Part A and B.

2) Complete the file (10 pts) and submit this to Gradescope by the deadline for your section.

Be sure to test your word_file module carefully for correctness AND style before submitting into gradescope. You will be limited to 15 submissions for Part A code.

Part B - (70 points Autograder + 10 points by instructor)

You may use valid_words to refer to the collection of words accepted as valid for the game. This is the file that the word_file.get_all_valid_words() must have created.

Upload only your file to Gradescope. You should not include any other file in your submission.

Be sure to complete the following steps:

  • Make sure that works as expected with your finished code.
    • Test your solution thoroughly.
  • Review the style guide to ensure your code meets the style requirements.
    • Run flake8 and eliminate all warnings.
    • Review and update docstrings as needed.

You are limited to a maximum of 25 submissions into Gradescope for Part B.

Programming Assignment Attribution

Provide a short statement describing any assistance that you received on this assignment, either from another student, an online source, an AI-enabled tool, or any other source.