Python Command-Line Arguments: Complete Class Guide
Python Command-Line Arguments: Complete Class Guide
Table of Contents
- Introduction
- What is a CLI?
- Understanding sys.argv
- Introduction to argparse
- Building Advanced CLIs
- Real-World Patterns
- Best Practices
- Hands-On Exercises
- Quick Reference
Introduction
Command-line interfaces (CLIs) are powerful tools that allow users to interact with your Python programs through the terminal. This class will take you from understanding basic command-line arguments to building professional-grade CLI applications.
Learning Objectives
- Understand what CLIs are and why theyβre important
- Master
sys.argvfor basic argument handling - Build sophisticated CLIs with
argparse - Create professional command-line tools
- Handle complex argument patterns and validation
What is a CLI?
Command-Line Interface Basics
A Command-Line Interface (CLI) is a text-based way to interact with programs. Instead of clicking buttons in a graphical interface, users type commands and arguments.
CLI vs GUI
# CLI approach
$ convert image.jpg --resize 800x600 --quality 85 output.jpg
# GUI approach would require:
# 1. Open application
# 2. Click "File" β "Open" β browse to image.jpg
# 3. Click "Image" β "Resize" β type 800, 600
# 4. Click "File" β "Export" β set quality to 85
# 5. Choose location and save
Why CLIs Matter
- Automation: Can be scripted and chained together
# Process hundreds of files automatically for file in *.jpg; do convert "$file" --resize 800x600 "resized_$file" done - Speed: No GUI overhead, direct execution
- Remote Access: Works over SSH, no display needed
- Composability: Unix philosophy - small tools that do one thing well
# Combine tools with pipes $ cat data.txt | grep "error" | wc -l # Count error lines - Reproducibility: Commands can be documented and shared
# Share exact command with colleague python analyze.py --input data.csv --method regression --output results.pdf
Anatomy of a CLI Command
$ python script.py positional --flag --option value --verbose
β β β β β β β
| | | | | | |
Program Script Positional Flag Option Value Flag
argument (with value) (boolean)
Real example:
$ git commit -m "Initial commit" --all
β β β β β
| | | | |
Program | Option Message Flag
Subcommand
Command-Line Argument Types
Before diving into implementation details, letβs clarify the different types of command-line arguments:
python script.py input.txt -v --output result.txt --format json
β β β β β β
positional flag option value option value
Dash conventions:
- Single dash (
-v,-o): Short form, typically one letter - Double dash (
--verbose,--output): Long form, full words for readability - Most arguments support both:
-vand--verbosedo the same thing
Argument types:
- Flags (
-v,--verbose): Boolean switches that are either present or absent - Options (
-o file.txt,--output file.txt): Take values and modify behavior
Both flags and options can use single or double dashes, but options require additional values while flags donβt.
Common flag conventions:
-v,--verbose: Enable detailed output-q,--quiet: Suppress output-f,--force: Skip confirmations-h,--help: Show help message-n,--dry-run: Show what would happen without doing it-r,--recursive: Process directories recursively
Understanding sys.argv
What is sys.argv?
sys.argv is a list containing the command-line arguments passed to a Python script. Itβs the most basic way to handle command-line input.
# script.py
import sys
print(f"Script name: {sys.argv[0]}")
print(f"Arguments: {sys.argv[1:]}")
print(f"Number of arguments: {len(sys.argv) - 1}")
Running it:
$ python script.py hello world 123
Script name: script.py
Arguments: ['hello', 'world', '123']
Number of arguments: 3
Key Points About sys.argv
- argv[0] is always the script name (or path to the script)
- All arguments are strings - even numbers need conversion
- Includes everything - flags, options, values all mixed together
- Order matters - arguments are positional
Basic sys.argv Examples
Example 1: Simple Calculator
# calc.py
import sys
if len(sys.argv) != 4:
print("Usage: python calc.py <number1> <operator> <number2>")
print("Example: python calc.py 10 + 5")
sys.exit(1)
try:
num1 = float(sys.argv[1])
operator = sys.argv[2]
num2 = float(sys.argv[3])
if operator == '+':
result = num1 + num2
elif operator == '-':
result = num1 - num2
elif operator == '*':
result = num1 * num2
elif operator == '/':
if num2 == 0:
print("Error: Division by zero!")
sys.exit(1)
result = num1 / num2
else:
print(f"Unknown operator: {operator}")
print("Supported operators: +, -, *, /")
sys.exit(1)
print(f"{num1} {operator} {num2} = {result}")
except ValueError:
print("Error: Please provide valid numbers")
sys.exit(1)
#TODO Try extending this calculator to support sin, cos operations!
Usage:
$ python calc.py 10 + 5
10.0 + 5.0 = 15.0
$ python calc.py 20 "*" 3 # Note: * needs quotes in bash
20.0 * 3.0 = 60.0
$ python calc.py sin(60) # radians, degrees ?
$ python calc.py cos(60) --units degrees # add an option to specify units
$python calc.py tan(0.5) -u rad # short option
Example 2: File Processor
# process_files.py
import sys
import os
def process_file(filepath):
"""Process a single file."""
if not os.path.exists(filepath):
print(f"Error: File '{filepath}' not found")
return False
with open(filepath, 'r') as f:
lines = f.readlines()
print(f"File: {filepath}")
print(f" Lines: {len(lines)}")
print(f" Size: {os.path.getsize(filepath)} bytes")
return True
def main():
if len(sys.argv) < 2:
print("Usage: python process_files.py <file1> [file2] [file3] ...")
print("Process one or more files and display statistics")
sys.exit(1)
# Process each file provided
files = sys.argv[1:]
success_count = 0
for filepath in files:
if process_file(filepath):
success_count += 1
print() # Empty line between files
print(f"Successfully processed {success_count}/{len(files)} files")
if __name__ == "__main__":
main()
Limitations of sys.argv
While sys.argv works for simple cases, it has significant limitations:
- No built-in help: You must manually write usage instructions
- No validation: All checking is manual
- No type conversion: Everything is a string
- Poor organization: Mixing flags, options, and positional args is messy
- No standard parsing: Each script reinvents the wheel
Example of complexity with sys.argv:
# Trying to handle flags with sys.argv becomes messy
import sys
verbose = False
output_file = None
input_files = []
i = 1
while i < len(sys.argv):
arg = sys.argv[i]
if arg == '-v' or arg == '--verbose':
verbose = True
i += 1
elif arg == '-o' or arg == '--output':
if i + 1 < len(sys.argv):
output_file = sys.argv[i + 1]
i += 2
else:
print("Error: -o requires a filename")
sys.exit(1)
elif arg.startswith('-'):
print(f"Unknown option: {arg}")
sys.exit(1)
else:
input_files.append(arg)
i += 1
# This is getting complicated and we haven't even added:
# - Short flag combinations (-vo instead of -v -o)
# - Default values
# - Type checking
# - Subcommands
# - Help text generation
This is why we use argparse!
Introduction to argparse
What is argparse?
argparse is Pythonβs standard library module for creating professional command-line interfaces. It handles all the complexity of parsing arguments and provides many features automatically.
Basic argparse Structure
import argparse
# 1. Create the parser
parser = argparse.ArgumentParser(description='My awesome program')
# 2. Add arguments
parser.add_argument('filename', help='File to process')
parser.add_argument('-v', '--verbose', action='store_true',
help='Enable verbose output')
# 3. Parse the arguments
args = parser.parse_args()
# 4. Use the arguments
print(f"Processing {args.filename}")
if args.verbose:
print("Verbose mode enabled")
Automatic Features
With just those few lines, argparse automatically provides:
$ python script.py --help
usage: script.py [-h] [-v] filename
My awesome program
positional arguments:
filename File to process
optional arguments:
-h, --help show this help message and exit
-v, --verbose Enable verbose output
Error handling:
$ python script.py
usage: script.py [-h] [-v] filename
script.py: error: the following arguments are required: filename
$ python script.py --invalid
usage: script.py [-h] [-v] filename
script.py: error: unrecognized arguments: --invalid
Types of Arguments
1. Positional Arguments
Required arguments that must appear in a specific order.
parser.add_argument('source', help='Source file')
parser.add_argument('destination', help='Destination file')
# Usage: python script.py input.txt output.txt
# args.source = 'input.txt'
# args.destination = 'output.txt'
2. Optional Arguments (Flags/Options)
Arguments that start with - or --. Can be flags (boolean) or take values.
# Flag (boolean) - using action='store_true'
parser.add_argument('-v', '--verbose', action='store_true',
help='Enable verbose output')
# Option with value
parser.add_argument('-o', '--output', type=str,
help='Output filename')
# Usage: python script.py -v -o result.txt
# args.verbose = True
# args.output = 'result.txt'
3. Optional with Default Values
parser.add_argument('-n', '--number', type=int, default=10,
help='Number of iterations (default: %(default)s)')
# If not provided: args.number = 10
# If provided: python script.py -n 20 β args.number = 20
Argument Actions
The action parameter controls what happens when an argument is encountered:
# store_true: Set to True if flag is present
parser.add_argument('--verbose', action='store_true')
# store_false: Set to False if flag is present
parser.add_argument('--no-cache', action='store_false', dest='cache')
# store_const: Store a constant value
parser.add_argument('--mode-fast', action='store_const',
const='fast', dest='mode')
# append: Accumulate values into a list
parser.add_argument('--include', action='append',
help='Include a file (can be used multiple times)')
# python script.py --include a.txt --include b.txt
# args.include = ['a.txt', 'b.txt']
# count: Count how many times an argument appears
parser.add_argument('-v', '--verbose', action='count', default=0,
help='Increase verbosity (-vvv for level 3)')
# python script.py -vvv β args.verbose = 3
Type Conversion and Validation
# Built-in type conversion
parser.add_argument('--port', type=int, help='Port number')
parser.add_argument('--ratio', type=float, help='Ratio value')
# Custom type function
def positive_int(value):
ivalue = int(value)
if ivalue <= 0:
raise argparse.ArgumentTypeError(f"{value} is not a positive integer")
return ivalue
parser.add_argument('--count', type=positive_int,
help='Positive integer count')
# File type - automatically handles opening files
parser.add_argument('--input', type=argparse.FileType('r'),
help='Input file')
parser.add_argument('--output', type=argparse.FileType('w'),
help='Output file')
Choices and Constraints
# Limit to specific choices
parser.add_argument('--format', choices=['json', 'xml', 'csv'],
default='json',
help='Output format')
# Required optional argument (sounds contradictory but useful!)
parser.add_argument('--config', required=True,
help='Configuration file (required)')
# Mutually exclusive group
group = parser.add_mutually_exclusive_group()
group.add_argument('--verbose', action='store_true')
group.add_argument('--quiet', action='store_true')
# Can't use both --verbose and --quiet
Comprehensive Example
#!/usr/bin/env python3
"""
File processor with comprehensive CLI.
"""
import argparse
import sys
from pathlib import Path
def create_parser():
"""Create and configure argument parser."""
parser = argparse.ArgumentParser(
description='Process files with various options',
epilog='Example: %(prog)s input.txt -o output.txt --format json -v',
formatter_class=argparse.RawDescriptionHelpFormatter
)
# Positional arguments
parser.add_argument('input_file',
type=Path,
help='Input file to process')
# Optional arguments
parser.add_argument('-o', '--output',
type=Path,
help='Output file (default: stdout)')
parser.add_argument('-f', '--format',
choices=['json', 'xml', 'csv', 'text'],
default='text',
help='Output format (default: %(default)s)')
parser.add_argument('--encoding',
default='utf-8',
help='File encoding (default: %(default)s)')
# Processing options
processing_group = parser.add_argument_group('processing options')
processing_group.add_argument('--skip-empty',
action='store_true',
help='Skip empty lines')
processing_group.add_argument('--limit',
type=int,
metavar='N',
help='Process only first N lines')
# Verbosity
verbosity_group = parser.add_mutually_exclusive_group()
verbosity_group.add_argument('-v', '--verbose',
action='count',
default=0,
help='Increase verbosity (-vvv for debug)')
verbosity_group.add_argument('-q', '--quiet',
action='store_true',
help='Quiet mode')
# Advanced feature: multiple values
parser.add_argument('--exclude',
action='append',
default=[],
help='Patterns to exclude (can be used multiple times)')
return parser
def main():
"""Main function."""
parser = create_parser()
args = parser.parse_args()
# Check if input file exists
if not args.input_file.exists():
parser.error(f"Input file does not exist: {args.input_file}")
# Set verbosity level
if args.quiet:
verbosity = -1
else:
verbosity = args.verbose
# Process based on arguments
if verbosity >= 1:
print(f"Processing: {args.input_file}")
print(f"Format: {args.format}")
if args.output:
print(f"Output: {args.output}")
if args.exclude:
print(f"Excluding: {', '.join(args.exclude)}")
# Main processing logic would go here
with open(args.input_file, 'r', encoding=args.encoding) as f:
lines = f.readlines()
if args.skip_empty:
lines = [line for line in lines if line.strip()]
if args.limit:
lines = lines[:args.limit]
# Output results
if verbosity >= 0:
print(f"Processed {len(lines)} lines")
if __name__ == "__main__":
main()