Metadata-Version: 2.4
Name: pyvdrift
Version: 0.1.0
Summary: Detect environment drift across all your Python projects
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: packaging>=24
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# pyvdrift

Detect environment drift across all your Python projects.

Every Python developer with more than a handful of projects hits this: venvs scattered across your machine, requirements drifting from what's installed, broken interpreters, stale environments. **pyvdrift** is the cross-project health layer that sits on top of whatever tools you already use.

## Install

```bash
pipx install pyvdrift
```

## Quick Start

```bash
pyvdrift scan          # find all Python projects on your machine
pyvdrift check         # diff requirements vs actually installed packages
pyvdrift doctor        # diagnose broken venvs and interpreter mismatches
pyvdrift list          # show all known projects with health status
pyvdrift clean         # remove venvs not touched in N days
pyvdrift watch <path>  # monitor a project for drift in real time
```

## Supported Package Managers

pyvdrift is **tool-agnostic** — it reads whatever format your project uses:

| Tool | Detection | Lockfile |
|------|-----------|----------|
| **uv** | `uv.lock` or `[tool.uv]` | `uv.lock` |
| **Poetry** | `poetry.lock` or `[tool.poetry]` | `poetry.lock` |
| **Pipenv** | `Pipfile` | `Pipfile.lock` |
| **pip** | `requirements*.txt` | — |
| **Hatch** | `[tool.hatch]` | — |
| **PDM** | `pdm.lock` or `[tool.pdm]` | `pdm.lock` |
| **conda** | `environment.yml` | — |
| **setup.py/cfg** | `setup.py` or `setup.cfg` | — |

A single project can use multiple tools simultaneously — pyvdrift detects all of them.

## Commands

### `pyvdrift scan [PATH] [--depth N] [--json] [--save]`

Walk a directory tree and find all Python projects. Default path is `~`, default depth is 5.

### `pyvdrift check [PATH] [--fix] [--json] [--include-dev]`

Compare declared dependencies against what's actually installed in the project's venv. Shows missing packages, version mismatches, and undeclared packages.

### `pyvdrift doctor [PATH] [--json]`

Run all health checks: venv exists, Python binary works, interpreter version matches, deps installed, lockfile in sync, tool available. Exit codes: 0 = ok, 1 = warnings, 2 = errors.

### `pyvdrift list [--depth N] [--sort-by health|name|tool|last-used] [--json]`

Scan + doctor for every project in a compact dashboard.

### `pyvdrift clean [--dry-run] [--older-than DAYS] [--yes]`

Find and remove stale venvs. Dry run by default — pass `--no-dry-run --yes` to actually delete.

### `pyvdrift watch <PATH> [--interval SECONDS]`

Poll a project and re-check on change. Exit with Ctrl+C.

## Design Principles

- **Read-only by default** — never mutates your projects unless you explicitly ask
- **Pure Python** — minimal dependencies, fast startup
- **Tool-agnostic** — works with whatever your project uses
- **Cross-project** — the health layer that no single tool provides
- **stdlib-first** — uses `tomllib`, `configparser`, `ast`, `pathlib` where possible

## License

MIT
