autopatch 🛠️

autopatch is an intelligent Python dependency upgrade and breaking change migration tool. It detects public API breaking changes between package versions, scans your codebase to find where you use them, and suggests/applies patches automatically.

The Problem

When upgrading packages (e.g., pydantic from v1 to v2, or requests versions), developers face breaking changes:

• Functions or classes get removed.
• Method parameters are renamed or deleted.
• Mandatory arguments are added without defaults.

Currently, developers find these changes through runtime crashes, linters, or reading massive changelogs.

The Solution

autopatch automatically:

1. Downloads and isolates target package versions from PyPI.
2. Parses ASTs of both versions to extract and diff public interfaces.
3. Scans your local codebase to locate usages of deleted or changed symbols.
4. Generates and applies unified diff patches to automatically migrate your codebase (with optional LLM assistance).

Quick Start

Installation

Install autopatch from source:

pip install -e .

Basic Usage

To analyze upgrades for a specific package, specify the package name, the source version, and the target version:

# Scan current directory for breaking changes from package updates
autopatch package_name --from 1.10.0 --to 2.0.0

Auto-Patching

To generate and apply migration patches directly:

# Add --patch to generate and apply fixes (optionally uses OPENAI_API_KEY/GEMINI_API_KEY)
autopatch package_name --from 1.10.0 --to 2.0.0 --patch

Engineering Design

                     ┌──────────────────┐
                     │  User Codebase   │
                     └────────┬─────────┘
                              │ 1. Parse Imports
                              ▼
┌─────────────┐      ┌──────────────────┐      ┌──────────────┐
│  PyPI API   ├─────►│  Package Sources ├─────►│ AST Analyzer │
└─────────────┘ 2.   └──────────────────┘ 3.   └──────┬───────┘
                 Download                             │
                                                      ▼
                                               ┌──────────────┐
                                               │   API Diff   │
                                               └──────┬───────┘
                                                      │ 4. Detect Breaks
                                                      ▼
┌─────────────┐      ┌──────────────────┐      ┌──────────────┐
│ Patch Apply │◄─────┤ Patch Generator  │◄─────┤ Symbol Match │
└─────────────┘ 6.   └──────────────────┘ 5.   └──────────────┘

1. AST Extraction: autopatch uses standard Python ast.NodeVisitor to traverse modules without importing or running the code, keeping the process fast and safe.
2. Diff Signature Validation: Standard signature matching checks positional, keyword-only, default values, and parameter existence.
3. Intelligent LLM Patching: Integrates seamlessly with OpenAI/Gemini APIs to generate context-aware code refactoring.