# venvy 🐍

> **Smart Python virtual environment manager — like `package.json` for Python.**

venvy takes the pain out of managing Python virtual environments and `requirements.txt`. It works cross-platform (Windows CMD/PowerShell + macOS/Linux bash/zsh) with **zero shell setup required**.

---

## Features

| Feature | Description |
|---------|-------------|
| `venvy create venv` | Interactively create & configure a venv |
| `venvy +` | **Activate venv — no setup needed, works everywhere** |
| `venvy -` | Deactivate / exit venv shell |
| `venvy pip install <pkg>` | Install + auto-add to requirements |
| `venvy pip uninstall <pkg>` | Uninstall + auto-remove from requirements |
| `venvy status` | Show venv & requirements info |
| `venvy sync` | Install all packages from requirements |
| `venvy list` | List tracked packages |

---

## Installation

```bash
# Recommended: install globally with pipx
pipx install venvy

# Or with pip (global)
pip install venvy
```

---

## Quick Start

### 1. Create a virtual environment

```bash
cd my-project
venvy create venv
```

You'll be asked two questions:

```
venvy — virtual environment setup
────────────────────────────────────────
  [1/2] Install ipykernel (for Jupyter notebook support)? [y/N]: n
  [2/2] Requirements file name [requirements.txt]:
```

venvy then creates the venv, upgrades pip, installs any existing requirements, and saves config.

---

### 2. Activate / deactivate — zero setup, works everywhere

```
venvy +
```

That's it. venvy spawns a new interactive shell with the venv already activated. Your prompt changes automatically:

```
# Windows CMD:
(.venv) D:\my-project>

# macOS/Linux bash:
(.venv) user@machine:~/my-project$
```

To deactivate — just exit the shell:

```
exit
# or:
venvy -
```

> **How it works:** `venvy +` spawns a new shell process with the venv's
> `Scripts/` (Windows) or `bin/` (macOS/Linux) prepended to `PATH` and
> `VIRTUAL_ENV` set — exactly what `source activate` does, but without
> needing to modify the parent shell's environment. No `eval`, no `source`,
> no configuration.

---

### 3. Install packages (auto-tracked in requirements.txt)

```bash
venvy pip install requests httpx
# → installs packages AND adds them to requirements.txt automatically

venvy pip uninstall requests
# → uninstalls AND removes from requirements.txt
```

Or use plain pip when the venv is active (via `venvy +`) — then use `venvy pip` for requirement tracking.

---

### 4. Clone a project and restore dependencies

```bash
git clone https://github.com/user/project
cd project
venvy create venv    # reads existing requirements.txt and installs everything
# or if venv already exists:
venvy sync
```

---

## All Commands

```
venvy create venv [options]     Create virtual environment
  --name  -n    Venv directory name (default: .venv)
  --requirements -r   Requirements file name (prompted if not given)
  --ipykernel         Pre-select ipykernel installation
  --yes -y            Skip all prompts, use defaults

venvy +                         Activate venv (spawns shell, no setup needed)
venvy -                         Deactivate venv / exit

venvy pip install <packages>    Install & track packages
  --upgrade -U  Upgrade packages
venvy pip uninstall <packages>  Uninstall & untrack packages
  --yes -y      Skip confirmation

venvy status                    Show environment info
venvy list                      List tracked packages
venvy sync                      Install all requirements

venvy shell-init                (Optional) print shell integration for native pip tracking

venvy --version                 Show version
```

---

## Works With Existing Venvs

venvy works with any existing virtual environment — it doesn't need to have created it. If a `.venv`, `venv`, `env`, or `.env` directory exists, venvy finds it and manages `requirements.txt` accordingly.

```bash
python -m venv .venv            # created manually
venvy +                         # venvy finds and activates it ✓
venvy pip install flask         # tracked in requirements.txt ✓
```

---

## Project Structure

After `venvy create venv`:

```
my-project/
├── .venv/                  ← virtual environment
├── .venvy/
│   └── config.json         ← venvy project config
├── requirements.txt        ← auto-managed
└── your code...
```

`.venvy/config.json` example:

```json
{
  "venv_name": ".venv",
  "requirements_file": "requirements.txt",
  "install_ipykernel": false
}
```

---

## Optional: Native pip auto-tracking

For plain `pip install` to auto-update `requirements.txt` without using `venvy pip`, add the optional shell integration:

**macOS/Linux** — add to `~/.bashrc` or `~/.zshrc`:
```bash
eval "$(venvy shell-init)"
```

**Windows PowerShell** — add to `$PROFILE`:
```powershell
venvy shell-init | Invoke-Expression
```

This is entirely optional — `venvy pip install` always works without it.

---

## Philosophy

venvy brings `package.json`-style dependency management to Python:

| npm / Node | venvy / Python |
|------------|----------------|
| `npm init` | `venvy create venv` |
| `npm install <pkg>` | `venvy pip install <pkg>` |
| `npm uninstall <pkg>` | `venvy pip uninstall <pkg>` |
| `npm install` (restore) | `venvy sync` |
| `package.json` | `requirements.txt` |
| `node_modules/` | `.venv/` |

---

## Development

```bash
git clone https://github.com/yourorg/venvy
cd venvy
python -m venv .venv
source .venv/bin/activate   # or: venvy +
pip install -e ".[dev]"
pytest
```

---

## License

MIT
