# pip-add

A command-line tool that combines package installation and requirements.txt management. Install, update, or remove Python packages and their dependencies with automatic requirements.txt handling.

## Features

- Single command for package management and requirements.txt updates
- Smart dependency handling for installation and removal
- Dependency analysis to prevent breaking other packages
- Flexible version specifications (`>=` by default)
- Optional exact version pinning (`==`)
- Clean, informative output with version information
- Preserves requirements.txt comments and formatting
- Creates requirements.txt if it doesn't exist

## Installation

```bash
# Install from PyPI
pip install pip-add

# Or install latest version
pip install --upgrade pip-add
```

## Usage

### Installation

```bash
# Basic package installation
pip-add requests
# Output:
# Installing requests...
# ✓ Successfully installed requests (2.32.3)
# ✓ Updated requirements.txt

# Install with exact version
pip-add -e requests
# Adds: requests==2.32.3 to requirements.txt

# Install with dependencies
pip-add -d requests
# Output:
# Installing requests...
# ✓ Successfully installed:
#   - certifi (2024.8.30)
#   - charset-normalizer (3.4.0)
#   - idna (3.10)
#   - requests (2.32.3)
#   - urllib3 (2.2.3)
# ✓ Updated requirements.txt
```

### Removal

```bash
# Remove single package
pip-add -r requests
# Output:
# Removing packages...
# ✓ Successfully uninstalled requests (2.32.3)
# ✓ Updated requirements.txt

# Remove package and its unused dependencies
pip-add -d -r requests
# Output:
# Removing packages...
# ✓ Successfully uninstalled:
#   - certifi (2024.8.30)
#   - charset-normalizer (3.4.0)
#   - requests (2.32.3)
#   - urllib3 (2.2.3)
#
# ℹ️  Dependencies kept (required by other packages):
#   - idna (needed by: email-validator, cryptography)
#
# ✓ Updated requirements.txt
```

## Command Line Options

```
pip-add [-h] [-d] [-e] [-r] package

positional arguments:
  package               Package to install or remove

options:
  -h, --help           show this help message and exit
  -d, --dependencies   Include dependencies when installing or removing
  -e, --exact         Use == instead of >= for version specification
  -r, --remove        Remove package(s) and their entries from requirements.txt
```

## How It Works

### Installation Process

1. Installs the specified package using pip
2. Retrieves installed version information
3. With `-d`: tracks and installs all dependencies
4. Updates requirements.txt with new package(s)
5. Uses `>=` by default or `==` with `-e` flag

### Removal Process

1. Analyzes package dependencies
2. Identifies which dependencies are safe to remove
3. Checks if any dependencies are needed by other packages
4. Safely removes unused packages
5. Updates requirements.txt
6. Reports kept dependencies and their dependents

## Safe Dependency Handling

The tool is designed to safely handle dependencies:

- **Installation**: Records all dependencies when using `-d`
- **Removal**: Only removes dependencies that aren't needed by other packages
- **Analysis**: Shows which dependencies were kept and why
- **Protection**: Prevents breaking other installed packages

## Requirements

- Python 3.6+
- pip
- setuptools

## Development

### Local Setup

```bash
# Clone the repository
git clone https://github.com/PacNPal/pip-add.git
cd pip-add

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install in development mode
pip install -e .
```

## Common Scenarios

### New Project

```bash
# First time setup
pip-add -d flask
# Creates requirements.txt and adds Flask with dependencies
```

### Updating Dependencies

```bash
# Update with newer versions
pip-add requests
# Updates to newest version with >= specification
```

### Clean Uninstall

```bash
# Remove package and unused dependencies
pip-add -d -r flask
# Removes Flask and dependencies not used by other packages
```

## Troubleshooting

1. **Package not found in requirements.txt**
   - The file will be created automatically
   - Existing comments are preserved

2. **Dependency conflicts**
   - Uses `>=` by default to minimize conflicts
   - Use `-e` for exact versions when needed

3. **Dependencies not removing**
   - Check the output for dependencies kept
   - Tool will show which packages need them