feat!: Migrate imports from glean to glean.api_client

Add automated tool to transform glean package structure from flat
to namespace package layout with Speakeasy regeneration detection.
Includes comprehensive documentation and dry-run capabilities.

Author: rwjblue-glean

.github/workflows/patch-speakeasy-pr.yml

@@ -1,10 +1,8 @@
-name: Patch Speakeasy PR
+name: Restructure Speakeasy PR
 
 on:
   pull_request:
     types: [opened, synchronize]
-    paths:
-      - 'src/glean/__init__.py'
   workflow_dispatch:
 
 jobs:
@@ -21,17 +19,19 @@ jobs:
           ref: ${{ github.head_ref || github.ref_name }}
           fetch-depth: 0
 
-      - name: Patch glean/__init__.py with extend_path
-        id: patch
+      - name: Restructure glean package to namespace structure
         run: |
-          OUTPUT=$GITHUB_OUTPUT .github/scripts/patch_extend_path.sh
+          python scripts/restructure_to_namespace.py
 
-      - name: Commit and push if file changed
-        if: steps.patch.outputs.patched == 'true'
+      - name: Commit and push if files changed
         run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --global user.name "github-actions[bot]"
+            git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
-          git add src/glean/__init__.py
-          git commit -m "ci: ensure extend_path lines in glean/__init__.py" || echo "No changes to commit"
-          git push origin HEAD:${{ github.head_ref || github.ref_name }}
+            git add .
+            git commit -m "ci: restructure glean package to namespace structure"
+            git push origin HEAD:${{ github.head_ref || github.ref_name }}
+          else
+            echo "No changes detected"
+          fi

scripts/README.md

@@ -0,0 +1,126 @@
+# Restructuring Script
+
+This directory contains a script to restructure the glean package from:
+
+```
+src/glean/          # All implementation files
+```
+
+To:
+
+```
+src/glean/          # Implicit namespace package (no __init__.py)
+src/glean/api_client/   # All implementation files moved here
+```
+
+## Usage
+
+### Analyze what would change (recommended first step)
+
+```bash
+python scripts/restructure_to_namespace.py --dry-run
+```
+
+This shows you:
+
+- Which files would be moved
+- Which import statements would be updated
+- Current state of the transformation
+
+### Perform the restructuring
+
+```bash
+python scripts/restructure_to_namespace.py
+```
+
+This script:
+
+- **Detects Speakeasy regeneration** and automatically handles it
+- Creates a backup and moves all files
+- Uses implicit namespace packages (no `__init__.py` needed)
+- Can be run multiple times safely
+- Updates all import statements throughout the codebase
+
+## Smart Speakeasy Integration
+
+The script automatically detects when Speakeasy has regenerated files:
+
+1. **First run**: Moves everything to `api_client/`
+2. **After Speakeasy regeneration**: Detects new files in `src/glean/`, removes old `api_client/`, and re-runs the transformation
+3. **Subsequent runs**: Detects already-transformed structure and skips
+
+This means you can safely run the script as part of your build process!
+
+## Examples
+
+```bash
+# First, see what would be changed
+python scripts/restructure_to_namespace.py --dry-run
+
+# If it looks good, perform the restructuring
+python scripts/restructure_to_namespace.py
+
+# Safe to run multiple times - it will detect and handle various states
+python scripts/restructure_to_namespace.py  # Skips if already done
+python scripts/restructure_to_namespace.py  # Auto-detects Speakeasy regeneration
+```
+
+## What the restructuring does
+
+1. **Creates a backup** of the current `src/glean` directory
+2. **Moves all files** from `src/glean/` to `src/glean/api_client/`
+3. **Creates an implicit namespace package** (no `__init__.py` - Python 3.3+ feature)
+4. **Updates all import statements** in tests, examples, and internal files
+5. **Handles Speakeasy regeneration** automatically
+
+## After restructuring
+
+Users will need to update their imports:
+
+### Before
+
+```python
+from glean import Glean, models, errors
+from glean.utils import parse_datetime
+```
+
+### After
+
+```python
+from glean.api_client import Glean, models, errors
+from glean.api_client.utils import parse_datetime
+
+# Or use an alias for convenience:
+import glean.api_client as glean
+client = glean.Glean(...)
+```
+
+## Workflow Integration
+
+You can integrate this into your build process:
+
+```bash
+# In your build script or CI
+speakeasy generate  # Regenerates files to src/glean/
+python scripts/restructure_to_namespace.py  # Automatically detects and re-transforms
+```
+
+## Recovery
+
+If something goes wrong, the script provides the path to the backup directory:
+
+```bash
+rm -rf src/glean
+cp -r /path/to/backup/glean src/glean
+```
+
+## Testing after restructuring
+
+```bash
+# Run tests
+python -m pytest
+
+# Try importing
+python -c "from glean.api_client import Glean; print('Success!')"
+```
+