# Python Baseline Standard

**Date:** 2026-01-25
**Status:** Official Standard

## Baseline Requirement

**Python 3.11.x** is the official baseline for Styrene TUI development and deployment.

### Version Matrix

| Environment | Current | Should Be | Status |
|-------------|---------|-----------|--------|
| **Project Spec** | `>=3.11` | `>=3.11, <3.13` | ⚠️ Update |
| **Q502 Production** | 3.11.11 | 3.11.x | ✅ Correct |
| **MacBook Dev** | 3.14.2 | 3.11.x | ❌ **Wrong** |
| **CI/CD** | Not set | 3.11.x | ⚠️ TBD |

## Why Python 3.11?

1. **RNS Compatibility**: RNS (Reticulum Network Stack) is tested primarily against Python 3.10-3.12
2. **Stability**: Python 3.11 is mature (released Oct 2022)
3. **NixOS Support**: Q502 runs NixOS which has stable 3.11 packages
4. **Project Classifiers**: `pyproject.toml` explicitly lists 3.11 and 3.12 only

## Python 3.14 Issues

Python 3.14 (released Oct 2024) is **too new** and causes inconsistencies:

### Current Issue: TCPClientInterface Loading

| Python Version | RNS Config Parsing | TCPClientInterface | Hub Connection |
|----------------|-------------------|-------------------|----------------|
| 3.11.11 (Q502) | ✅ Works | ❌ **Fails silently** | ❌ No connection |
| 3.14.2 (MacBook) | ✅ Works | ✅ Loads | ✅ Connected |

**Hypothesis:** Python 3.14 may have:
- Fixed a bug in `configparser` that RNS depends on
- Changed socket/network behavior that makes TCP initialization work
- Different module loading behavior that affects RNS interface initialization

**This inconsistency is dangerous** - code that works in dev (3.14) fails in production (3.11).

## Standard Enforcement

### pyproject.toml Updates

**Current:**
```toml
requires-python = ">=3.11"
```

**Should be:**
```toml
requires-python = ">=3.11, <3.13"
```

**Rationale:** Explicitly cap at 3.12.x to prevent 3.13/3.14 from being used until tested.

### Development Setup

**All developers MUST use Python 3.11.x:**

```bash
# Check Python version
python --version
# Should output: Python 3.11.x

# Create venv with 3.11
python3.11 -m venv .venv
source .venv/bin/activate

# Verify venv Python
python --version
# Should output: Python 3.11.x

# Install dependencies
pip install -e ".[dev]"
```

### CI/CD Configuration

When CI is set up, pin to Python 3.11:

```yaml
# .github/workflows/test.yml
jobs:
  test:
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]  # NOT 3.13 or 3.14
```

### Deployment Environments

All deployment targets MUST run Python 3.11.x:

| Target | Python | Verification |
|--------|--------|--------------|
| Q502 | 3.11.11 | ✅ Verified |
| Future edge devices | 3.11.x | Required |
| Container images | 3.11.x | TBD |

## Migration Path

### Immediate (Today)

1. **Recreate MacBook venv with Python 3.11**
   ```bash
   cd ~/workspace/vanderlyn/styrene-lab/styrene-tui
   rm -rf .venv
   python3.11 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   ```

2. **Test TCPClientInterface with 3.11**
   - If it works: Python version is NOT the issue
   - If it fails: We've identified the problem

3. **Update pyproject.toml**
   ```toml
   requires-python = ">=3.11, <3.13"
   ```

### Testing Protocol

After aligning to Python 3.11:

1. **MacBook:** Test hub connection with 3.11
2. **Q502:** Retest TCPClientInterface loading
3. **Compare:** If both fail, issue is elsewhere; if both work, issue was version

### Future Python Upgrades

Before upgrading to Python 3.13+:

- [ ] Verify RNS supports the new version
- [ ] Test all RNS interfaces (TCP, UDP, Serial, Auto)
- [ ] Test on both Linux and macOS
- [ ] Update pyproject.toml version cap
- [ ] Update CI matrix
- [ ] Document any breaking changes

## Python Version Check Script

Add to project root:

```python
#!/usr/bin/env python3
"""Verify Python version meets baseline requirement."""
import sys

REQUIRED_MAJOR = 3
REQUIRED_MINOR_MIN = 11
REQUIRED_MINOR_MAX = 12

version = sys.version_info

if version.major != REQUIRED_MAJOR:
    print(f"❌ Python {REQUIRED_MAJOR}.x required, found {version.major}.{version.minor}")
    sys.exit(1)

if version.minor < REQUIRED_MINOR_MIN or version.minor > REQUIRED_MINOR_MAX:
    print(f"❌ Python 3.{REQUIRED_MINOR_MIN}-3.{REQUIRED_MINOR_MAX} required, found {version.major}.{version.minor}")
    sys.exit(1)

print(f"✅ Python {version.major}.{version.minor}.{version.micro} meets baseline requirement")
```

Usage:
```bash
python scripts/check_python_version.py
```

## RNS Version Compatibility

| RNS Version | Python 3.10 | Python 3.11 | Python 3.12 | Python 3.13 | Python 3.14 |
|-------------|-------------|-------------|-------------|-------------|-------------|
| 1.0.x | ✅ | ✅ | ✅ | ⚠️ Untested | ⚠️ Untested |
| 1.1.x | ✅ | ✅ | ✅ | ⚠️ Untested | ⚠️ Untested |

**Current:** RNS 1.1.3 on both machines

## References

- Python 3.11 Release: https://docs.python.org/3.11/whatsnew/3.11.html
- Python 3.14 Release: https://docs.python.org/3.14/whatsnew/3.14.html (Oct 2024)
- RNS Documentation: https://reticulum.network/
- Project pyproject.toml: `requires-python = ">=3.11"`

## Decision Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-01-25 | Set Python 3.11 as baseline | Project spec, RNS compatibility, production stability |
| 2026-01-25 | Cap at <3.13 until tested | Prevent 3.14 inconsistencies |
| TBD | Evaluate 3.13 upgrade | After RNS community testing |

## Verification Checklist

Before deploying to any environment:

- [ ] `python --version` shows 3.11.x or 3.12.x
- [ ] RNS 1.1.x installed and working
- [ ] TCPClientInterface loads correctly
- [ ] Hub connection succeeds
- [ ] LXMF initializes successfully
- [ ] All tests pass
