Refactor a sales report generator to code defensively
A teammate wrote a program that reads sales data from a CSV file and prints a report. It works on clean data, but it crashes on real data. In this exercise, you refactor the program so that it’s readable, handles bad data, is documented, and has unit tests. Then you use GitHub Copilot to find and fix a gap you missed.
This exercise takes approximately 40 minutes.
Set up your workspace
You write and run your code in Visual Studio Code. The starter code is in a GitHub repository.
Tip: If you already cloned the repository in another exercise, skip to the next section.
-
Open a new Visual Studio Code window (File > New Window).
-
On the Welcome page, select Clone Git Repository…, or open the Command Palette (Ctrl+Shift+P) and run Git: Clone.
-
Enter the following URL and press Enter:
https://github.com/MicrosoftLearning/mslearn-python-programming.git -
Create a folder for the repository, such as
mslearn-python, and select Select as Repository Destination. -
When the clone completes, select Open.
Review and run the starter code
-
In the Explorer pane, open the
Labfiles/09-sales-report-generatorfolder. It contains three files:File Purpose sales_report.pyThe program you refactor. sales.csvThe sales data. test_sales_report.pyUnit tests that you extend. -
Open
sales.csv. Some rows are intentionally bad:Date,Product,Amount 2024-01-15,Widget A,1500.00 2024-01-15,Widget B,2100.00 2024-01-15,Widget C,INVALID 2024-01-16,Widget A,1200.00 2024-01-16,Widget B 2024-01-17,Widget C,450.00 2024-01-17,Widget A,-50.00Line 4 has a non-numeric amount, line 6 has no amount, and line 8 has a negative amount.
-
Open
sales_report.pyand review the code:Function Purpose parse_sales_rowReads the amount from one row. It already validates the row and raises ValueErrorfor bad data.rdReads the file and returns a list of amounts. avgCalculates the average of the amounts. display_sales_reportPrints the report. The
if __name__ == "__main__":block at the bottom runs the program. It runs only when you run the file directly, so your tests can import the functions without printing a report. -
Open a terminal (Terminal > New Terminal), change to the exercise folder, and run the program:
cd Labfiles/09-sales-report-generator python sales_report.pyThe program crashes. The last line of the error is:
ValueError: could not convert string to float: 'INVALID'parse_sales_rowcorrectly rejected the bad row, but nothing handles the exception, so the program stops. In the next sections, you fix this and the other weaknesses in the code.
Make the code readable
The names rd and avg don’t describe what the functions do. You rename them with VS Code, which updates every place the names are used.
-
Beneath the
# Read sales data from CSV filecomment, right-clickrdin thedefline and select Rename Symbol, or selectrdand press F2. Enterread_sales_dataand press Enter. -
Beneath the
# Calculate statisticscomment, renameavgtocalculate_averagethe same way. -
Check that the calls in
display_sales_reportand in the# Main program flowblock changed too. Run the program again. You get the sameValueErroras before.Renaming changes how the code reads, not how it behaves.
Handle errors
The program has three weaknesses: one bad row stops the whole report, a missing file crashes the program, and an empty list of sales causes a confusing error. In this section, you address each of these issues.
Skip bad rows
A single bad row shouldn’t stop the whole report. parse_sales_row already raises a ValueError for a bad row. You catch that exception in the loop so the program reports the problem and moves on to the next row.
Tip: As you add code, be sure to maintain the correct indentation. Use the existing comments as a guide, entering the new code at the same level of indentation.
-
Beneath the
# Skip a row that parse_sales_row rejects and print its line numbercomment, update the code to the following:try: sales_amounts.append(parse_sales_row(line)) except ValueError as error: print(f"Line {line_number}: {error} - skipped")- The
appendline moves inside thetryblock, so a row is added to the list only ifparse_sales_rowaccepts it. except ValueError as errorruns whenparse_sales_rowraises an exception. The variableerrorholds the message.- The loop already numbers each row with
enumerate(file, start=2). The count starts at2because the header is line 1. You useline_numberto tell the user which row was skipped.
- The
-
Run the program. The report prints, and each bad row is reported:
Reading sales from sales.csv... Line 4: could not convert string to float: 'INVALID' - skipped Line 6: row is missing the amount - skipped Line 8: amount must be greater than zero - skipped Sales Report ======================================== Total Sales: $5,250.00 Average Sale: $1,312.50 Highest Sale: $2,100.00 Lowest Sale: $450.00 Number of Sales: 4 ========================================
Handle a missing file
read_sales_data shouldn’t decide what happens when the file is missing. The code that calls it should. When the file doesn’t exist, open() raises a FileNotFoundError, and the exception passes up to the caller. You catch it in the main program flow.
-
Beneath the
# If the file isn't found, print an error message and use an empty listcomment, update the code to the following:try: sales_amounts = read_sales_data(filename) except FileNotFoundError: print(f"Error: File '{filename}' not found") sales_amounts = []- The call to
read_sales_datamoves inside thetryblock. except FileNotFoundErrorprints a clear message instead of a traceback.sales_amounts = []givesdisplay_sales_reportan empty list, so it prints its “No valid sales data found.” message and the program ends normally.
- The call to
-
To test it, beneath the
# Main program flowcomment, update thefilenameline to the following:filename = "missing.csv" -
Run the program:
Reading sales from missing.csv... Error: File 'missing.csv' not found Sales Report ======================================== No valid sales data found. -
Beneath the
# Main program flowcomment, update thefilenameline back to the following:filename = "sales.csv"
Reject an empty list
display_sales_report checks for an empty list before it calls calculate_average. But other code might call calculate_average directly. With an empty list, the function fails with ZeroDivisionError, which doesn’t explain the real problem. You add a check that raises a clearer exception.
-
Beneath the
# Raise a ValueError if the list of sales amounts is emptycomment, add the following lines:if len(sales_amounts) == 0: raise ValueError("Can't calculate the average of an empty list")- The
ifstatement checks the input before the calculation runs. raise ValueError(...)stops the function with a message that explains what went wrong. The caller decides how to respond.
- The
-
Run the program. The output doesn’t change, because
display_sales_reportnever passes an empty list. You confirm the new check with a unit test later in this exercise.
Document the function
You changed what calculate_average does for an empty list, but a reader can’t tell that from the function’s first line. You add type hints and a docstring so they know what to pass in, what comes back, and what can go wrong.
-
Beneath the
# Add type hints and a docstring that describes the ValueErrorcomment, update the function definition to the following:def calculate_average(sales_amounts: list[float]) -> float: """Return the average of the sales amounts. Raises ValueError if the list is empty. """list[float]shows that the function expects a list of numbers, and-> floatshows that it returns a number.- The docstring describes the result and the exception that you added.
- The
ifstatement and thereturnline beneath the docstring stay the same.
-
Beneath the
# Display reportcomment, hover overcalculate_averagein thedisplay_sales_reportfunction. VS Code shows the docstring and the type hints.parse_sales_rowalready has both, so you can use it as a model.
Add unit tests
Tests confirm that your error handling keeps working when the code changes. You write one test for each place where the program rejects bad input.
-
Open
test_sales_report.py. It has two tests for normal input and two comments that describe the tests you add. -
Beneath the
# Test that calculate_average raises ValueError for an empty listcomment, add the following test:def test_calculate_average_empty_list(self): with self.assertRaises(ValueError): calculate_average([])assertRaisespasses only when the code inside thewithblock raises the exception. Ifcalculate_average([])returns a value or raises a different exception, the test fails.- This test confirms the check that you added to
calculate_average.
-
Beneath the
# Test that parse_sales_row raises ValueError for an amount that isn't a numbercomment, add the following test:def test_parse_sales_row_invalid_amount(self): with self.assertRaises(ValueError): parse_sales_row("2024-01-15,Widget C,INVALID")- The test passes a row with the text
INVALIDwhere the amount belongs. - This test confirms the validation in
parse_sales_row.
Keep both tests indented inside the
TestSalesReportclass, at the same level as the existing tests. - The test passes a row with the text
-
Run the tests from the terminal:
python -m unittest test_sales_report -vtest_calculate_average (test_sales_report.TestSalesReport.test_calculate_average) ... ok test_calculate_average_empty_list (test_sales_report.TestSalesReport.test_calculate_average_empty_list) ... ok test_parse_sales_row (test_sales_report.TestSalesReport.test_parse_sales_row) ... ok test_parse_sales_row_invalid_amount (test_sales_report.TestSalesReport.test_parse_sales_row_invalid_amount) ... ok ---------------------------------------------------------------------- Ran 4 tests in 0.001s OKNote: The test names in the output depend on your Python version. Versions earlier than 3.11 print
test_calculate_average (test_sales_report.TestSalesReport).
Practice with GitHub Copilot
The program handles the problems you knew about. Use GitHub Copilot to look for the ones you didn’t. Open the Copilot Chat panel in VS Code (Ctrl+Alt+I) and try the following prompts. Copilot can make mistakes, so read each response, and run the program and the tests before you accept a change.
Document the rest of the code
“Add a docstring and type hints to
read_sales_dataanddisplay_sales_report. Describe what each function does, what it returns, and what it prints.”
This prompt applies the same documentation you added to calculate_average. Check the result. Does the read_sales_data docstring mention the skipped rows and the FileNotFoundError that it can raise? Are the type hints correct?
Find the gaps
“What inputs could make
read_sales_datacrash or report misleading results? Don’t change the code.”
This prompt asks Copilot to review the code without editing it. Review the list it gives you. To try one possible gap, create an empty file named empty.csv in the exercise folder. Then beneath the # Main program flow comment, update the filename line to the following:
filename = "empty.csv"
Run the program. It crashes with StopIteration, because next(file) finds no header row. Update the filename line back to the following:
filename = "sales.csv"
Fix the gap and prove the fix
“Update
read_sales_dataso that an empty file prints a clear message and returns an empty list. Then add a unit test that checks the fix.”
This prompt asks for both a code change and a test that proves it works. Review the change. Run the program with empty.csv and sales.csv, then run the tests again. Keep the change only if the program and all the tests pass.
You started with a program that crashed on real data. You now have one that reports bad rows, handles missing and empty files, explains itself, and has tests that catch regressions.