Metadata-Version: 2.4
Name: patch-package-py
Version: 0.2.1
Summary: patch 3rd party Python packages
Project-URL: Homepage, https://github.com/nomyfan/patch-package-py
Project-URL: Repository, https://github.com/nomyfan/patch-package-py
Project-URL: Issues, https://github.com/nomyfan/patch-package-py/issues
Author-email: nomyfan <nomyfan@live.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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

```bash
uv add patch-package-py
```

## Agent skill

This repository includes an
[agent skill](skills/patch-package-py/) for AI agents that support agent
skills.

## Usage

The tool provides three main commands via the `p12y` CLI:

### 1. Create a patch workspace

```bash
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:

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

### 2. Commit changes and create patch file

```bash
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:

```bash
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

```bash
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`.

```bash
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
