Skip to main content

Command-Line Contracts

What this concept is​

A command-line tool has inputs, outputs and failure behavior just like a function. Arguments select work; standard output carries the result; an error and nonzero exit status indicate that no successful result was produced. The filesystem effects are also part of the contract.

Why it matters here​

Launchpad taught terminal and Git use. Here you design a small tool that can be composed with other tools without guessing what it changed.

Concrete example​

Run python3 cli.py data starter sessions.csv in the extracted lab after implementing the starter. The source file is read-only to the program; the JSON report appears on standard output. Compare its count and topic totals with your hand calculation.

A dangerous composition is redirecting standard output to sessions.csv itself. The shell can truncate that file before Python reads it. The tool's read-only behavior does not protect against destructive shell redirection. Keep reports separate from inputs.

Common confusion / misconception​

A green exit status should not accompany a failed import disguised as an empty result. A traceback is acceptable for this beginner CLI; improving error presentation is optional, but preserving rejection behavior is required. Re-running a report is not the same as re-running a command that appends records.

How to use it​

Declare the working directory and exact argument order. Reproduce the run in a fresh extracted folder. Use a disposable invalid fixture to check nonzero failure and unchanged input bytes. Keep human diagnostic text separate from machine-readable results if you extend the CLI. Use Git to review your changes; terminal and Git instruction is not repeated here.

Check yourself​

Why is a function that preserves its input not enough to prove the whole command preserves the file? The wrapper and shell can add effects outside the function. Test the complete invocation.

Mini drill or application​

Write a five-line README with prerequisites, one successful command, expected summary, one rejection case and file effects. Ask whether another learner could reproduce it without hidden setup.

Read this only if stuck​

Python tutorial: command-line arguments provides the basic interface. The provided wrapper keeps argument parsing out of the first implementation task.