Python Argparse Tutorial: Command-Line Argument Parsing (With Examples)

When writing Python scripts or command-line tools, it’s common to require inputs from users. The argparse module in Python provides a robust way to parse command-line arguments and options, making it easier to create interactive and user-friendly command-line interfaces. In this tutorial, we will explore the argparse module in-depth, covering its various features and providing examples to illustrate its usage.

Table of Contents

1. Introduction to argparse
2. Basic Usage and Concepts
3. Defining Positional Arguments
4. Adding Optional Arguments
5. Handling Different Data Types
6. Customizing Argument Help Messages
7. Advanced Features
   • Subparsers
   • Argument Groups
   • Argument Defaults and Prefixes
8. Real-World Examples
   • Example 1: File Manipulation Tool
   • Example 2: Data Processing Script
9. Conclusion

1. Introduction to argparse

The argparse module is a part of the Python standard library and provides an easy way to parse command-line arguments. It handles the process of defining, validating, and parsing arguments and options that users provide when running a script. argparse helps improve the usability and clarity of command-line interfaces, making scripts more user-friendly and versatile.

2. Basic Usage and Concepts

To use the argparse module, you need to import it:

import argparse

The core components of argparse include:

• ArgumentParser: This class is used to define what arguments and options your script should accept.
• add_argument(): This method is used to specify which arguments and options are supported and how they should be parsed.
• parse_args(): This method is called to parse the command-line arguments provided by the user.

3. Defining Positional Arguments

Positional arguments are the values provided to the script in a specific order. Here’s how you can define and use positional arguments with argparse:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A simple script to greet users')

# Add a positional argument
parser.add_argument('name', help='Name of the user')

# Parse the command-line arguments
args = parser.parse_args()

# Access the value of the positional argument
print(f"Hello, {args.name}!")

In this example, when you run the script with python script.py John, it will output: Hello, John!

4. Adding Optional Arguments

Optional arguments are specified with a flag (e.g., --verbose). They don’t rely on a specific order and are not required. Here’s how you can define and use optional arguments:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A script to calculate the area of a rectangle')

# Add an optional argument
parser.add_argument('--length', type=float, help='Length of the rectangle')
parser.add_argument('--width', type=float, help='Width of the rectangle')

# Parse the command-line arguments
args = parser.parse_args()

# Calculate and print the area
area = args.length * args.width
print(f"The area of the rectangle is {area}")

When running the script with python script.py --length 5 --width 3, it will output: The area of the rectangle is 15.0

5. Handling Different Data Types

argparse provides various argument types that you can use to handle different data types. Some commonly used types include int, float, str, and bool. Here’s an example demonstrating their usage:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A script to calculate the total cost')

# Add arguments of different types
parser.add_argument('--quantity', type=int, help='Quantity of items')
parser.add_argument('--price', type=float, help='Price per item')
parser.add_argument('--discount', type=float, help='Discount percentage')
parser.add_argument('--verbose', type=bool, help='Enable verbose output', default=False)

# Parse the command-line arguments
args = parser.parse_args()

# Calculate the total cost
total_cost = args.quantity * args.price * (1 - args.discount / 100)

# Print the result
if args.verbose:
    print(f"Total cost: ${total_cost:.2f}")
else:
    print(f"Total cost: ${total_cost:.2f}")

By running the script with python script.py --quantity 10 --price 5 --discount 20 --verbose true, it will output: Total cost: $40.00

6. Customizing Argument Help Messages

argparse automatically generates help messages for each argument. However, you can customize these messages to provide more context and guidance to users. Here’s how to do it:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A script to greet users')

# Add a positional argument with custom help
parser.add_argument('name', help='Name of the user')

# Add an optional argument with custom help
parser.add_argument('--age', type=int, help='Age of the user (optional)')

# Parse the command-line arguments
args = parser.parse_args()

# Greet the user
greeting = f"Hello, {args.name}!"
if args.age:
    greeting += f" You are {args.age} years old."
print(greeting)

When running the script with python script.py John --age 25, it will output: Hello, John! You are 25 years old.

7. Advanced Features

Subparsers

Subparsers allow you to create scripts with multiple subcommands, each having its own set of arguments. This is useful for creating complex command-line tools with different modes of operation. Here’s an example:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A script with subcommands')

# Create subparsers
subparsers = parser.add_subparsers(title='Subcommands', dest='subcommand')

# Subcommand 1: greet
greet_parser = subparsers.add_parser('greet', help='Greet a user')
greet_parser.add_argument('name', help='Name of the user')

# Subcommand 2: calculate
calculate_parser = subparsers.add_parser('calculate', help='Perform calculations')
calculate_parser.add_argument('--number', type=int, help='Number to operate on')

# Parse the command-line arguments
args = parser.parse_args()

# Perform actions based on subcommand
if args.subcommand == 'greet':
    print(f"Hello, {args.name}!")
elif args.subcommand == 'calculate':
    result = args.number ** 2
    print(f"Result: {result}")

Running the script with python script.py greet Alice will output: Hello, Alice!

Running the script with python script.py calculate --number 5 will output: Result: 25

Argument Groups

You can organize arguments into groups to improve the structure of your help messages. This is particularly useful when your script has multiple related arguments. Here’s an example:

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A script to process data')

# Create argument groups
input_group = parser

.add_argument_group('Input')
input_group.add_argument('--input-file', help='Input file path')

output_group = parser.add_argument_group('Output')
output_group.add_argument('--output-file', help='Output file path')

# Parse the command-line arguments
args = parser.parse_args()

# Process data based on arguments
if args.input_file:
    print(f"Processing data from {args.input_file}")
if args.output_file:
    print(f"Saving results to {args.output_file}")

Running the script with python script.py --input-file input.txt --output-file output.txt will output:

Processing data from input.txt
Saving results to output.txt

Argument Defaults and Prefixes

You can set default values for arguments and change the default prefix from - to something else. Here’s an example:

# Create an ArgumentParser object with custom prefixes and default values
parser = argparse.ArgumentParser(description='A script to demonstrate argument defaults and prefixes', 
                                 prefix_chars='+-',
                                 formatter_class=argparse.ArgumentDefaultsHelpFormatter)

# Add an optional argument with a default value
parser.add_argument('+n', '--number', type=int, default=10, help='A number (default: 10)')
parser.add_argument('-v', '--verbose', action='store_true', help='Enable verbose output')

# Parse the command-line arguments
args = parser.parse_args()

# Print the parsed arguments
print(f"Number: {args.number}")
print(f"Verbose: {args.verbose}")

Running the script with python script.py +n 5 -v will output:

Number: 5
Verbose: True

8. Real-World Examples

Example 1: File Manipulation Tool

Let’s create a script that performs various file manipulation operations. It supports copying, moving, and deleting files.

import argparse
import shutil
import os

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A file manipulation tool')

# Create subparsers for different operations
subparsers = parser.add_subparsers(title='Operations', dest='operation')

# Subcommand 1: copy
copy_parser = subparsers.add_parser('copy', help='Copy a file')
copy_parser.add_argument('source', help='Source file path')
copy_parser.add_argument('destination', help='Destination file path')

# Subcommand 2: move
move_parser = subparsers.add_parser('move', help='Move a file')
move_parser.add_argument('source', help='Source file path')
move_parser.add_argument('destination', help='Destination file path')

# Subcommand 3: delete
delete_parser = subparsers.add_parser('delete', help='Delete a file')
delete_parser.add_argument('file', help='File path to delete')

# Parse the command-line arguments
args = parser.parse_args()

# Perform operations based on subcommand
if args.operation == 'copy':
    shutil.copy(args.source, args.destination)
    print(f"File copied from {args.source} to {args.destination}")
elif args.operation == 'move':
    shutil.move(args.source, args.destination)
    print(f"File moved from {args.source} to {args.destination}")
elif args.operation == 'delete':
    os.remove(args.file)
    print(f"File {args.file} deleted")

Example 2: Data Processing Script

Let’s create a script that processes data from a CSV file. It supports filtering and summarizing data.

import argparse
import pandas as pd

# Create an ArgumentParser object
parser = argparse.ArgumentParser(description='A data processing script')

# Add an optional argument for input file
parser.add_argument('--input', required=True, help='Input CSV file')

# Add an optional argument for filtering
parser.add_argument('--filter', help='Filter data by column value')

# Add an optional argument for summarizing
parser.add_argument('--summarize', action='store_true', help='Summarize data')

# Parse the command-line arguments
args = parser.parse_args()

# Read data from the input CSV file
data = pd.read_csv(args.input)

# Apply filtering if specified
if args.filter:
    data = data[data['column_name'] == args.filter]

# Summarize data if specified
if args.summarize:
    summary = data.describe()
    print(summary)
else:
    print(data)

9. Conclusion

The argparse module is a powerful tool for creating user-friendly and interactive command-line interfaces for your Python scripts. By defining positional and optional arguments, handling different data types, and customizing help messages, you can create versatile and robust command-line tools. With advanced features like subparsers and argument groups, you can build complex scripts that accommodate various use cases. By following the concepts and examples outlined in this tutorial, you’ll be well-equipped to create effective command-line interfaces for your Python scripts.