Python Typer Config File CLI Argument Merging

Building command-line interfaces often requires configuration management. Python Typer makes this process elegant and powerful.

You can merge settings from files with command-line arguments. This creates flexible applications that work in different environments.

Why Merge Configuration Files and CLI Arguments?

Many applications need multiple configuration sources. Files provide default settings and environment-specific values.

Command-line arguments offer runtime flexibility. Users can override file settings when needed.

Merging both creates the best user experience. Applications become both configurable and convenient.

Setting Up Your Typer Application

First, install Typer if you haven't already. Use pip to get the latest version.

pip install typer

Create a basic application structure. We'll build a file processing tool as our example.

import typer
from typing import Optional
import json
from pathlib import Path

app = typer.Typer()

@app.command()
def process_files(
    input_dir: str = typer.Argument(..., help="Input directory"),
    output_dir: str = typer.Argument(..., help="Output directory"),
    config_file: Optional[Path] = typer.Option(
        None, help="Configuration file path"
    ),
    verbose: bool = typer.Option(False, help="Enable verbose output"),
    max_files: int = typer.Option(100, help="Maximum files to process")
):
    """Process files with configurable settings."""
    pass

if __name__ == "__main__":
    app()

Reading Configuration Files

Configuration files can use various formats. JSON is popular for its simplicity and readability.

Create a function to load configuration data. Handle missing files and parsing errors gracefully.

def load_config_file(config_path: Path) -> dict:
    """Load configuration from JSON file."""
    try:
        if config_path and config_path.exists():
            with open(config_path, 'r') as f:
                return json.load(f)
        return {}
    except json.JSONDecodeError:
        typer.echo(f"Error: Invalid JSON in {config_path}", err=True)
        raise typer.Exit(1)

This function uses the load_config_file method to read JSON files. It returns an empty dictionary if no file is specified.

Merging Configuration with CLI Arguments

The merging logic determines which values take precedence. CLI arguments should typically override file settings.

Create a configuration merging function. This combines file settings with command-line values.

def merge_configurations(
    file_config: dict, 
    cli_args: dict
) -> dict:
    """Merge file configuration with CLI arguments."""
    merged = file_config.copy()
    
    # CLI arguments override file settings
    for key, value in cli_args.items():
        if value is not None:  # Only override if value is provided
            merged[key] = value
    
    return merged

CLI arguments always take precedence in this approach. This gives users ultimate control at runtime.

Complete Implementation Example

Here's the full implementation with configuration merging. The application processes files with merged settings.

import typer
from typing import Optional
import json
from pathlib import Path

app = typer.Typer()

def load_config_file(config_path: Path) -> dict:
    """Load configuration from JSON file."""
    try:
        if config_path and config_path.exists():
            with open(config_path, 'r') as f:
                return json.load(f)
        return {}
    except json.JSONDecodeError:
        typer.echo(f"Error: Invalid JSON in {config_path}", err=True)
        raise typer.Exit(1)

def merge_configurations(file_config: dict, cli_args: dict) -> dict:
    """Merge file configuration with CLI arguments."""
    merged = file_config.copy()
    
    for key, value in cli_args.items():
        if value is not None:
            merged[key] = value
    
    return merged

@app.command()
def process_files(
    input_dir: str = typer.Argument(..., help="Input directory"),
    output_dir: str = typer.Argument(..., help="Output directory"),
    config_file: Optional[Path] = typer.Option(
        None, help="Configuration file path"
    ),
    verbose: bool = typer.Option(False, help="Enable verbose output"),
    max_files: int = typer.Option(100, help="Maximum files to process")
):
    """Process files with configurable settings."""
    # Load configuration from file
    file_config = load_config_file(config_file)
    
    # Prepare CLI arguments
    cli_args = {
        'verbose': verbose,
        'max_files': max_files
    }
    
    # Merge configurations
    final_config = merge_configurations(file_config, cli_args)
    
    # Use merged configuration
    if final_config.get('verbose'):
        typer.echo(f"Processing files from {input_dir} to {output_dir}")
        typer.echo(f"Maximum files: {final_config.get('max_files')}")
    
    typer.echo(f"Successfully processed with merged configuration!")

if __name__ == "__main__":
    app()

Configuration File Example

Create a configuration file in JSON format. This stores default settings for your application.

{
    "verbose": true,
    "max_files": 50,
    "file_pattern": "*.txt",
    "backup_enabled": false
}

Testing the Configuration Merging

Test your application with different scenarios. Verify that CLI arguments override file settings.

# Using only configuration file
python app.py /input /output --config-file config.json

# Overriding file settings with CLI arguments
python app.py /input /output --config-file config.json --max-files 200 --verbose false

# Using only CLI arguments (no config file)
python app.py /input /output --max-files 75 --verbose true

The output shows how configurations merge. CLI values take priority over file settings.

Processing files from /input to /output
Maximum files: 200
Successfully processed with merged configuration!

Advanced Configuration Strategies

For complex applications, consider multiple configuration sources. You might use environment variables or multiple files.

Implement a configuration loading hierarchy. This provides maximum flexibility for different deployment scenarios.

Learn about Python Typer Global Options with Root Callbacks for application-wide settings. This complements file-based configuration nicely.

Error Handling and Validation

Robust configuration handling requires proper error management. Validate both file contents and merged configurations.

def validate_configuration(config: dict) -> bool:
    """Validate merged configuration."""
    if config.get('max_files', 0) < 0:
        typer.echo("Error: max_files must be positive", err=True)
        return False
    return True

Check out the Python Typer Error Handling Guide for comprehensive error management techniques.

Best Practices for Configuration Merging

Follow these practices for reliable configuration management. They ensure your application works predictably.

Document your configuration options clearly. Users need to understand available settings.

Use sensible defaults for all options. This makes your application work out of the box.

Validate merged configurations before use. Catch errors early in the execution flow.

Consider using Python Typer Global State with Context for sharing configuration across commands.

Conclusion

Configuration file merging with CLI arguments creates flexible applications. Users get the convenience of files with the control of command-line options.

Python Typer makes this pattern straightforward to implement. The merging logic ensures CLI arguments take precedence.

This approach scales well from simple tools to complex applications. Proper error handling and validation make it production-ready.

Start implementing configuration merging in your Typer applications today. Your users will appreciate the flexibility and control.