Capstone: Your First Sprint

Start where Bea starts. The starter writes today's export to disk for you — the same six rows every ticket this week uses — and your job is to read it back and say how big it is.

A CSV's first line is the header, so the number of records is one fewer than the number of lines. Work both out from the file rather than typing them: an export that arrives truncated is exactly the case where a hardcoded number lies.

Deliver: two lines.

7 lines
6 data rows

csv.DictReader reads the header for you and hands back one dictionary per row, keyed by column name. Splitting on commas yourself works right up until a field contains one.

Deliver: the header line as it appears in the file, then one line per row.

region,quantity,price
eu 3 1250
us 4 300
eu 2 500
jp 1 900
us 6 500
eu x 100

Two decisions live in this ticket, and the second is the one that matters. Crashing on a bad row means one mid-correction stops the whole morning. Skipping it silently means the totals quietly shrink and nobody finds out. Skip it, count it, and say so.

int("x") raises ValueError. Catch that specifically — a bare except would also swallow the typo in your own code.

Deliver: the usable rows converted to numbers, and the two counts.

loaded 5
rejected 1

Accumulate into a dictionary keyed by region. defaultdict(int) saves the "have I seen this region before" branch: a key that has never been touched starts at 0, so += works the first time.

Print them sorted by region name, so two runs of the same export produce the same output — a report whose row order moves around is a report people stop trusting.

Deliver: one line per region, alphabetical.

eu 4750
jp 900
us 4200

Put the ranking in a function of its own. rank takes the totals and returns pairs, largest first — no printing, no files. That separation is what lets a test call it with rows it invented, and it is the shape the graded assignment is built around.

sorted takes a key saying what to sort on and reverse=True for descending. Write the key as a named function rather than a lambda if it makes the intent clearer — either is fine, and one of them has a name.

Deliver: rank(summed) returning (region, total) pairs largest first, then the top two printed.

eu 4750
us 4200

A script edited before each run is not a tool. The first thing to move out is whatever you keep changing at the top of the file.

parser = argparse.ArgumentParser(prog="report")
parser.add_argument("path")
args = parser.parse_args(argv)

A positional argument is required and unnamed — the thing the command is about. parse_args takes a list, which is what lets you test it without a shell.

Your task: build a parser taking a path positional and a --region option defaulting to all, then print the two attributes for two different argument lists:

sales.csv all
sales.csv eu

type=int converts and rejects. choices restricts and lists the valid values in the error. Both happen in the parser, so the rest of the program can assume the arguments are sane.

parser.add_argument("--top", type=int, default=3)
parser.add_argument("--format", choices=["csv", "json"], default="csv")

A bad value makes argparse print the usage and exit with code 2 — the conventional code for "you called this wrongly".

Your task: add both, then print the defaults, a converted value with its type, and the exit code from a bad one:

3 csv
5 int
json
exit 2

action="store_true" makes a flag: False by default, True when the option appears. No value follows it.

Watch the name. --dry-run arrives as args.dry_run, because a hyphen cannot be part of an attribute name.

Your task: add --dry-run and --verbose, then print both for three argument lists:

False False
True False
True True

The shape that makes a tool testable is one function taking the arguments and returning the exit code.

def main(argv=None):
    args = parser.parse_args(argv)
    ...
    return 0

Taking argv is what lets a check call main(["sales.csv", "--top", "2"]) without a shell, and passing None makes argparse fall back to the real command line — so the normal path is unaffected.

Your task: write main(argv=None) printing a summary line and returning 0. Call it twice:

reading sales.csv, top 3
0
reading other.csv, top 5
0

The convention is worth following, because other programs depend on it:

A shell script with set -e, a cron job and a CI step all check the code and none of them read the message. Without one, a failure is indistinguishable from a success.

Your task: write main(argv) returning 0 when there are rows to report and 1 when the file is empty. Print a line either way:

3 rows
0
no rows to report
1

Results go to stdout; diagnostics go to stderr. The reason is piping: report sales.csv | mail -s totals team should send the totals, not "rejected 2 rows".

print(row)
print(f"rejected {n} rows", file=sys.stderr)

Both reach a terminal, so a person running it still sees everything. The difference only shows when the output is redirected — which is exactly when it matters.

Your task: print the two data rows to stdout and the two diagnostics to stderr. Only the data will appear in the output below, which is the point:

eu 4750
us 1200

FileNotFoundError already carries the path. Catching it and printing something vaguer is a downgrade — name the file, say what you were doing, put it on stderr, and return a failing code.

Your task: write main(argv) that reads the file and reports its line count, or reports the missing path on stderr and returns 1:

2 lines
0
1

The missing run prints nothing to stdout — its complaint went to stderr — so only its exit code appears.

A dry run reads, validates, and reports what it would do — then stops before changing anything. On a tool that overwrites a file it is the difference between one people will run and one they will not.

if args.dry_run:
    print(f"would write {len(rows)} rows to {args.out}")
else:
    write(args.out, rows)

Your task: write main(argv) honouring --dry-run. The real run writes the file; the dry run says what it would have written and leaves the file alone:

would write 2 rows to out.txt
False
wrote 2 rows to out.txt
True

The booleans are whether the file exists after each run.

sys.exit belongs in the __main__ guard, not inside main. A function that exits the process cannot be called from a test, or reused by another tool.

if __name__ == "__main__":
    sys.exit(main())

The guard also means importing the file runs nothing — the point Modules & the Standard Library made, and the reason one file can be both a tool and a library.

Your task: move the sys.exit out of main and into a guard at the bottom:

2
0
still running
2

The lab runs your code as the main module, so the guard fires and calls main a second time — which is the fourth line, and a useful thing to watch happen. Its sys.exit(0) then ends the program, which is why nothing follows it.