CSP1150/CSP5110 Programming Principles
Assignment 2: Individual programming project (“Board Game Catalogue” program)
Assignment Marks: Marked out of 30, (30% of unit)
Due Date: 5 November 2018, 9:00AM
Background Information
This assignment tests your understanding of and ability to apply the programming concepts we have covered throughout the unit. The concepts covered in the second half of the unit build upon the fundamentals covered in the first half of the unit.
Assignment Requirements
You are required to design and implement two related programs:
• “admin.py”, a CLI program that allows the user to manage the details of a collection of board games which are stored in a text file. Develop this program before “gamefinder.py”.
• “game_finder.py”, a GUI program that uses the data in the text file and allows the user to find games which match the criteria they specify. Develop this program after “admin.py”.
The following pages describe the requirements of both programs in detail.
Starter files for both of these programs are provided along with this assignment brief, to help you get started and to facilitate an appropriate program structure. Please use the starter files.
Pseudocode
As emphasised by the case study of Module 5, it is important to take the time to properly design a solution before starting to write code. Hence, this assignment requires you to write and submit pseudocode of your program design for “admin.py”, but not “game_finder.py” (pseudocode is not very well suited to illustrating the design of an event-driven GUI program). Furthermore, while your tutors are happy to provide help and feedback on your assignment work throughout the semester, they will expect you to be able to show your pseudocode and/or explain the design of your code.
You will gain a lot more benefit from pseudocode if you actually attempt it before trying to code your program – even if you just start with a rough draft to establish the overall program structure, and then revise and refine it as you work on the code. This back and forth cycle of designing and coding is completely normal and expected, particularly when you are new to programming. The requirements detailed on the following pages should give you a good idea of the structure of the program, allowing you to make a start on designing your solution in pseudocode.
See Reading 3.3 for further information and tips regarding writing good pseudocode.
Write a separate section of pseudocode for each function you define in your program so that the pseudocode for the main part of your program is not cluttered with function definitions. Ensure that the pseudocode for each of your functions clearly describes the parameters that the function receives and what the function returns back to the program.
It may help to think of the pseudocode of your program as the content of a book, and the pseudocode of functions as its appendices: It should be possible to read and understand a book without necessarily reading the appendices, however they are there for further reference if needed.
The three functions required in the “admin.py” program are detailed later in the assignment brief.
The following pages describe the requirements of both programs in detail.
Requirements of “admin.py”
“admin.py” is a program with a Command-Line Interface (CLI) like that of the programs we have created throughout the first half of the unit. It allows the user to manage the details of a collection of board games which are stored in a text file named “data.txt”. The program (without optional additions and enhancements) can be implemented in under 150 lines of code – If your program significantly exceeds this, ask your tutor for advice. Everything you need to know in order to develop this program is covered in the first seven modules of the unit. This program should be developed before “game_finder.py”.
This program allows the user to manage details of a collection of board games. The program will allow the user to add details of new games, as well as list, search, view and delete existing games.
A text file named “data.txt” will be used to store the details of games. Use the “json” module to write data to the text file in JSON format and to read the JSON data from the file back into Python. See Reading 7.1 for details regarding this.
To illustrate the structure of the data, below is an example of the file content in JSON format:
[
{
-name-: -The Settlers of Catan-,
-min_players-: 3,
-max_players-: 4,
-duration-: 90,
-min_age-: 10
},
{
-name-: -Race for the Galaxy-,
-min_players-: 2,
-max_players-: 4,
-duration-: 45,
-min_age-: 12
}
] JSON
This example contains two items in a list. Each of those items is a dictionary consisting of 5 items which have keys of “name”, “min_players”, “max_players”, “duration” and “min_age”. If this file was to be read into a Python variable named data, then “data[1]” would refer to the dictionary containing the second game (Race for the Galaxy), and “data[1]['min_age']” would refer to the integer of 12.
Understanding the structure of this data and how you can use it is very important in many aspects of this assignment – in particular, you will need to understand how to loop through the items of a list and how to refer to items in a dictionary. Revise Module 3 and Module 7 if you are unsure about how to interact with lists and dictionaries.
In the following information, numbered points describe a requirement of the program, and bullet points (in italics) are additional details, notes and hints regarding the requirement. Ask your tutor if you do not understand the requirements or would like further information. The requirements are:
1. The first thing the program should do is try to open a file named “data.txt” in read mode, then load the data from the file into a variable named data and then close the file.
? The data in the file should be in JSON format, so you will need to use the “load()” function from the “json” module to read the data into your program. See the previous page for details of the data.
? If any exceptions occur (e.g. due to the file not existing, or it not containing valid JSON data), then simply set the data variable to be an empty list. This will occur the first time the program is run, since the data file will not exist yet.
? This is the first and only time that the program should need to read anything from the file. After this point, the program uses the data variable, which is written to the file whenever a change is made.
2. The program should then print a welcome message and enter an endless loop which starts by printing a list of options: “Choose [a]dd, [l]ist, [s]earch, [v]iew, [d]elete or [q]uit.” and then prompts the user to enter their choice. Once a choice has been entered, use an “if/elif” to respond appropriately (detailed in the following requirements).
? This requirement has been completed for you in the starter file.
3. If the user enters “a” (add), prompt them to enter the game name, then the minimum number of players, maximum number of players, average game duration and minimum player age. The details should then be appended to the data list and written to the text file in JSON format.
? Use your “inputSomething()” function (detailed below) when prompting for the name of the game, to ensure that the user is re-prompted until they enter something other than whitespace.
? Use your “inputInt()” function (detailed below) when prompting for the minimum players, maximum players, duration and minimum player age, to ensure that the user is re-prompted until they enter an integer.
? Once all the values have been entered, append the new game details to the data list (as a dictionary with same keys as shown on the previous page).
? Once the dictionary of game details has been appended to the data list, call your “saveData()” function (detailed below) to write the data to the text file.
4. If the user enters “l” (list), display a list of all games (just the name) preceded by their index number in the data list, or a “No Games Saved” error message if there is nothing in the list.
? Use a “for” loop to iterate through the games in the data list.
? You can use the “enumerate()” function to make sure you have a variable containing the index number of each game as you loop through them (see Lecture 3).
5. If the user enters “s” (search), prompt them for a search term and then list the games whose name contains what they type. Remember to include the index number next to each game.
? If the data list is empty, show a “No Games Saved” message instead of prompting the user for a search term.
? This is a good opportunity to reuse and tweak the code to list all games – the loop body needs an “if” to only print game names that contain the search term (use the “in” operator – see Lecture 3).
? Convert the search term and game name to lowercase to find matches regardless of case.
? Use your “inputSomething()” function (detailed below) when prompting for the search term, to ensure that the user is re-prompted until they enter something other than whitespace.
6. If the user enters “v” (view), prompt them for an index number and then print the corresponding game’s name and other details as shown in the example screenshots below.
? If the data list is empty, show a “No Games Saved” message instead of prompting the user for an index number.
? Use your “inputInt()” function (detailed below) to prompt the user for the index number of the game, to ensure that the user is re-prompted until they enter an integer.
? Display an “Invalid Index Number” message if the user enters an index number that doesn’t exist in
the data list.
7. If the user enters “d” (delete), prompt them for an index number and then delete the corresponding item from the data list, then display a “Game Deleted” message.
? If the data list is empty, show a “No Games Saved” message instead of prompting the user for an index number.
? Use your “inputInt()” function (detailed below) to prompt the user for the index number of the game, to ensure that the user is re-prompted until they enter an integer.
? Display an “Invalid Index Number” message if the user enters an index number that doesn’t exist in the data list.
? Once the game has been deleted from data list, call your “saveData()” function (detailed below) to write the data to the text file.
8. If the user enters “q” (quit), print “Goodbye!” and break out of the loop to end the program.
9. If the user enters anything else, print an “Invalid Choice” message (the user will then be reprompted on the next iteration of the loop).
This concludes the core requirements of “admin.py”. The following pages detail the function mentioned above, the additional requirements for CSP5110 students, optional additions and enhancements, and an annotated screenshot of the program.
Remember that you are required to submit pseudocode for your design of “admin.py”.
Functions in “admin.py”
The requirements above mentioned three functions - “inputInt()”, “inputSomething()”, and “saveData()”. As part of “admin.py”, you must define and use these functions.
1. The “inputInt()” function takes one parameter named prompt. The function should repeatedly re-prompt the user (using the prompt parameter) for input until they enter an integer. It should then return the value as an integer.
? See Workshop 4 for instructions regarding a similar function.
2. The “inputSomething()” function takes one parameter named prompt. The function should repeatedly re-prompt the user (using the prompt parameter) for input until they enter a value which consists of at least one non-whitespace character (i.e. the input cannot be nothing or consist entirely of spaces, tabs, etc.). It should then return the value as a string.
? Use the “strip()” method on a string to remove whitespace from the start and end. If a string consists entirely of whitespace, it will have nothing left once you strip the whitespace away.
? Note that exception handling is not needed in this function.
3. The “saveData()” function takes one parameter named dataList (this will be the data list). The function should open “data.txt” in write mode, then write the dataList parameter to the file in JSON format and close the file. This function does not return anything.
? This is the only part of the program that should be writing to the file, and it always simply overwrites the entire content of the file with the entirety of the current data.
? See Reading 7.1 for an example of using the “json” module. You can specify an additional indent parameter in the “dump()” function to format the JSON data nicely in the text file.
The definitions of these functions should be at the start of the program (as they are in the starter file provided), and it should be called where needed in the program. Revise Module 4 if you are uncertain about defining and using functions, and be sure to implement them so that they receive and return values exactly as described above. In particular, remember that the “prompt” parameter of inputInt() and inputSomething()is for the text that you want to show as a prompt.
You are welcome to write additional functions if you feel they improve your program.
Additional “admin.py” Requirements for CSP5110 Students
If you are in CSP5110, the following additional requirements apply. If you are in CSP1150, you do not need to do implement these requirements (but you are encouraged to do so if you want). Ask your tutor if you do not understand any of the requirements or would like further information.
1. Add 1 to the index number of games whenever the list or search results are shown, so that the list begins at 1 instead of 0. Remember to subtract 1 from the user’s input when viewing or deleting games so that you reference the appropriate index of the data list.
2. As well as ensuring that the user enters an integer, the “inputInt()” function must also make sure that the integer is larger than 0 (i.e. a minimum of 1). Make sure that this requirement is mentioned in the error message that is displayed if an invalid value is entered.
Optional Additions and Enhancements for “admin.py”
The following are suggestions for optional additions and enhancements that you can implement to demonstrate deeper understanding of programming and deliver a product which is more “polished”. They are not required, but you are encouraged to implement them (and others) if you can.
? When searching the games, show a “No results found” message if the search term is not found in any of the games in the data list.
o Be sure to only show this message once per search, not once for every game.
? Add some code to the “add” section that checks if there is already a game in the data list with the same name after the user enters the name of the game. If there is, alert the user to this fact (and the index number of the existing game) and discontinue adding the new game.
o You could also use a loop to re-prompt them until they enter a different name.
? Add a new menu option of “[b]reakdown” which calculates and shows:
o The number of games in the data list.
o The minimum number of players across all games in the data list. o The maximum number of players across all games in the data list.
o The average duration of the games in the data list.
o The average minimum age of the games in the data list.
? Allow users to use the search, view and delete options more efficiently by allowing input of “s search term ”, “v index number ” and “d index number ”. For example, instead of needing to type “s” and then “catan”, the user could type “s catan”, and instead of needing to type “v” then “1”, the user could type “v 1”.
o This feature takes a relatively large amount of extra thought, code and effort.
Program Output Example
Below is an example of a user using “admin.py” to manage the list of games. It demonstrates most of the functionality of the program. CSP5110 requirements are not implemented in this example.
Details of “game_finder.py”
“game_finder.py” is a program with a Graphical User Interface (GUI), as covered in Module 9. The entirety of this program can be implemented in under 150 lines of code – If your program exceeds this, ask your tutor for advice. This program should be developed after “admin.py”. To ensure compatibility and consistency, you must use the “tkinter” module to create the GUI. You will also need to use the “tkinter.messagebox”, and “json” modules.
The program allows the user to find games which match the criteria they specify, using data from the “data.txt” file. The program should load all of the data from the file once only - when the program begins. Here is a screenshot of the program’s GUI and an overview of its functionality:
Label and Entry widgets are used to present the user with a form that allows them to specify the number of players, time available and the age of the youngest player.
A Button widget allows the user to submit the form, triggering a method in the code which searches the data from the text file to find games that match all of the criteria.
The names of matching games are shown here. If the form has not yet been submitted, or if no matching games were found, a message explaining this is shown here instead.
See the content of Module 9 for examples of creating a class for your program’s GUI. A starter file has been provided to assist you. The following pages detail the requirements of the program.
Constructor of the GUI Class of “game_finder.py”
The constructor (the “__init__” method) of your GUI class must implement the following:
1. Create the main window of the program and give it a title of “Game Finder”.
? You may also wish to set other settings such as the minimum size of the window.
2. Try to open the “data.txt” file in read mode and load the JSON data from the file into an attribute named “self.data”, and then close the file.
? If any exceptions occur (due to the file not existing, or it not containing valid JSON data), show an error messagebox with a “Missing/Invalid file” message and use the “destroy()” method on the main window to end the program. Include a “return” statement in the exception handler after destroying the main window to halt the constructor so that the program ends cleanly.
3. The constructor should then use Label, Entry, Button and Frame widgets from the “tkinter” module as needed to implement the GUI depicted on the previous page.
? You will save time if you design the GUI and determine exactly which widgets you will need and how to lay them out before you start writing the code.
? You are welcome change the layout of the GUI, as long as the functionality is implemented.
? See Reading 9.1 for information regarding various settings that can be applied to widgets to make them appear with the desired padding, colour, size, etc.
? The Button that allows users to submit the form should call the “findGames()” method (detailed below) when clicked. You will need to refer to it as “self.findGames”.
? Since no games will be listed under the “Matching Games” heading when the program first loads, make sure that there is initially a label showing a message such as “No criteria submitted.”
4. Finally, the constructor should end by setting the initial focus of the program to the number of players Entry widget, and then calling “tkinter.mainloop()” to start the main loop of the program’s GUI.
That is all that the constructor requires. The following page detail the “findGames()” method, the additional requirements for CSP5110 students and optional additions and enhancements. You are not required to submit pseudocode for your design of “game_finder.py”, as pseudocode is not particularly well suited to illustrating the design of an event-driven GUI program.
The “findGames()” Method of the GUI Class of “game_finder.py”
Your GUI class only requires one method to implement the functionality of the program - “findGames()”. It does not require any parameters other than “self”, which is passed to all methods in a class. The “findGames()” method is called when the user clicks the submit button, and it must do the following:
1. Get the values that the user has typed into the Entry widgets for number of players, time available and age of youngest player, and convert them to integers. If an exception occurs when converting any of the values to an integer, display a messagebox saying “Invalid criteria specified” and do nothing else.
? Use the “get()” method on the Entry widget to retrieve its current value.
2. If no exceptions occurred and all three values were able to be converted to integers, loop through the self.data list and identify any games which match the criteria. Display the names of matching games below the “Matching Games” heading.
? Make sure that you get rid of any message or previous list of game names that may already be there.
? To match the criteria, the number of players must be between the minimum and maximum number of players, the duration must be less than or equal to the time available, and the minimum age must be less than or equal to the age of the youngest player.
? An “else” can go after “except” and will only run if no exception occurred. See end of Lecture 6.
3. If no matching games are found, display a “No matching games” message below the “Matching Games” heading.
? You may wish to create a “noMatches” variable and set it to True before looping through the games, and then set it to False when a game matching the criteria is found. Show the message if the variable is still set to True after the loop.
Additional “game_finder.py” Requirements for CSP5110 Students
If you are in CSP5110, the following additional requirements apply. If you are in CSP1150, you do not need to do implement these requirements (but you are encouraged to do so if you want). Ask your tutor if you do not understand any of the requirements or would like further information.
1. The layout and presentation of your GUI will be assessed more critically. Make appropriate use of frames, alignment, fill/expand and padding settings to create a clear and consistent layout. Use font colour, size or styles to make important text stand out.
2. When showing the results of a search, the program should display the number of matching games and the total number of games, e.g. “3 out of 14 games matched the search.”
Optional Additions and Enhancements for “game_finder.py”
The following are suggestions for optional additions and enhancements that you can implement to demonstrate deeper understanding of programming and deliver a product which is more “polished”. They are not required, but you are encouraged to implement them (and others) if you can.
? Give the program a custom icon and add a suitable background image to the main window.
? Add a second Button next to the Submit button labelled “Choose For Me”. When this button is clicked, matching games are found as normal, but instead of showing the names of all matching games, just one of them is randomly selected to be shown.
? Instead of simply showing the names of matching games in a label, display them using Button widgets that, when clicked, show a messagebox showing all details of the game.
Submission of Deliverables
Once your assignment is complete, submit both the pseudocode for admin.py (in PDF format) and the source code for “admin.py” and “game_finder.py” to the appropriate location in the Assessments area of Blackboard. An assignment cover sheet is not required, but be sure to include your name and student number at the top of all files (not just in the filenames).
Referencing, Plagiarism and Collusion
The entirety of your assignment must be your own work (unless otherwise referenced) and produced for the current instance of the unit. Any use of unreferenced content you did not create constitutes plagiarism, and is deemed an act of academic misconduct. All assignments will be submitted to plagiarism checking software which includes previous copies of the assignment, and the work submitted by all other students in the unit.
Remember that this is an individual assignment. Never give anyone any part of your assignment – even after the due date or after results have been released. Do not work together with other students on individual assignments – helping someone by explaining a concept or directing them to the relevant resources is fine, but doing the assignment for them or alongside them, or showing them your code is not appropriate. An unacceptable level of cooperation between students on an assignment is collusion, and is deemed an act of academic misconduct. If you are uncertain about plagiarism, collusion or referencing, simply contact your tutor, lecturer or unit coordinator and ask.
You may be asked to explain and demonstrate your understanding of the work you have submitted. Always remember that the purpose of an assignment is for you to demonstrate your understanding of the unit content and your ability to apply it to the task presented to you.
Marking Key
Marks are allocated as follows for this assignment. The marks are divided between both programs.
Criteria Marks
Pseudocode
These marks are awarded for submitting pseudocode which suitably represents the design of your source code. As there are no fixed standards for pseudocode, it will be assessed on the basis of “does it help in understanding/describing the structure of the program?” 5
Functionality
These marks are awarded for submitting source code that implements the requirements specified in this brief, in Python 3. Code which is not functional or contains syntax errors will lose marks, as will failing to implement requirements as specified. 15
Code Quality
These marks are awarded for submitting well-written source code that is efficient, wellformatted and demonstrates a solid understanding of the concepts involved. This includes appropriate use of commenting and adhering to best practise. 10
Total: 30