# Python Environment Setup Guide

**Last Updated:** 2025-11-20

## Overview

The Excel Template Generator system uses Python for advanced Excel features (charts, pivot tables, sparklines) that PhpSpreadsheet cannot generate natively. This guide explains how to set up the Python environment.

## Requirements

- **Python Version:** 3.8 or higher
- **Operating System:** macOS, Linux, or Windows (with WSL recommended)

## Quick Setup

### Automated Setup (Recommended)

```bash
# Run the setup script
chmod +x setup-python-env.sh
./setup-python-env.sh
```

This script will:

1. Check Python version
2. Create a virtual environment (`.venv/`)
3. Install all required dependencies
4. Verify installation

### Manual Setup

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
venv\Scripts\activate

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

## Dependencies

### Core Dependencies

- **openpyxl>=3.1.0** - Excel generation with advanced features

  - Charts (bar, line, pie, scatter, area, column)
  - Pivot tables
  - Sparklines
  - Excel Tables
  - Advanced conditional formatting

- **jsonschema>=4.17.0** - Template validation
  - JSON schema validation
  - Template definition validation

### Optional Dependencies

- **pandas>=2.0.0** - Data manipulation (for complex data processing)
- **pytest>=7.4.0** - Testing framework
- **black>=23.0.0** - Code formatting
- **mypy>=1.5.0** - Type checking

## Virtual Environment

### Why Use a Virtual Environment?

- Isolates dependencies from system Python
- Prevents conflicts with other projects
- Ensures consistent versions across environments
- Easy to recreate if needed

### Activating the Virtual Environment

**macOS/Linux:**

```bash
source .venv/bin/activate
```

**Windows:**

```bash
venv\Scripts\activate
```

### Deactivating

```bash
deactivate
```

## Verification

### Check Python Version

```bash
python3 --version
# Should show: Python 3.9.x or higher
```

### Verify Dependencies

```bash
python3 -c "import openpyxl; print(openpyxl.__version__)"
python3 -c "import jsonschema; print(jsonschema.__version__)"
```

### Test Installation

```bash
# Test openpyxl
python3 -c "from openpyxl import Workbook; wb = Workbook(); print('✓ openpyxl working')"

# Test enhancement script
python3 v2/scripts/enhance-template.py --help
```

## Troubleshooting

### Python Not Found

**macOS:**

```bash
# Install via Homebrew
brew install python3

# Or download from python.org
```

**Linux:**

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv

# Fedora/RHEL
sudo dnf install python3 python3-pip
```

**Windows:**

- Download from https://www.python.org/downloads/
- Make sure to check "Add Python to PATH" during installation

### Virtual Environment Issues

**Permission Denied:**

```bash
chmod +x setup-python-env.sh
chmod +x .venv/bin/activate
```

**Virtual Environment Not Activating:**

```bash
# Recreate virtual environment
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Dependency Installation Issues

**pip Not Found:**

```bash
# Install pip
python3 -m ensurepip --upgrade
```

**SSL/Certificate Issues:**

```bash
# Upgrade pip and certificates
pip install --upgrade pip certifi
```

**Network Issues:**

```bash
# Use alternative index
pip install -r requirements.txt -i https://pypi.org/simple/
```

## Using pyenv (Optional)

If you use `pyenv` for Python version management:

```bash
# Install Python 3.9+
pyenv install 3.11.0

# Set local version
pyenv local 3.11.0

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

The `.python-version` file specifies Python 3.9+ for this project.

## Integration with PHP

The Python scripts are called from PHP using `exec()` or `shell_exec()`. Make sure:

1. Python is in PATH
2. Virtual environment is activated (or use full path)
3. Scripts have execute permissions

**Example PHP call:**

```php
$pythonPath = __DIR__ . '/../../.venv/bin/python3';
$scriptPath = __DIR__ . '/enhance-template.py';
$command = escapeshellcmd($pythonPath) . ' ' . escapeshellarg($scriptPath);
exec($command, $output, $returnCode);
```

## Development Workflow

1. **Activate virtual environment:**

   ```bash
   source .venv/bin/activate
   ```

2. **Run Python scripts:**

   ```bash
   python3 v2/scripts/enhance-template.py input.xlsx enhancements.json output.xlsx
   ```

3. **Run tests:**

   ```bash
   pytest v2/scripts/tests/
   ```

4. **Format code:**

   ```bash
   black v2/scripts/*.py
   ```

5. **Deactivate when done:**
   ```bash
   deactivate
   ```

## CI/CD Integration

For continuous integration, ensure Python environment is set up:

```yaml
# Example GitHub Actions
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: "3.9"

- name: Install dependencies
  run: |
    pip install --upgrade pip
    pip install -r requirements.txt
```

## Best Practices

1. **Always use virtual environment** - Never install packages globally
2. **Pin versions** - Use `requirements.txt` with version pins
3. **Test after setup** - Verify all dependencies work
4. **Document changes** - Update `requirements.txt` when adding dependencies
5. **Keep updated** - Regularly update dependencies for security

## Next Steps

After setting up Python environment:

1. Test the enhancement script: `python3 v2/scripts/enhance-template.py --help`
2. Generate a test template with charts
3. Verify all features work correctly
4. Read the [AI Agent Workflow Guide](AI_AGENT_WORKFLOW.md)