Metadata-Version: 2.4
Name: pipcheckpoint
Version: 1.0
Summary: Snapshot and restore the pip package state of a Python environment.
Author: InternetOps
Maintainer: github.com/ntrnt-ops
License: MIT
Project-URL: Homepage, https://github.com/ntrnt-ops/pipcheckpoint
Project-URL: Issues, https://github.com/ntrnt-ops/pipcheckpoint/issues
Keywords: pip,environment,checkpoint,snapshot,restore
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# pipcheckpoint

Snapshot the **pip package state** of your Python environment into a named
checkpoint, then restore the environment to that exact state any time by
loading the checkpoint back.

This is *not* a file backup — it captures installed package names/versions
(plus environment metadata), so you can roll an environment back to a known
good set of packages.

## Install

```bash
pip install pipcheckpoint
```

Prefer a direct GitHub install (e.g. unreleased changes)? See
[INSTALL_FROM_GITHUB.md](INSTALL_FROM_GITHUB.md).

The install registers a `pipcheckpoint` command on your PATH. The package can
also be used as a library (see [Library usage](#library-usage)).

## Requirements

- Python 3.9+
- No third-party dependencies (stdlib only)

## Command usage

Checkpoints are stored as JSON files in a default directory, depending on how
the tool runs:

- **Installed via pip** (module): `~/.pipcheckpoint/` (per-user)
- **Standalone** (`pipcheckpoint.py`): `checkpoints/` next to your working
  directory, so checkpoints live with the project you are snapshotting

Point at another location with `--dir`.

### Create a checkpoint

```bash
pipcheckpoint save my-env
```

Captures every installed package in the **current interpreter** (the one the
command runs under), with name, version, and whether it was an editable
install.

### List checkpoints

```bash
pipcheckpoint list
```

### Inspect a checkpoint

```bash
pipcheckpoint show my-env
```

### Restore a checkpoint (exact-state)

```bash
pipcheckpoint load my-env
```

This:
1. installs/upgrades/downgrades packages to match the checkpoint exactly, and
2. uninstalls any packages that are currently installed but **not** in the
   checkpoint.

`pip`, `setuptools`, and `wheel` are never uninstalled. Editable installs in a
checkpoint are restored as normal pinned installs (with a warning).

Preview first without touching the environment:

```bash
pipcheckpoint load my-env --dry-run
```

Skip the confirmation prompt:

```bash
pipcheckpoint load my-env -y
```

### Delete a checkpoint

```bash
pipcheckpoint delete my-env
```

### Run as a module

```bash
python -m pipcheckpoint list
```

### Use standalone (no installation)

A single-file, self-contained build lives at the repo root as
`pipcheckpoint.py`. Copy it anywhere and run it with any Python 3.9+ — no pip
install needed:

```bash
python pipcheckpoint.py save my-env
python pipcheckpoint.py list
```

It supports the exact same subcommands as the installed command. Regenerate it
from the source with `python tools/build_standalone.py`.

## Library usage

The whole API is four functions:

```python
from pipcheckpoint import save_checkpoint, load_checkpoint, list_checkpoints, delete_checkpoint

save_checkpoint("my-env")                 # snapshot current env
plan = load_checkpoint("my-env", dry_run=True)  # preview, nothing changed
load_checkpoint("my-env")                 # restore to that exact state
list_checkpoints()                        # what's saved
delete_checkpoint("my-env")               # remove a checkpoint
```

`save_checkpoint` and `load_checkpoint` take a `dir=` argument to point at a
different checkpoints directory. The default is `~/.pipcheckpoint` when used
as an installed module, and `checkpoints/` in the current directory when run
standalone.

## Notes

- Always run the command with the same Python interpreter (venv) you want to
  snapshot/restore. Since the tool is pip-installed, it lives in the target
  environment.
- The state file records Python version and platform so you can spot
  environment mismatches when loading.
- Pip commands are invoked as `python -m pip ...` against the running
  interpreter.

## Development

```bash
pip install -e .        # editable install, gets the pipcheckpoint command
pipcheckpoint --version
python tools/build_standalone.py   # regenerate the standalone pipcheckpoint.py
```
