python-venv-manager

What this skill does

# Python Virtual Environment Manager Skill

Python virtual environment management, dependency handling, and project setup automation.

## Instructions

You are a Python environment and dependency expert. When invoked:

1. **Virtual Environment Management**:
   - Create and configure virtual environments
   - Manage Python versions with pyenv
   - Set up isolated development environments
   - Handle multiple Python versions per project
   - Configure environment activation scripts

2. **Dependency Management**:
   - Generate and manage requirements.txt
   - Use modern tools (pip-tools, poetry, pipenv)
   - Lock dependencies with hashes
   - Handle dev vs production dependencies
   - Resolve dependency conflicts

3. **Project Setup**:
   - Initialize new Python projects
   - Configure project structure
   - Set up testing frameworks
   - Configure linting and formatting
   - Create reproducible environments

4. **Troubleshooting**:
   - Fix import errors
   - Resolve version conflicts
   - Debug installation issues
   - Handle platform-specific dependencies
   - Clean corrupted environments

5. **Best Practices**: Provide guidance on Python packaging, versioning, and environment isolation

## Virtual Environment Tools Comparison

### venv (Built-in)
```bash
# Pros: Built-in, no installation needed
# Cons: Basic features, manual workflow

# Create environment
python3 -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Deactivate
deactivate

# Install dependencies
pip install -r requirements.txt
```

### virtualenv (Enhanced)
```bash
# Pros: More features, faster than venv
# Cons: Requires installation

# Install
pip install virtualenv

# Create with specific Python version
virtualenv -p python3.11 venv

# Create with system site-packages
virtualenv --system-site-packages venv
```

### Poetry (Modern, Recommended)
```bash
# Pros: Dependency resolution, packaging, publishing
# Cons: Learning curve

# Install
curl -sSL https://install.python-poetry.org | python3 -

# Create new project
poetry new my-project

# Initialize existing project
poetry init

# Add dependencies
poetry add requests
poetry add --group dev pytest

# Install dependencies
poetry install

# Run commands in virtual environment
poetry run python script.py
poetry run pytest

# Activate shell
poetry shell

# Update dependencies
poetry update

# Show dependency tree
poetry show --tree
```

### Pipenv
```bash
# Pros: Automatic venv, Pipfile format
# Cons: Slower than alternatives

# Install
pip install pipenv

# Install dependencies
pipenv install requests

# Install dev dependencies
pipenv install --dev pytest

# Activate environment
pipenv shell

# Run command
pipenv run python script.py

# Generate requirements.txt
pipenv requirements > requirements.txt
```

### pyenv (Python Version Manager)
```bash
# Install multiple Python versions
# Manage Python versions per project

# Install
curl https://pyenv.run | bash

# Install Python version
pyenv install 3.11.5
pyenv install 3.12.0

# List available versions
pyenv install --list

# Set global version
pyenv global 3.11.5

# Set local version (per directory)
pyenv local 3.11.5

# List installed versions
pyenv versions

# Show current version
pyenv version
```

## Usage Examples

```
@python-venv-manager
@python-venv-manager --setup-project
@python-venv-manager --create-venv
@python-venv-manager --poetry
@python-venv-manager --fix-dependencies
@python-venv-manager --migrate-to-poetry
```

## Project Setup Workflows

### Basic Project with venv
```bash
# Create project directory
mkdir my-project
cd my-project

# Create virtual environment
python3 -m venv venv

# Activate environment
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install requests pytest black flake8

# Freeze dependencies
pip freeze > requirements.txt

# Create .gitignore
cat > .gitignore << EOF
venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.so
*.egg
*.egg-info/
dist/
build/
.pytest_cache/
.coverage
htmlcov/
.env
.venv
EOF
```

### Modern Project with Poetry
```bash
# Create new project with structure
poetry new my-project
cd my-project

# Project structure created:
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── my_project/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

# Add dependencies
poetry add requests httpx pydantic
poetry add --group dev pytest pytest-cov black flake8 mypy

# Install dependencies
poetry install

# Configure pyproject.toml
cat >> pyproject.toml << EOF

[tool.black]
line-length = 88
target-version = ['py311']

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
EOF
```

### Initialize Existing Project
```bash
# Navigate to project
cd existing-project

# Initialize poetry
poetry init

# Follow interactive prompts, then add dependencies
poetry add $(cat requirements.txt)

# Add dev dependencies
poetry add --group dev pytest black flake8

# Create virtual environment
poetry install

# Verify installation
poetry run python -c "import requests; print(requests.__version__)"
```

## Dependency Management

### requirements.txt Best Practices
```bash
# Basic requirements.txt
requests==2.31.0
django==4.2.7
celery==5.3.4

# With hashes for security (pip-tools)
pip-compile --generate-hashes requirements.in

# Separate files
requirements/
├── base.txt          # Common dependencies
├── development.txt   # Dev dependencies
├── production.txt    # Production dependencies
└── testing.txt       # Test dependencies

# development.txt
-r base.txt
pytest==7.4.3
black==23.11.0
flake8==6.1.0

# Install from specific file
pip install -r requirements/development.txt
```

### Using pip-tools (Recommended)
```bash
# Install pip-tools
pip install pip-tools

# Create requirements.in
cat > requirements.in << EOF
django>=4.2,<5.0
requests
celery[redis]
EOF

# Compile to requirements.txt with pinned versions
pip-compile requirements.in

# Install from compiled requirements
pip-sync requirements.txt

# Update dependencies
pip-compile --upgrade requirements.in

# Compile with hashes for security
pip-compile --generate-hashes requirements.in
```

### Poetry Dependency Management
```bash
# Add dependency with version constraint
poetry add "django>=4.2,<5.0"

# Add with specific version
poetry add [email protected]

# Add from git
poetry add git+https://github.com/user/repo.git

# Add from local path
poetry add --editable ./local-package

# Add with extras
poetry add "celery[redis,auth]"

# Update specific package
poetry update django

# Update all packages
poetry update

# Show outdated packages
poetry show --outdated

# Remove package
poetry remove requests

# Export to requirements.txt
poetry export -f requirements.txt --output requirements.txt
poetry export --without-hashes -f requirements.txt --output requirements.txt
```

### Development vs Production Dependencies
```bash
# Poetry approach
[tool.poetry.dependencies]
python = "^3.11"
django = "^4.2"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.11"
flake8 = "^6.1"

# Install without dev dependencies
poetry install --without dev

# Install only specific groups
poetry install --only dev

# pip-tools approach
# requirements.in (production)
django>=4.2
requests

# requirements-dev.in (development)
-r requirements.in
pytest>=7.4
black>=23.11
flake8>=6.1

# Compile both
pip-compile requirements.in
pip-compile requirements-dev.in
```

## Python Version Management

### Using pyenv
```bash
# Install pyenv
curl https://pyenv.run | bash

# Add to shell configuration (.bashrc, .zshrc)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# Install Python versions
pyenv install 3.11.5
pyenv install 3.12.0

# Set global version
pyenv global 3.11.5

# Set local vers