CLI Interface

Main command-line interface providing the pip-upgrade console command with comprehensive options for interactive and automated requirements file upgrading.

Capabilities

Main CLI Entry Point

The primary entry point for the pip-upgrade command-line tool that orchestrates the complete upgrade workflow.

def main():
    """
    Main CLI entrypoint that executes the complete upgrade workflow.
    
    Workflow:
    1. Parse command-line options
    2. Check virtual environment status
    3. Detect requirements files
    4. Parse packages from requirements files
    5. Query PyPI for available upgrades
    6. Present interactive selection or use pre-selected packages
    7. Install packages and update requirements files
    
    Raises:
        KeyboardInterrupt: On user cancellation or validation failures
    """

Command-Line Options Parsing

Parses command-line arguments using docopt and returns a structured options dictionary.

def get_options():
    """
    Parse command-line arguments using docopt.
    
    Returns:
        dict: Options dictionary containing all parsed arguments and flags
    """

Command-Line Arguments

Positional Arguments

pip-upgrade [<requirements_file>] ...

• requirements_file (optional, multiple): The requirement file path(s) or wildcard patterns to multiple files. If not provided, the tool will auto-discover requirements files in the current directory.

Optional Flags

--prerelease

Include prerelease versions for upgrade when querying PyPI repositories.

-p <package> [<package> ...]

Pre-choose which packages to upgrade. Skips the interactive prompt. Special value "all" selects all available upgrades.

--dry-run

Simulates the upgrade process but does not execute the actual upgrade or file modifications.

--skip-package-installation

Only upgrade the version numbers in requirements files, don't install the new packages via pip.

--skip-virtualenv-check

Disable virtualenv check. Allows installing new packages outside of a virtual environment.

--use-default-index

Skip searching for custom index-url in pip configuration files and use the default PyPI index.

Usage Examples

Basic Interactive Usage

# Auto-discover requirements.txt and upgrade interactively
pip-upgrade

# Specify requirements file explicitly
pip-upgrade requirements.txt

# Work with multiple requirements files
pip-upgrade requirements/dev.txt requirements/production.txt

Non-Interactive Usage

# Pre-select specific packages
pip-upgrade requirements.txt -p django -p celery

# Upgrade all available packages
pip-upgrade requirements.txt -p all

Dry Run and Simulation

# Simulate upgrade without making changes
pip-upgrade requirements.txt --dry-run

# Combine with package selection
pip-upgrade requirements.txt -p django --dry-run

Environment and Index Options

# Skip virtualenv validation
pip-upgrade requirements.txt --skip-virtualenv-check

# Only update requirements files, don't install packages
pip-upgrade requirements.txt --skip-package-installation

# Include prerelease versions
pip-upgrade requirements.txt --prerelease

# Use default PyPI instead of custom index
pip-upgrade requirements.txt --use-default-index

Error Handling

The CLI interface handles several types of errors:

• KeyboardInterrupt: User cancellation (Ctrl+C) displays colored "Upgrade interrupted" message
• Virtual environment warnings: Prompts user when not in a virtual environment unless skipped
• No requirements files: Displays helpful message when no valid requirements files are found
• No upgrades available: Shows "All packages are up-to-date" message when appropriate
• Package installation failures: Continues processing other packages and reports failures

Output Format

The CLI provides colored terminal output using the colorclass library:

• Yellow: Informational messages and warnings
• Green: Success messages and up-to-date packages
• Red: Error messages and failures
• Cyan: File names and paths
• Magenta: Dry-run indicators

Tables are formatted using the terminaltables library for clear presentation of upgrade options.