# 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 + macOS/Linux) and integrates seamlessly into your shell so that `pip install` automatically tracks packages.

---

## Features

| Feature | Description |
|---------|-------------|
| `venvy create venv` | Interactively create & configure a venv |
| `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 |
| Shell integration | `venvy +` / `venvy -` for activate/deactivate |
| Existing venv support | Works with any venv, not just venvy-created ones |

---

## Installation

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

# Or with pip (global)
pip install venvy

# Or with pip --user
pip install --user venvy
```

---

## Quick Start

### 1. Initialize a project

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

You'll be asked:

```
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 `.venv/`
- Upgrades pip
- Installs ipykernel (if chosen)
- Installs existing requirements (if any)
- Saves config to `.venvy/config.json`

### 2. Activate / deactivate

**Without shell integration (always works):**
```bash
# macOS / Linux
source .venv/bin/activate

# Windows (cmd)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
```

**With shell integration (recommended):**
```bash
# Set up once:
echo 'eval "$(venvy shell-init)"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

# Then use anywhere:
venvy +    # activate
venvy -    # deactivate
```

### 3. Install packages (auto-tracked)

```bash
# With venvy (always works):
venvy pip install requests httpx

# With shell integration, plain pip works too:
pip install requests httpx
# → automatically added to requirements.txt!

pip uninstall requests
# → automatically removed from requirements.txt!
```

### 4. Clone a project and restore dependencies

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

---

## Shell Integration (Recommended)

Add to your `~/.bashrc` or `~/.zshrc`:

```bash
eval "$(venvy shell-init)"
```

Restart your terminal. Now:

```bash
venvy +              # activates the venv (like npm run)
venvy -              # deactivates the venv

pip install <pkg>    # auto-updates requirements.txt ✓
pip uninstall <pkg>  # auto-removes from requirements.txt ✓
```

### Windows (PowerShell)

Add to your `$PROFILE`:

```powershell
venvy shell-init | Invoke-Expression
```

---

## Commands Reference

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

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                Print shell integration script
venvy +                         Activation hint / activate (shell integration)
venvy -                         Deactivation hint / deactivate (shell integration)

venvy --version                 Show version
```

---

## 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
}
```

Add `.venvy/` to your `.gitignore` or commit it — your choice. Commit `requirements.txt` always.

---

## Using an Existing Venv

venvy works with any existing virtual environment — it doesn't need to have created it. As long as:

1. The venv is active (`$VIRTUAL_ENV` is set), **or**
2. A `.venv`, `venv`, `env`, or `.env` directory exists in the project

venvy will find it and manage `requirements.txt` accordingly.

---

## 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
pip install -e ".[dev]"
pytest
```

---

## License

MIT
