Command-Line Configuration with `argparse`

What are Command-Line Arguments?

Before diving into the code, let's clarify what we mean by "command-line arguments." When you run a Python script from your terminal, you typically type something like python my_script.py. The parts that come after the script name are the arguments. They act as inputs that control the script's behavior.

This is exactly how many professional tools you might have encountered, like git or pip, operate. For example, in pip install pandas, install is a command (an argument) and pandas is another argument specifying the package.

The image below breaks down a typical command, illustrating the different components.

This image illustrates the anatomy of a command-line instruction, identifying the Python executable, the script name, an argument's name (--value), and the argument's value (level).

Our goal is to build scripts that can interpret these kinds of arguments to perform specific tasks, such as running a financial analysis for a given month and year.

Introducing argparse: Your CLI Co-pilot

Python's standard library includes the argparse module, a powerful and convenient tool designed specifically for this purpose. You don't need to install anything; it's ready to use. Using argparse has several key advantages:

• It parses arguments from the command line for you.
• It automatically generates user-friendly help messages (e.g., when a user runs your script with -h or --help).
• It issues clear errors if the user provides invalid arguments.
• It can convert inputs to the correct data type (e.g., from the string '12' to the integer 12).

Let's begin by watching a short video that provides a great introduction to the basics of argparse.

As the video demonstrated, using argparse boils down to three fundamental steps:

1. Import argparse and create a parser object: parser = argparse.ArgumentParser()
2. Define arguments your script should accept: parser.add_argument(...)
3. Parse the arguments from the command line: args = parser.parse_args()

The args object then holds the values passed by the user, which you can access in your code using dot notation (e.g., args.my_argument).

Positional vs. Optional Arguments

argparse handles two main types of arguments:

1. Positional Arguments: These are required and their meaning is determined by their position. In python my_script.py 100 200, 100 and 200 are positional arguments.
2. Optional Arguments: These are identified by a name, not position, and are prefixed with - (short version) or -- (long version). They are typically not required. For example, in python my_script.py --month 11 --year 2023, --month and --year are optional arguments.

For building flexible automation tools for your FP&A tasks, optional arguments are generally more useful because they are self-documenting (the name tells you what the value is for) and you can provide sensible defaults.

Let's explore how to define both types.

Building a Configurable Reporting Script

Now, let's apply these concepts to a practical financial scenario. Imagine we're enhancing the main script from our last lesson, which we might call create_report.py. We want to configure it to run for a specific year and month, and also specify where to save the output report.

Here's how we could define the arguments:

import argparse
import os

def run_report(year, month, output_dir, verbose):
    """
    A placeholder function that simulates generating a report.
    """
    if verbose:
        print(f"Generating report for {month:02d}-{year}...")
        print(f"Output directory: {output_dir}")

    # --- Your report generation logic would go here ---
    # For example, using pandas to read data, DuckDB to transform it...
    
    # Create the output directory if it doesn't exist
    os.makedirs(output_dir, exist_ok=True)
    
    # Simulate saving the report
    report_filename = f"variance_report_{year}_{month:02d}.xlsx"
    report_path = os.path.join(output_dir, report_filename)
    
    # In a real script, you'd save a DataFrame here.
    # For now, we'll just create an empty file.
    with open(report_path, 'w') as f:
        f.write("This is your report.")
        
    print(f"Successfully generated report: {report_path}")

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description="Generate a monthly financial variance report."
    )

    parser.add_argument(
        '--year',
        type=int,
        required=True,
        help="The year of the report (e.g., 2023)."
    )
    
    parser.add_argument(
        '--month',
        type=int,
        required=True,
        choices=range(1, 13),
        help="The month of the report (1-12)."
    )

    parser.add_argument(
        '--output-dir',
        type=str,
        default='reports',
        help="Directory to save the output report. Defaults to 'reports'."
    )
    
    parser.add_argument(
        '-v', '--verbose',
        action='store_true',
        help="Enable verbose output for debugging."
    )

    args = parser.parse_args()

    run_report(
        year=args.year,
        month=args.month,
        output_dir=args.output_dir,
        verbose=args.verbose
    )

Let's break down the new add_argument parameters we've used here:

• type=int: This tells argparse to convert the user's input into an integer. If they provide text, argparse will automatically raise an error.
• required=True: This makes an "optional-style" argument (--year) mandatory. The script won't run unless the user provides it.
• choices=range(1, 13): This restricts the input for --month to integers from 1 to 12. Another automatic validation!
• default='reports': If the user doesn't specify an --output-dir, it will default to the string 'reports', which aligns perfectly with the project structure we created.
• action='store_true': This creates a boolean flag. If the user includes -v or --verbose in their command, args.verbose will be True. If they don't, it will be False. This is perfect for turning features on or off.

Now, from your terminal, you could run this script in several ways:

# Generate a report for November 2023, with verbose output
python src/create_report.py --year 2023 --month 11 --verbose

# Generate a report for February 2024, saving it to a custom directory
python src/create_report.py --year 2024 --month 2 --output-dir "fy24_reports/q1"

# See the automatically generated help message
python src/create_report.py --help

The script is now a flexible tool, not a static piece of code.

Advanced Argument Handling

argparse offers many more features to handle complex requirements. For a deeper look at some of these powerful options, the following video is an excellent resource.

For a comprehensive textual reference on these advanced features, the DataCamp article is again a great resource.

Conclusion

In this lesson, you've learned how to transform a static script into a flexible, configurable command-line tool using argparse. This is a fundamental skill for automation, as it allows you to separate your core logic from the specific parameters of any single run. You can now build one script and reuse it for countless scenarios, a core principle of efficient and "proper" code.

Key Takeaways:

• argparse is Python's standard library for creating command-line interfaces.
• Scripts are made configurable by defining arguments that users can pass when running the script from the terminal.
• Arguments can be positional (required by position) or optional (named with - or --).
• The add_argument() method has powerful parameters like type, default, required, choices, and action to validate input and control behavior.
• Using argparse makes your scripts more robust, reusable, and user-friendly by providing automatic help messages and error handling.

In our next lesson, we'll address another aspect of configuration. While argparse is excellent for parameters that change with each run (like a date), what about settings that are fixed, or sensitive information like API keys or database credentials? Passing these on the command line isn't ideal. We will learn how to manage these by using external configuration files, further separating your code from its configuration.