Build a Small CLI with argparse

Select a timestamp to watch that moment on YouTube.

1. 00:00

   A useful command-line tool needs to understand options, defaults, and mistakes. A user may ask for JSON output and a limit of five rows. The shell passes those tokens as strings; it does not give our Python function a ready-made integer or validated format. We could manually scan a list and convert values, but that quickly becomes fragile when options arrive in a different order or someone misspells one. Python's standard-library argparse gives us a parser that describes the command's grammar. In this lesson, we will run a deliberately unsupported format, read the error, build a small report parser, then test defaults, conversions, and a positive-number rule.

2. 00:44

   The browser console cannot rely on a local shell's arguments, so its practical task passes an explicit list like `['--format', 'json', '--limit', '5']`. A real script can use the same parser with process arguments at its entry point. We keep parsing separate from any file or network work so the examples run the same way on every machine. Think of the parser as the boundary between untrusted text supplied by a person and the typed values the rest of the report program is allowed to use. The parser refuses xml because we declared only text and json. In a normal terminal, argparse would also print a usage line and an invalid-choice explanation, then exit with status two.

3. 01:31

   This demonstration catches the exit and redirects its usage text only to make the output stable for our recording. The important behavior remains: a wrong option is an error. Quietly changing xml to text would mislead the user into thinking their request was honored. Choices handle this kind of syntax-level restriction. We also want an integer limit, so we can declare `type=int`; argparse will reject a token like “many.” But it will happily parse zero or negative two, because both are valid integers. The application still needs its own rule that a report limit must be positive.

4. 02:11

   Keep those layers separate: argparse converts and checks the command grammar, then our function validates the domain meaning. This separation makes error handling and testing much clearer. Nothing has crashed because zero is a perfectly valid integer token. `type=int` answered only the conversion question: can these characters become an int? It did not know that a zero-row report is meaningless for our example. We need a second check after parsing. A reusable `parse_report_args(argv)` function can raise ValueError with a specific message when limit is below one. A full command-line entry point might call `parser.error` instead, which displays usage and exits; the reusable core can let the caller choose how to present the failure.

5. 03:00

   We should also decide whether unknown flags are accepted. Here they are not. `parse_args` rejects them, catching typos like `--limt`. `parse_known_args` has a real use when forwarding leftovers to another program, but silently discarding unknown tokens in this tool would hide mistakes. Finally, the browser task must pass an explicit argv list. Calling `parse_args()` with no argument would read whatever arguments launched the Python process, which is unrelated to the sample command and makes tests unreliable. The parser creates named options from the supplied tokens. The format choice is limited to text or json, with text as the default.

6. 03:43

   The limit token is converted to int and defaults to ten. We then apply the positive-number rule and return a small tuple that the report-writing code can use. The first call gives an explicit format and limit; the second shows both defaults. Each call builds its own parser here for clarity, although a larger application could construct the parser once and reuse it. The order of named options is not important: `--limit 5 --format json` yields the same result. Keep help enabled in a normal command-line program so a user can request `--help`; add_help=False only keeps this exercise's output focused.

7. 04:24

   Also think about where errors are displayed. argparse's own errors usually print to stderr and exit; our added ValueError should be turned into a clear user-facing message by the entry point, not swallowed and replaced with a mysterious empty report. The assertions cover defaults, a different option order, an invalid positive range, and a format outside choices. They test the parser function without writing a report file or reading any shell-specific state. That makes the exercise repeatable in the browser and locally. If a hidden check fails, inspect which layer owns the rule. Argparse already converts a supplied integer and rejects an unknown format.

8. 05:08

   Your code must still reject zero and negatives and return the parsed values rather than placeholders. A full CLI needs more than this core: help text, a useful exit message, actual report generation, and tests for its output. We have deliberately isolated the part that turns tokens into trusted options. The same approach works for batch utilities and maintenance scripts: describe the command grammar explicitly, validate domain ranges after parsing, and keep command-line input separate from the work the command performs. Try the solved examples on the matching PythonLessonLab page, then complete the checked function and quiz before extending it with another option of your own.

9. 05:52

   A useful next test is a misspelled flag such as `--limt`; let the parser reject it so the user can correct the command rather than wondering why the report ignored their request.