CS21 Lab 7: Inventory management, Top-Down Design

Design is due Sunday, March 29, before midnight.

Full Implementation is due Monday, April 6, 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 (March 29) and the full implementation is due the following week (April 6). 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. Inventory Management

For this lab assignment, you’ll write a program that helps a user manage an inventory of items that are available for sale. The inventory data will be stored in a series of records, each of which contains:

  1. A product ID — An integer that uniquely identifies each product.

  2. A description — A human-readable string describing the product.

  3. A price — A floating point value representing the product’s cost.

You will need to support reading this information into your program from a file. Each line of a file contains information about one product (one "record"). Each line of the file will contain the information described above with a comma between fields. Here is an example file of product data. You can also access example files at:

  • /usr/local/doc/inventory/small.txt

  • /usr/local/doc/inventory/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-inventory.py first. 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 in main(), 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 call other functions.

    • If your function is supposed to return something, you should return a dummy value of the appropriate type (e.g. return 0 for an int, [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 handin21 to turn it in! After running handin21, 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 inventory.py (cp design-inventory.py inventory.py) and implement the full program. Leave design-inventory.py as 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_inventory.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_inventory.py from Kevin’s computer to Joshua’s computer. 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. 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. Here are the minimal requirements:

  • At the start of your program, you should automatically load the small.txt file from the path /usr/local/doc/inventory/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 From File. When this option is selected, your program should discard any previously loaded product 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 — we haven’t taught you how to solve that problem.

    • Display Individual Product Details. When this option is selected, your program should ask for a product ID and then display information about the matching product (or a message if no such product can be found). When printing product information, you must format it in a tabular format. See the "Tips" section below for formatting suggestions.

    • Display All Product Details. When this option is selected, your program should print the details of every product in a tabular format. See the "Tips" section below for formatting suggestions.

    • Add Product. When this option is selected, your program should ask the user for information about one new product. Then, your program should add this product to the existing list of records. If the user enters a product ID that already exists for another product, you should prompt them again to select a different ID. That is, users should not be allowed to enter a second product with the same ID as an existing product. The user must also enter a positive price, if not, continue prompting them until they do so.

    • Build Invoice. Prompt the user for a product count, and for each item up to the count, ask the user for a product ID and then a quantity. Use the product IDs and quantities to build an invoice that shows the cost, quantity, and total price for all the items. You should not assume that the user will enter a valid product ID or quantity. For the product 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. For the quantity, the user must enter a positive integer, otherwise continue to prompt them until they do.

    • Quit. This option allows the user to quit.

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 Product" request, you cannot assume that the user enters a product ID that doesn’t already exist.

  • 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 an invoice, you may find it helpful to accumulate into the final invoice 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_string variable above would output:

    hello  |  10

  • When printing product information, you can use format strings to help make it look like a nice table, where values are aligned. For example, you can insert "padding" spaces to align printed values 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.

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 inventory.py to a new file named inventory_extra.py using the cp command.

  • Make your optional changes to the inventory_extra.py file, leaving your inventory.py file ready for grading.

Add a new menu option: "Save Product File" that prompts the user for a file name and then writes the contents of your current product records to that file. You can use a file name like products.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 (logout icon or other 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 xlock 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!