Add Windows Python 3.9 environment support (monsta_venv)

docs/_docs/quick-starts/quick-start-windows.md

@@ -16,7 +16,10 @@ parent: Quick Starts
 - Windows 10/11 with WSL2 enabled
 - Docker Desktop for Windows
 - Git for Windows
-- Python 3.6+ (for CueGUI)
+- **Python 3.9** (required for Windows client components - see note below)
+
+{: .important }
+> **Python 3.9 Requirement:** Windows client components (rqd, cuegui, cuesubmit) specifically require Python 3.9.x. This is due to binary wheel availability and compatibility with native dependencies like PySide2. See the [monsta_venv setup](#option-2-using-monsta_venv-recommended-for-python-39) for an easy way to configure the correct environment.
 
 ## Setup Steps
 
@@ -67,10 +70,34 @@ You should see all services in "Up" state.
 
 ### 6. Install Python dependencies
 
+There are two options for setting up Python dependencies on Windows:
+
+#### Option 1: Standard pip install
+
 ```bash
 pip install pycue cuegui
 ```
 
+#### Option 2: Using monsta_venv (Recommended for Python 3.9)
+
+The `monsta_venv` directory provides a preconfigured Python 3.9 virtual environment setup specifically for Windows:
+
+1. Open PowerShell as Administrator
+2. Navigate to the OpenCue repository:
+   ```powershell
+   cd OpenCue\monsta_venv
+   ```
+3. Run the setup script:
+   ```powershell
+   .\setup_windows_venv.ps1
+   ```
+4. Activate the environment:
+   ```powershell
+   .\activate.ps1
+   ```
+
+See the [monsta_venv README](../../../monsta_venv/README.md) for detailed instructions and troubleshooting.
+
 ### 7. Configure environment
 
 Set the Cuebot host:
@@ -100,6 +127,18 @@ cuegui
 
 ## Troubleshooting
 
+### Python 3.9 Issues
+
+**Python version mismatch:**
+Windows client components require Python 3.9.x specifically. If you encounter module import errors or PySide2 issues:
+1. Install Python 3.9 from [python.org](https://www.python.org/downloads/release/python-3913/)
+2. Use the `monsta_venv` setup: `.\monsta_venv\setup_windows_venv.ps1`
+
+**PySide2 installation fails:**
+```powershell
+pip install PySide2==5.15.2.1
+```
+
 ### Docker not starting
 - Ensure virtualization is enabled in BIOS
 - Check that WSL2 is properly installed
@@ -114,8 +153,15 @@ cuegui
 - Allocate more resources to Docker Desktop in Settings
 - Use WSL2 backend for better performance
 
+### PowerShell script execution blocked
+Run PowerShell as Administrator and execute:
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
 ## Next Steps
 
+- [monsta_venv README](../../../monsta_venv/README.md) - Detailed Windows Python 3.9 setup
 - [Installing CueSubmit](../getting-started/installing-cuesubmit.md)
 - [Submitting Jobs](../user-guides/submitting-jobs.md)
 - [Configuring RQD](../other-guides/customizing-rqd.md)

monsta_venv/README.md

@@ -0,0 +1,142 @@
+# monsta_venv - Windows Python 3.9 Virtual Environment Setup
+
+This directory provides Windows-specific Python 3.9 virtual environment setup for running OpenCue client components (rqd, cuegui).
+
+## Requirements
+
+- Windows 10/11
+- Python 3.9.x (required for Windows client components)
+- Administrator privileges (for initial setup)
+
+## Quick Setup
+
+### Option 1: Automated Setup (Recommended)
+
+1. Open PowerShell as Administrator
+2. Navigate to this directory:
+   ```powershell
+   cd path\to\OpenCue\monsta_venv
+   ```
+3. Run the setup script:
+   ```powershell
+   .\setup_windows_venv.ps1
+   ```
+
+### Option 2: Manual Setup
+
+1. Install Python 3.9:
+   - Download from [Python.org](https://www.python.org/downloads/release/python-3913/)
+   - During installation, check "Add Python to PATH"
+   - Select "Customize installation" and enable "pip"
+
+2. Create virtual environment:
+   ```powershell
+   cd path\to\OpenCue\monsta_venv
+   py -3.9 -m venv venv
+   ```
+
+3. Activate the environment:
+   ```powershell
+   .\venv\Scripts\Activate.ps1
+   ```
+
+4. Install dependencies:
+   ```powershell
+   pip install -r requirements.txt
+   ```
+
+## Activating the Environment
+
+### PowerShell
+```powershell
+.\monsta_venv\activate.ps1
+```
+
+### Command Prompt
+```cmd
+monsta_venv\activate.bat
+```
+
+## Running Client Components
+
+After activating the environment:
+
+### RQD (Render Queue Daemon)
+```powershell
+$env:CUEBOT_HOSTNAME = "your-cuebot-server"
+rqd -c ..\sandbox\rqd_windows.conf
+```
+
+### CueGUI
+```powershell
+$env:CUEBOT_HOSTS = "your-cuebot-server"
+cuegui
+```
+
+### CueSubmit
+```powershell
+$env:CUEBOT_HOSTS = "your-cuebot-server"
+cuesubmit
+```
+
+## Troubleshooting
+
+### Python 3.9 Not Found
+If Python 3.9 is not in your PATH, specify the full path:
+```powershell
+C:\Python39\python.exe -m venv venv
+```
+
+### PowerShell Execution Policy
+If scripts are blocked, run PowerShell as Administrator and execute:
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### Module Import Errors
+Ensure all dependencies are installed:
+```powershell
+pip install -r requirements.txt
+```
+
+### PySide2/Qt Issues
+For CueGUI Qt issues:
+```powershell
+pip uninstall PySide2
+pip install PySide2==5.15.2.1
+```
+
+### gRPC Connection Issues
+1. Verify CUEBOT_HOSTNAME is set correctly
+2. Check firewall allows port 8443 (gRPC) and 8444 (RQD)
+3. Test connectivity:
+   ```powershell
+   Test-NetConnection -ComputerName your-cuebot-server -Port 8443
+   ```
+
+## Directory Structure
+
+```
+monsta_venv/
+├── README.md              # This file
+├── requirements.txt       # Python dependencies
+├── setup_windows_venv.ps1 # Automated setup script
+├── activate.ps1           # PowerShell activation script
+├── activate.bat           # Command Prompt activation script
+└── venv/                  # Virtual environment (created during setup)
+```
+
+## Python Version Requirement
+
+**Important:** Windows client components specifically require Python 3.9.x due to:
+- Binary wheel availability for PySide2 on Windows
+- Compatibility with psutil and other native dependencies
+- Tested and verified operation with OpenCue client tools
+
+Python versions 3.10+ may have issues with some dependencies on Windows.
+
+## See Also
+
+- [Quick Start for Windows](../docs/_docs/quick-starts/quick-start-windows.md)
+- [Hybrid RQD Setup](../docs/_docs/developer-guide/hybrid-rqd-setup.md)
+- [OpenCue Documentation](https://www.opencue.io/docs/)

monsta_venv/activate.bat

@@ -0,0 +1,22 @@
+@echo off
+REM OpenCue Windows Virtual Environment Activation Script
+
+set SCRIPT_DIR=%~dp0
+set VENV_ACTIVATE=%SCRIPT_DIR%venv\Scripts\activate.bat
+
+if exist "%VENV_ACTIVATE%" (
+    call "%VENV_ACTIVATE%"
+    echo OpenCue virtual environment activated!
+    echo.
+    echo Available commands:
+    echo   cuegui    - Launch CueGUI
+    echo   cuesubmit - Launch CueSubmit
+    echo   rqd       - Start RQD daemon
+    echo   cueadmin  - Command-line admin tool
+    echo.
+    echo Remember to set CUEBOT_HOSTS environment variable:
+    echo   set CUEBOT_HOSTS=your-cuebot-server
+) else (
+    echo ERROR: Virtual environment not found!
+    echo Run setup_windows_venv.ps1 first.
+)

monsta_venv/activate.ps1

@@ -0,0 +1,20 @@
+# OpenCue Windows Virtual Environment Activation Script
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$VenvActivate = Join-Path $ScriptDir "venv\Scripts\Activate.ps1"
+
+if (Test-Path $VenvActivate) {
+    & $VenvActivate
+    Write-Host "OpenCue virtual environment activated!" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "Available commands:" -ForegroundColor Cyan
+    Write-Host "  cuegui    - Launch CueGUI" -ForegroundColor White
+    Write-Host "  cuesubmit - Launch CueSubmit" -ForegroundColor White
+    Write-Host "  rqd       - Start RQD daemon" -ForegroundColor White
+    Write-Host "  cueadmin  - Command-line admin tool" -ForegroundColor White
+    Write-Host ""
+    Write-Host "Remember to set CUEBOT_HOSTS environment variable:" -ForegroundColor Yellow
+    Write-Host "  `$env:CUEBOT_HOSTS = `"your-cuebot-server`"" -ForegroundColor White
+} else {
+    Write-Host "ERROR: Virtual environment not found!" -ForegroundColor Red
+    Write-Host "Run setup_windows_venv.ps1 first." -ForegroundColor Yellow
+}

monsta_venv/requirements.txt

@@ -0,0 +1,30 @@
+# OpenCue Windows Client Requirements
+# Python 3.9.x required for Windows client components
+
+# Core dependencies
+grpcio>=1.48.0
+grpcio-tools>=1.48.0
+protobuf>=3.19.0,<4.0.0
+
+# OpenCue Python packages (installed from local source)
+# These will be installed by setup script from the repository root
+# pycue
+# pyoutline  
+# rqd
+# cuegui
+# cuesubmit
+# cueadmin
+
+# GUI dependencies (for CueGUI)
+PySide2==5.15.2.1
+
+# RQD dependencies
+psutil>=5.8.0
+future>=0.18.3
+
+# CueNIMBY dependencies
+pynput>=1.7.6
+
+# Utility dependencies
+PyYAML>=5.4.0
+six>=1.16.0