python-setup

What this skill does

# Python Development Environment Setup

Complete guide to setting up Python on your computer for Universe 2025 (Tufty) Badge development, including virtual environments and all necessary tools.

## Quick Start (First Time Setup)

If you're brand new and just want to get started quickly:

```bash
# 1. Check if Python is installed
python3 --version
# If not installed, see "Install Python" section below

# 2. Create project directory
mkdir ~/badge-projects
cd ~/badge-projects

# 3. Create virtual environment
python3 -m venv venv

# 4. Activate it
source venv/bin/activate  # macOS/Linux
# venv\Scripts\Activate.ps1 # Windows

# 5. Install badge tools
pip install mpremote

# 6. Test badge connection
mpremote exec "print('Badge connected!')"
# Should print: Badge connected!

# ✓ You're ready! Continue to badger-quickstart skill
```

If any command fails, continue with the detailed instructions below.

## Prerequisites Check

Before starting detailed setup, check what you already have:

```bash
# Check Python version
python3 --version

# Check pip
pip3 --version

# Check if tools are installed
which mpremote
which ampy
which rshell
```

## Install Python

### macOS

**Option 1: Using Homebrew (Recommended)**

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3

# Verify installation
python3 --version
pip3 --version
```

**Option 2: Using python.org installer**

1. Download from https://www.python.org/downloads/
2. Run installer
3. Check "Add Python to PATH"
4. Complete installation

### Linux (Ubuntu/Debian)

```bash
# Update package list
sudo apt update

# Install Python 3 and pip
sudo apt install python3 python3-pip python3-venv

# Verify installation
python3 --version
pip3 --version
```

### Linux (Fedora/RHEL)

```bash
# Install Python 3
sudo dnf install python3 python3-pip

# Verify installation
python3 --version
pip3 --version
```

### Windows

**Option 1: Using winget (Windows 10/11)**

```powershell
# Install Python
winget install Python.Python.3.11

# Restart terminal, then verify
python --version
pip --version
```

**Option 2: Using python.org installer**

1. Download from https://www.python.org/downloads/
2. Run installer
3. **IMPORTANT**: Check "Add Python to PATH"
4. Check "Install pip"
5. Complete installation
6. Restart terminal

**Option 3: Using Microsoft Store**

1. Open Microsoft Store
2. Search for "Python 3.11"
3. Install
4. Verify in terminal

## Create Project Directory

Set up a dedicated directory for Badger 2350 projects:

```bash
# Create project directory
mkdir -p ~/badger-projects
cd ~/badger-projects

# Create your first project
mkdir my-badge-app
cd my-badge-app
```

## Set Up Virtual Environment

Virtual environments isolate project dependencies and prevent conflicts.

### Create Virtual Environment

```bash
# Create venv in project directory
python3 -m venv venv

# Alternative name
python3 -m venv .venv
```

### Activate Virtual Environment

**macOS/Linux:**

```bash
# Activate
source venv/bin/activate

# Your prompt should change to show (venv)
(venv) user@computer:~/badger-projects/my-badge-app$

# Deactivate when done
deactivate
```

**Windows (PowerShell):**

```powershell
# Enable script execution (first time only)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Activate
venv\Scripts\Activate.ps1

# Deactivate when done
deactivate
```

**Windows (Command Prompt):**

```cmd
# Activate
venv\Scripts\activate.bat

# Deactivate when done
deactivate
```

### Verify Virtual Environment

```bash
# Should show venv Python, not system Python
which python3  # macOS/Linux
where python   # Windows

# Should be venv location like:
# ~/badger-projects/my-badge-app/venv/bin/python3
```

## Install Badger Development Tools

With virtual environment activated:

### Core Tools

```bash
# Install mpremote (recommended primary tool)
pip install mpremote

# Install ampy (alternative file management)
pip install adafruit-ampy

# Install rshell (interactive shell)
pip install rshell

# Install esptool (firmware flashing)
pip install esptool

# Verify installations
mpremote --version
ampy --version
rshell --version
esptool.py version
```

### Optional Development Tools

```bash
# Thonny IDE (beginner-friendly)
pip install thonny

# Code quality tools
pip install black      # Code formatter
pip install pylint     # Linter
pip install mypy       # Type checker

# Testing tools
pip install pytest     # Testing framework
pip install pytest-cov # Coverage reporting

# Documentation tools
pip install mkdocs     # Documentation generator
pip install sphinx     # Alternative documentation
```

### Save Dependencies

Create `requirements.txt` to track dependencies:

```bash
# Generate requirements.txt
pip freeze > requirements.txt
```

**Example requirements.txt:**

```
mpremote==1.20.0
adafruit-ampy==1.1.0
rshell==0.0.32
esptool==4.6.2
black==23.12.1
pylint==3.0.3
pytest==7.4.3
```

### Install from requirements.txt

```bash
# Install all dependencies at once
pip install -r requirements.txt

# Or upgrade existing
pip install -r requirements.txt --upgrade
```

## Configure Tools

### mpremote Configuration

Create alias for easier use:

**macOS/Linux (.bashrc or .zshrc):**

```bash
# Add to ~/.bashrc or ~/.zshrc
alias badge='mpremote connect /dev/tty.usbmodem*'

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Usage
badge ls
badge cp main.py :main.py
```

**Windows (PowerShell profile):**

```powershell
# Open profile
notepad $PROFILE

# Add alias
function badge { mpremote connect COM3 @args }

# Reload
. $PROFILE

# Usage
badge ls
```

### ampy Configuration

Set default port to avoid typing it each time:

**macOS/Linux:**

```bash
# Add to ~/.bashrc or ~/.zshrc
export AMPY_PORT=/dev/tty.usbmodem*

# Reload
source ~/.bashrc
```

**Windows:**

```powershell
# Add to PowerShell profile
$env:AMPY_PORT = "COM3"

# Or set permanently
[Environment]::SetEnvironmentVariable("AMPY_PORT", "COM3", "User")
```

## Verify Complete Setup

Run this verification script:

```bash
# verify_setup.sh (macOS/Linux)
#!/bin/bash

echo "Verifying Badger 2350 Development Setup"
echo "========================================"

# Check Python
if command -v python3 &> /dev/null; then
    echo "✓ Python: $(python3 --version)"
else
    echo "✗ Python not found"
    exit 1
fi

# Check pip
if command -v pip3 &> /dev/null; then
    echo "✓ pip: $(pip3 --version)"
else
    echo "✗ pip not found"
    exit 1
fi

# Check virtual environment
if [[ "$VIRTUAL_ENV" != "" ]]; then
    echo "✓ Virtual environment: active"
else
    echo "⚠ Virtual environment: not active"
fi

# Check tools
tools=(mpremote ampy rshell esptool.py)
for tool in "${tools[@]}"; do
    if command -v $tool &> /dev/null; then
        echo "✓ $tool: installed"
    else
        echo "✗ $tool: not installed"
    fi
done

echo "========================================"
echo "Setup verification complete!"
```

Make executable and run:

```bash
chmod +x verify_setup.sh
./verify_setup.sh
```

**Windows PowerShell version:**

```powershell
# verify_setup.ps1
Write-Host "Verifying Badger 2350 Development Setup"
Write-Host "========================================"

# Check Python
if (Get-Command python -ErrorAction SilentlyContinue) {
    $version = python --version
    Write-Host "✓ Python: $version"
} else {
    Write-Host "✗ Python not found"
    exit 1
}

# Check pip
if (Get-Command pip -ErrorAction SilentlyContinue) {
    Write-Host "✓ pip: installed"
} else {
    Write-Host "✗ pip not found"
    exit 1
}

# Check virtual environment
if ($env:VIRTUAL_ENV) {
    Write-Host "✓ Virtual environment: active"
} else {
    Write-Host "⚠ Virtual environment: not active"
}

# Check tools
$tools = @("mpremote", "ampy", "rshell", "esptool.py")
foreach ($tool in $tools) {
    if (Get-Command $tool -ErrorAction SilentlyContinue) {
        Write-Host "✓ $tool: installed"