patch-package-py

A Python package patching tool that allows you to make and apply patches to third-party packages in your virtual environment.

Installation

uv add patch-package-py

Agent skill

This repository includes an agent skill for AI agents that support agent skills.

Usage

The tool provides three main commands via the p12y CLI:

1. Create a patch workspace

p12y patch <package_name>

This command:

• Resolves the package from an environment path
  • if omitted, it detects from the current directory (/.venv)
• Creates a temporary virtual environment
• Installs the same version of the package without dependencies
• Sets up a git repository for tracking changes
• Provides a path where you can edit the package files

Example:

p12y patch requests [-e <environment-path>]

2. Commit changes and create patch file

p12y commit <edit_path> [--skip-restore]

After editing the package files, use this command to:

• Generate a git diff of your changes
• Create a .patch file in the patches/ directory
• Reinstall the original package in the target environment
• Apply the new patch to the target environment

Example:

p12y commit /tmp/patch-requests-2.28.1-abc123/venv/lib/python3.11/site-packages/requests

Use --skip-restore to write the patch file and apply it to the current target environment directly.

3. Apply patches

p12y apply [-e <environment-path>]

This command:

• Looks for .patch files in the patches/ directory
• Applies them to the packages in the environment path
  • if omitted, it detects from the current directory (/.venv)
• Reports success/failure for each patch

Workflow

1. Prepare for patching: Run p12y patch <package_name> to set up a workspace
2. Make your changes: Edit the files in the provided path
3. Create the patch: Run p12y commit <path> to generate the patch file
4. Apply patches: Run p12y apply in your project to apply all patches

How it works

• Uses uv for fast virtual environment creation and package installation
• Leverages git for tracking changes and generating diffs
• Reinstalls the target package during commit before applying the newly generated patch
• Stores patch files in a patches/ directory in your project root
• Patch files are named using the format: <package-name>+<version>.patch

Using with Poetry

• Detect the environment path using poetry env info --path.
• Use the -e / --env-path option for patch and apply.
• commit reuses the environment path recorded by patch -e.

p12y patch requests -e "$(poetry env info --path)"
p12y commit <edit_path>
p12y apply -e "$(poetry env info --path)"

Requirements

• Python ≥ 3.9
• uv package manager
• git version control system
• patch utility (typically pre-installed on Unix-like systems)
  • for windows you can install
    • using chocolatey: choco install patch
    • using winget winget install --id=GnuWin32.Patch -e
    • or it might be packed with cygwin.

License

MIT