CS21 Lab 7: Songs and Playlists, Top-Down Design
Design is due Sunday, November 1, before midnight.
Full Implementation is due Monday, November 9, before midnight.
Goals
-
Practice using Top-Down Design
-
Write a complex program, with multiple functions, from scratch
-
Read input data from a file
Notes
Please read through the entire lab before starting!
This is a two-part lab, split over two weeks. For the first week you will work with a partner and focus on using top-down design to create the overall structure for the program. Once your proposed structure has been reviewed and approved by your professor or lab instructor, you will each individually use bottom-up implementation to complete the full program.
You have two weeks to complete the full program. The first week is for the design, and the second for the full program. Your initial top-down design is due this Sunday (November 1) and the full implementation is due the following week (November 9). We highly recommended that you submit your top-down design as soon as is possible so that we have time to give you feedback before you begin your full implementation. If you submit your design on the last day at midnight, it might take us a few days to send you valuable comments.
Partnerships will be announced in the lab.
As you write programs, use good programming practices:
-
Use a comment at the top of the file to describe the purpose of the program (see example).
-
All programs should have a
main()function (see example). -
Use variable names that describe the contents of the variables.
-
Write your programs incrementally and test them as you go. This is really crucial to success: don’t write lots of code and then test it all at once! Write a little code, make sure it works, then add some more and test it again.
-
Don’t assume that if your program passes the sample tests we provide that it is completely correct. Come up with your own test cases and verify that the program is producing the right output on them.
-
Avoid writing any lines of code that exceed 80 columns.
-
Always work in a terminal window that is 80 characters wide (resize it to be this wide)
-
In
vscode, at the bottom right in the window, there is an indication of both the line and the column of the cursor.
-
Function Comments
All functions should include a comment explaining their purpose, parameters, return value, and describe any side effects. Please see our function example page if you are confused about writing function comments.
1. Song Data
For this lab assignment, you’ll write a program that helps a user manage a collection of songs. The collection data will be stored in a series of records, each of which contains:
-
song ID— A positive integer that uniquely identifies each song. -
artist— A human-readable string describing the name of the artist. -
title— A human-readable string describing the name of the song. -
duration— A positive integer that represents the song’s length, in seconds.
You will need to support reading this information into your program from a file. Each line of an input file contains information about one song (one "record"). Each line of the file will contain the information described above with a comma between fields. Here is a small example file of song data. You can also access example files at:
-
/usr/local/doc/songs/small.txt -
/usr/local/doc/songs/large.txt
2. Example Output
Here are a few examples of the running program, to help you see how things should work.
3. Top-Down Design Requirements
You and your partner should complete your top-down design (TDD), submit it, and obtain feedback on it before beginning the full implementation. Special procedures for this lab:
-
Work with your partner to produce
design-songs.pyfirst. Please ensure your design meets the following requirements before submitting:-
main()should be completely written, and should perform high-level steps without focusing on details. -
main()should call the functions you create in your design, in the appropriate order, and with arguments that match parameters. Return values should be saved inmain(), even if you don’t do anything with them yet. -
All functions should be stubbed out with parameters, a block comment, and a return statement. They shouldn’t do anything yet, except possibly print that they’re being called and call other functions.
-
If your function is supposed to return something, you should return a dummy value of the appropriate type (e.g. return
0for anint,[1,2,3]for a list, etc.). -
Your design should contain several functions. Each function should be function worthy (i.e., not a trivial task). Each function should also demonstrate encapsulation (one clearly defined purpose).
-
The design should run without syntax errors. (even if it doesn’t do much).
-
-
After you have a working design, you and your partner should both run
handin21to turn it in! After runninghandin21, send an email to tdd@cs.swarthmore.edu, letting us know your design is done. We’ll take a look at each design and send you comments (usually within a day or two). If the design is incomplete or insufficient, you may be asked to submit a second design. -
After you have the design and have heard back from us, copy the file to
songs.py(cp design-songs.py songs.py) and implement the full program. Leavedesign-songs.pyas it is. Work by yourself for the implementation portion of this lab.
Here is a simple example of Top-Down Design.
3.1. Sharing code with your partner
We recommend that you and your partner work together on a single copy of your design. One person can take the lead writing code for a bit while the other person makes suggestions and asks questions. Then you can switch roles.
Once you have completed your design, or if you are taking a break to
work on it later, you can share your code with your partner via the
scp command. This command copies the file from your computer to your
partner’s computer. You and your partner need to be at the same
computer together to do this, as your partner will need to type
his/her/their password to copy the file to their computer.
Before running scp run handin21 to submit your design in case
anything goes wrong with the scp command.
To copy a file from your computer to your partner’s computer, you can
use the following command, replacing the username below with your
partner’s username. For example, if Kevin and Joshua are working
together on Kevin’s account, and he wishes to share his design with
Joshua, whose username is astudent2, he would type in his
cs21/labs/07 directory:
scp design-songs.py astudent2@cslab:cs21/labs/07/
(astudent2@cslab) Password:
# NOTE: When typing the password, no output (e.g. stars) will appear.
This command will copy the file design_songs.py from Kevin’s
lab directory to Joshua’s. Joshua will need to type in his password
to complete the copy. Please copy/paste the command above exactly,
only changing the username (astudent2) to your partner’s username. Note
that this will overwrite any file of the same name on your partner’s
computer, so be careful to go in the right direction! Copy from the
complete version to the incomplete version.
4. Program Requirements
This section contains requirements for how the final program should work. Consider these requirements as you build your design. However, you should not implement any of these requirements in the first week as you focus on the Top-Down Design.
You have some freedom in how you want your application to look and in the functionality you provide. The requirements are:
-
At the start of your program, you should automatically load the
small.txtfile from the path/usr/local/doc/songs/small.txt. This way, you’ll have some records loaded that you can immediately begin using for testing. -
Repeatedly provide the user a menu of options for what they can do with their program. Your program must perform requested actions from the user until they elect to quit. Here are the actions your program must support:
-
Load songs from file. When this option is selected, your program should discard any previously loaded song data, prompt for the name of a file where new data is stored, and load that into a list of records. For this option, you may assume that the user enters a valid file name to read from. It’s fine for your program to crash if given an invalid file. -
Display individual song details. When this option is selected, your program should ask for a song ID and then display information about the matching song (or a message if no such song can be found). When printing song information, you must format it in a tabular format. See the "Tips" section below for formatting suggestions. -
Display all song details. When this option is selected, your program should print the details of every song in a tabular format. See the "Tips" section below for formatting suggestions. -
Add song. When this option is selected, your program should ask the user for information about one new song. Then, your program should add this song to the existing list of records. If the user enters a song ID that already exists for another song, you should prompt them again to select a different ID. That is, users should not be allowed to enter a second song with the same ID as an existing song. The user must also enter a positive duration, and if not, continue prompting them until they do so. -
Build playlist. This option allows the user to add five songs to a playlist. It should repeatedly prompt the user to enter a song ID until the user has entered five valid songs. Use the song IDs to build a playlist that shows the artist, title, and duration for each song and the total duration of the entire playlist. You should not assume that the user will enter a valid song ID. If the user enters an ID that doesn’t exist in your records, continue to prompt them again until they enter a valid ID. The examples below should help to visualize the expectations for playlist behavior. -
Quit. This option allows the user to quit.
-
|
Note that input validation or output formatting is required for many of the options above:
|
4.1. Examples
Here are a few examples of the running program, to help you see how things should work.
5. Tips
-
Do not assume the user enters valid input values. For example, when handling a "Add Song" request, you cannot assume that the user enters a song ID that doesn’t already exist. (Note that you are allowed to assume that the user will input a valid file name to read song data from.)
-
You may assume that the user will enter valid input types. That is, the user will enter a string when you’re expecting a string, and int when you’re expecting an int, etc.
-
As you develop your top-down design, be mindful of the data structure(s) you’ll use to maintain the data in your program, and how this data gets passed around your functions.
-
When building a playlist, you may find it helpful to accumulate into the final playlist string as you go along. You can add a newline character, the sequence
\n, to the end of each line that you accumulate so that the next concatenation starts at the beginning of the next line. -
You can create a formatted string to accumulate using string formatting with placeholders. For example:
s = "hello" num = 10 formatted_string = "%s | %d" % (s, num)Printing the
formatted_stringvariable above would output:hello | 10
-
When printing song information, you can use format strings to help make it look like a nice table, where values are aligned by inserting "padding" spaces to print to a specific width. For example, if you wanted to print an integer in a space that’s always six characters wide, you could use
"%6d"instead of"%d"and python will print extra spaces if the number isn’t five digits long. You can do the same thing with strings and floats. For floats, you can also specify how many digits to display after the decimal. For example,"%8.2f"would pad the whole digits to a width of 8 and format the fractional part at two decimal places. See the string formatting section of the textbook for more details.-
For printing strings with padding, you can left-align them by using a negative number. For example, both
%40sand%-40swill print a string that gets padded to 40 characters, but the former will align the text to the right (padding at the start), and the latter will align the text to the left (padding at the end). -
When printing numbers, you can put leading zeros in the format code to pad with zeros for numbers that don’t require all the spaces. For example, if you print the value
4with%d, you’ll just see4. If you wanted to instead print04(e.g., for the number of seconds in a song), you could use%02d, which means "pad with leading zeroes up to two digits".
-
-
When converting a number of seconds to minutes:seconds, consider using a combination of integer division to determine a number of whole minutes and the modulus operator (
%) to compute a remainder for the number of seconds.
6. Optional Extra Challenge
If you’re interested in an extra challenge:
-
Finish the required parts of the lab as described above first.
-
Preserve your working solution by copying
songs.pyto a new file namedsongs_extra.pyusing thecpcommand. -
Make your optional changes to the
songs_extra.pyfile, leaving yoursongs.pyfile ready for grading.
Add a new menu option: "Save Song File" that prompts the user for a file
name and then writes the contents of your current song records to that file.
You can use a file name like songs.txt to write into the current
directory. After writing the file, if everything worked correctly, you should
be able to read the file you wrote as input in a new run of the program.
7. Answer the Questionnaire
After each lab, please complete the short Google Forms questionnaire. Please select the right lab number (Lab 07) from the dropdown menu on the first question.
Once you’re done with that, you should run handin21 again.
Submitting lab assignments
Remember to run handin21 to turn in your lab files! You may run handin21
as many times as you want. Each time it will turn in any new work. We
recommend running handin21 after you complete each program or after you
complete significant work on any one program.
Logging out
When you’re done working in the lab, you should log out of the computer you’re using.
First quit any applications you are running, including your vscode editor, the browser and the
terminal. Then click on the logout icon (
) and choose "log out".
If you plan to leave the lab for just a few minutes, you do not need to log
out. It is, however, a good idea to lock your machine while you are gone. You
can lock your screen by clicking on the lock
icon.
PLEASE do not leave a session locked for a long period of time. Power may go
out, someone might reboot the machine, etc. You don’t want to lose any work!