Command-Line Tools & Configuration.

Lesson 01 showed how to run a script from a repeatable local environment. Lesson 02 makes that project useful across different fictional sites without rewriting its source every time. Start by understanding argument strings and work toward a real read-only CLI tool.

• Explain how shells pass argument strings to Python and test parsing from an explicit argv list.
• Construct helpful command-line interfaces using argparse options, required arguments, defaults and choices.
• Validate positive numeric inputs and reject malformed arguments before beginning work.
• Handle Boolean switches and understand why --dry-run is not authorization by itself.
• Resolve configuration in documented CLI > environment > file > built-in precedence without treating empty values as missing.
• Parse and validate JSON settings without executing configuration as Python code.
• Return meaningful status codes and separate report output from diagnostics.
• Build and test a read-only configurable inventory reporter with changed arguments and datasets.

Prerequisite: Complete Projects, Environments & Dependencies or have a working local Python interpreter. If you haven't used argparse before, start with the written explanations below rather than jumping straight to the coding clinic.

A script that always analyzes the same fictional site isn't much of a tool. A command-line interface lets the person running it choose inputs without editing source code. The shell interprets the command text and passes an ordered list of argument strings to Python. sys.argv contains the program name at index zero and the following tokens afterward. For tests and browser practice, pass an explicit list to argparse instead of relying on the hosting interpreter's sys.argv. This gives your functions reproducible behavior without needing access to a real terminal.

import argparse
parser = argparse.ArgumentParser(prog='report.py')
parser.add_argument('--site', required=True)
args = parser.parse_args(['--site', 'HQ'])
print(args.site)

The standard-library argparse module handles recognized options, generated help text, type conversion, and common invalid-command errors. Define the tool's public contract in one function, such as build_parser(), and give every option a descriptive help message. add_argument() registers flags, while parse_args(argv) creates a Namespace from the supplied argument list. Required options demand a value; optional flags may have sensible defaults. This is more maintainable than repeatedly indexing sys.argv by hand.

import argparse
def build_parser():
    parser = argparse.ArgumentParser(description='Offline inventory reporter')
    parser.add_argument('--site', required=True, help='Site to report')
    parser.add_argument('--format', choices=['text', 'json'], default='text')
    return parser
args = build_parser().parse_args(['--site', 'BR1'])
print(args.site, args.format)

Every shell argument starts as text. argparse can apply type=int, type=float, a custom conversion function, or choices to reject unacceptable input before main() runs. A type=int option rejects non-integer text but still accepts negative values, so positive counts need an additional check. Raise argparse.ArgumentTypeError with a helpful message from a converter so users see a usage error rather than a mysterious traceback. For a batch size, zero must be rejected before division, not converted into a default.

import argparse
def positive_int(text):
    try:
        value = int(text)
    except ValueError as error:
        raise argparse.ArgumentTypeError('enter a whole number') from error
    if value <= 0:
        raise argparse.ArgumentTypeError('must be positive')
    return value
parser = argparse.ArgumentParser()
parser.add_argument('--limit', type=positive_int, default=10)
print(parser.parse_args(['--limit', '5']).limit)

print(isinstance(True, int))
print(type(True) is int)

def valid_limit(value):
    return type(value) is int and 1 <= value <= 25

print(valid_limit(True), valid_limit(5))

Boolean command-line switches let a tool change behavior without requiring users to type 'true' or 'false' as strings. action='store_true' makes --dry-run set a Boolean to True and defaults to False when omitted. An opt-in dry-run option is useful, but for any automation capable of making changes, safer design often makes dry-run the default and requires a separate explicit --apply plus authorization for state-changing actions. This lesson's example remains read-only and creates no live changes. Explain exactly what an option would do instead of treating a flag's name as a security guarantee.

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--verbose', action='store_true')
parser.add_argument('--dry-run', action='store_true')
options = parser.parse_args(['--verbose'])
print(options.verbose, options.dry_run)

As tools grow, command-line arguments shouldn't be the only place to store settings. A small JSON configuration file can provide portable non-secret defaults, environment variables can provide deployment-specific values, and CLI options can override values for a specific run. Define one documented precedence order and use it consistently: this course uses explicit CLI flag > environment value > configuration-file value > built-in default. Validate the final effective value after merging sources, and distinguish an absent option from a supplied blank value rather than using `or` everywhere. For this lesson, the configuration is a fictional Python dictionary; no environment variables are read from your computer.

def choose(cli, env, file_value, default):
    for candidate in (cli, env, file_value):
        if candidate is not None:
            return candidate
    return default
print(choose('HQ', 'DCA', 'BR1', 'LOCAL'))

def strict_source(cli, env, default):
    if cli is not None:
        return cli
    return env if env is not None else default

def optional_source(cli, env, default):
    if cli not in (None, ''):
        return cli
    return env if env not in (None, '') else default

print(repr(strict_source('', 'HQ', 'LOCAL')))
print(repr(optional_source('', 'HQ', 'LOCAL')))

A configuration file can contain malformed JSON, missing keys or values of the wrong type. Use json.loads() and catch json.JSONDecodeError for invalid document syntax. Check that the top-level value is a dictionary before reading fields. os.environ.get() returns environment values as strings, so a numeric timeout needs conversion and validation just like a CLI argument. In browser exercises, pass a fictional mapping explicitly to your functions rather than inspecting real host secrets. On a production workstation or CI runner, follow approved ways of providing secrets—never embed example credentials in downloadable learning files.

import json
raw = '{"site":"HQ","format":"text"}'
data = json.loads(raw)
if not isinstance(data, dict):
    raise ValueError('configuration must be an object')
print(data.get('site', 'LOCAL'))

import json
import os

file_text = '{"site": "BR1", "limit": 10}'
file_config = json.loads(file_text)
env_site = os.environ.get('NORTHSTAR_SITE')

site = env_site if env_site is not None else file_config['site']
limit = file_config['limit']
if not isinstance(site, str) or not site.strip():
    raise ValueError('invalid-site')
if type(limit) is not int or not 1 <= limit <= 25:
    raise ValueError('invalid-limit')
print(site.strip(), limit)

# PowerShell:
$env:NORTHSTAR_SITE = 'HQ'
# CMD:
set NORTHSTAR_SITE=HQ
# bash/zsh:
export NORTHSTAR_SITE=HQ

Other programs and schedulers use process exit codes to tell whether a command succeeded. By convention, 0 means success and nonzero means a problem; many tools use 2 for a command-line usage error, which argparse commonly emits for invalid arguments. Write a main(argv=None) function that returns an integer status, and use `raise SystemExit(main())` only at the actual entry point so importing the module doesn't exit. Put machine-readable results on stdout and useful diagnostics on stderr. Do not combine a successful-looking JSON report with an error message on the same output channel.

def main(argv=None):
    if argv == ['--bad']:
        return 2
    print('2 fictional devices')
    return 0
if __name__ == '__main__':
    raise SystemExit(main())

import sys

def main():
    valid = False
    if not valid:
        print('Invalid sample input', file=sys.stderr)
        return 2
    print('{"ok": true}')
    return 0

print('Exit status:', main())

You now have the pieces to make Lesson 01's report configurable. Define build_parser(), parse a supplied argument list, resolve any documented settings, validate input counts and format a report without touching live resources. Keep the data transformation in a pure function and let main(argv) handle parsing, messages and exit codes. A safe first command could be `python inventory_report.py --site HQ --format text --limit 5`. It should operate only on local, fictional data in this stage. When the CLI works for valid arguments, test a missing site, invalid limit, unknown option and changed inventory before calling it ready.

import argparse
def build_parser():
    p = argparse.ArgumentParser(prog='inventory_report.py')
    p.add_argument('--site', required=True)
    p.add_argument('--format', choices=['text','json'], default='text')
    return p
args = build_parser().parse_args(['--site','HQ'])
print(args.site, args.format)

Replace the fictional inventory_report.py file from Lesson 01 with this sample code. This example requires no extra dependencies, writes no files and makes no network requests. Run it using the Python interpreter from your project's virtual environment. The flags choose a site, output format and maximum number of matching records. The optional --dry-run flag annotates a preview; the script never changes real devices or files regardless of that flag.

import argparse
import json

INVENTORY = [
    {'host': 'SW-01', 'site': 'HQ', 'status': 'online'},
    {'host': 'AP-02', 'site': 'HQ', 'status': 'offline'},
    {'host': 'FW-01', 'site': 'BR1', 'status': 'online'},
]

def positive_int(text):
    try:
        value = int(text)
    except ValueError as exc:
        raise argparse.ArgumentTypeError('Enter a whole number') from exc
    if value <= 0:
        raise argparse.ArgumentTypeError('Limit must be positive')
    return value

def build_parser():
    parser = argparse.ArgumentParser(description='Offline, read-only inventory sample')
    parser.add_argument('--site', required=True)
    parser.add_argument('--format', choices=['text', 'json'], default='text')
    parser.add_argument('--limit', type=positive_int, default=10)
    parser.add_argument('--dry-run', action='store_true', help='annotate preview output; no writes')
    return parser

def main(argv=None):
    args = build_parser().parse_args(argv)
    devices = [row for row in INVENTORY if row['site'] == args.site][:args.limit]
    offline = sum(row['status'].strip().lower() == 'offline' for row in devices)
    report = {'site': args.site, 'total': len(devices), 'offline': offline}
    if args.dry_run:
        report['dry_run'] = True
    if args.format == 'json':
        print(json.dumps(report, sort_keys=True))
    else:
        suffix = ' [dry-run]' if args.dry_run else ''
        print(f"{args.site}: {offline}/{len(devices)} offline{suffix}")
    return 0

if __name__ == '__main__':
    raise SystemExit(main())

Safety boundary: This exercise works against the static fictional INVENTORY list. It is not a network scanner or device management utility. A production-facing CLI needs additional controls, credentials, auditability and safe defaults, which subsequent lessons will address.

The first coding challenge requires a function that parses an explicit list of arguments. Start there, then work through defaults, type validation, Boolean options, precedence, JSON configuration, exit status and the independent offline report. You can Run with changed code and Check against several datasets.

Python's standard library documents how argparse handles choices, types, errors and help. Refer to those details when you discover an edge case rather than inferring behavior from a simulated example.