windows: add shim modules, windows dev guide & setup script (issues kubernetes-client#2427 kubernetes-client#2428)

Author: PraveenMudalgeri

WINDOWS_DEVELOPMENT.md

@@ -0,0 +1,77 @@
+# Windows Development Guide
+
+This repository historically used Unix symbolic links inside the `kubernetes` package (e.g. `kubernetes/config` -> `kubernetes/base/config`). Windows clones without Developer Mode or elevated privileges could not create these links, breaking imports.
+
+## What Changed
+
+Shim Python modules replaced symlink placeholders (`config`, `dynamic`, `watch`, `stream`, `leaderelection`). They re-export from `kubernetes.base.*` so public APIs remain the same and no filesystem symlink is required.
+
+## Getting Started
+
+1. Ensure Python 3.9+ is installed and on PATH.
+2. (Optional) Create virtual environment:
+
+   ```powershell
+   py -3 -m venv .venv
+   .\.venv\Scripts\Activate.ps1
+   ```
+
+3. Install requirements:
+
+   ```powershell
+   pip install -r requirements.txt -r test-requirements.txt
+   ```
+
+4. Run a quick import smoke test:
+
+   ```powershell
+   python - <<'PY'
+   from kubernetes import config, watch, dynamic, stream, leaderelection
+   print('Imported packages OK')
+   PY
+   ```
+
+## Running Tests on Windows
+
+`tox` can run most tests; some network / streaming tests are flaky under Windows due to timing. Recommended:
+
+```powershell
+pip install tox
+tox -e py
+```
+
+If you see intermittent websocket or watch hangs, re-run that specific test module with pytest's `-k` to isolate.
+
+## Permission Semantics
+
+Windows has different file permission behavior than POSIX; tests expecting strict mode bits may fail. Adjust or skip such tests with `pytest.mark.skipif(sys.platform.startswith('win'), ...)` when encountered (none required yet after shims).
+
+## Streaming / WebSocket Notes
+
+If exec/port-forward tests hang:
+
+- Ensure firewall allows local loopback connections.
+- Set `PYTHONUNBUFFERED=1` to improve real-time logs.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| ------- | --- |
+| `ModuleNotFoundError` for subpackages | Ensure shim files exist and you installed the package in editable mode `pip install -e .` |
+| Watch stream stalls | Use smaller `timeout_seconds` and retry; Windows networking latency differs |
+| PermissionError deleting temp files | Close file handles; Windows locks open files |
+
+## Regenerating Client (Optional)
+
+Regeneration scripts in `scripts/` assume a Unix-like environment. Use WSL2 or a Linux container when running `update-client.sh`.
+
+## Contributing Windows Fixes
+
+1. Create branch
+2. Add / adjust tests using `sys.platform` guards
+3. Run `ruff` or `flake8` (if adopted) and `tox`
+4. Open PR referencing related issue (e.g. #2427 #2428)
+
+---
+
+Maintainers: Please keep this doc updated as additional Windows-specific adjustments are made.

kubernetes/config

@@ -1 +1,9 @@
-base/config
+"""Windows-friendly shim: exposes symbols from kubernetes.base.config.
+
+Previously this path used a symlink to base/config which is not portable on
+Windows (especially in workspaces lacking Developer Mode or proper
+permissions). Converting to a simple Python re-export preserves public API
+without requiring filesystem symlinks.
+"""
+
+from kubernetes.base.config import *  # noqa: F401,F403

kubernetes/dynamic

@@ -1 +1,6 @@
-base/dynamic
+"""Windows-friendly shim for kubernetes.base.dynamic.
+
+Replaces symlink with explicit import to maintain cross-platform behavior.
+"""
+
+from kubernetes.base.dynamic import *  # noqa: F401,F403

kubernetes/leaderelection

@@ -1 +1,3 @@
-base/leaderelection
+"""Windows-friendly shim for kubernetes.base.leaderelection."""
+
+from kubernetes.base.leaderelection import *  # noqa: F401,F403

kubernetes/stream

@@ -1 +1,3 @@
-base/stream
+"""Windows-friendly shim for kubernetes.base.stream."""
+
+from kubernetes.base.stream import *  # noqa: F401,F403

kubernetes/watch

@@ -1 +1,3 @@
-base/watch
+"""Windows-friendly shim for kubernetes.base.watch."""
+
+from kubernetes.base.watch import *  # noqa: F401,F403

scripts/windows/setup-windows-dev.ps1

@@ -0,0 +1,67 @@
+<#
+.SYNOPSIS
+Bootstrap Windows development environment for Kubernetes Python client.
+
+.DESCRIPTION
+Creates virtual environment (if missing), installs dependencies, and ensures
+shim modules (config/dynamic/watch/stream/leaderelection) contain re-export
+code replacing symlinks for Windows portability.
+
+#>
+param(
+    [string]$Python = "py",
+    [string]$Venv = ".venv"
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Write-Step($m){ Write-Host "[setup] $m" -ForegroundColor Cyan }
+
+Write-Step "Python version"
+& $Python -3 -c "import sys; print(sys.version)" | Write-Host
+
+if(!(Test-Path $Venv)){
+  Write-Step "Creating venv $Venv"
+  & $Python -3 -m venv $Venv
+}
+Write-Step "Activating venv"
+$activate = Join-Path $Venv 'Scripts/Activate.ps1'
+. $activate
+
+Write-Step "Upgrading pip"
+python -m pip install --upgrade pip > $null
+
+Write-Step "Installing requirements"
+if(Test-Path requirements.txt){ pip install -r requirements.txt }
+if(Test-Path test-requirements.txt){ pip install -r test-requirements.txt }
+
+$shimMap = @{ 
+  'kubernetes/config' = 'from kubernetes.base.config import *  # noqa: F401,F403';
+  'kubernetes/dynamic' = 'from kubernetes.base.dynamic import *  # noqa: F401,F403';
+  'kubernetes/watch' = 'from kubernetes.base.watch import *  # noqa: F401,F403';
+  'kubernetes/stream' = 'from kubernetes.base.stream import *  # noqa: F401,F403';
+  'kubernetes/leaderelection' = 'from kubernetes.base.leaderelection import *  # noqa: F401,F403'
+}
+
+foreach($path in $shimMap.Keys){
+  if(Test-Path $path){
+    $item = Get-Item $path
+    if($item.PSIsContainer){ continue }
+    $content = Get-Content $path -Raw
+    if($content -notmatch 'kubernetes.base'){
+      Write-Step "Updating shim $path"
+      """Windows shim auto-generated`n$($shimMap[$path])""" | Out-File -FilePath $path -Encoding UTF8
+    }
+  } else {
+    Write-Step "Creating shim file $path"
+    """Windows shim auto-generated`n$($shimMap[$path])""" | Out-File -FilePath $path -Encoding UTF8
+  }
+}
+
+Write-Step "Smoke import"
+python - <<'PY'
+from kubernetes import config, dynamic, watch, stream, leaderelection
+print('Shim import success')
+PY
+
+Write-Step "Done"