superset-showtime 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

{superset_showtime-0.1.0.dist-info → superset_showtime-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superset-showtime
-Version: 0.1.0
+Version: 0.2.2
 Summary: 🎪 Apache Superset ephemeral environment management with circus tent emoji state tracking
 Project-URL: Homepage, https://github.com/apache/superset-showtime
 Project-URL: Documentation, https://superset-showtime.readthedocs.io/
@@ -72,22 +72,34 @@ Description-Content-Type: text/markdown
 
 ## 🎯 What is Showtime?
 
-Superset Showtime replaces the complex GitHub Actions scripts for ephemeral environments with a simple, powerful CLI tool that uses **circus tent emoji labels** for state management.
+Superset Showtime is a CLI tool designed primarily for **GitHub Actions** to manage Apache Superset ephemeral environments. It uses **circus tent emoji labels** as a visual state management system and depends on Superset's existing build infrastructure.
 
-### The Problem We Solve
+## 🚀 Quick Start for Superset Contributors
+
+**Create an ephemeral environment:**
+1. Go to your PR in GitHub
+2. Add label: `🎪 ⚡ showtime-trigger-start`
+3. Watch the magic happen - labels will update automatically
+4. When you see `🎪 🚦 {sha} running`, your environment is ready!
+5. Get URL from `🎪 🌐 {sha} {ip}` → `http://{ip}:8080`
+6. **Every new commit automatically deploys a fresh environment** (zero-downtime)
+
+**To test a specific commit without auto-updates:**
+- Add label: `🎪 🧊 showtime-freeze` (prevents auto-sync on new commits)
 
-**Current Superset ephemeral environment issues:**
-- 🚨 **Stale environments** - New commits don't update existing environments
-- 💸 **Resource waste** - Multiple environments per PR, no automatic cleanup
-- 🔧 **Hard to maintain** - Complex GitHub Actions logic scattered across workflows
-- 👀 **Poor visibility** - Hard to see what environments exist and their status
+**Clean up when done:**
+```bash
+# Add this label:
+🎪 🛑 showtime-trigger-stop
+# All circus labels disappear, AWS resources cleaned up
+```
 
-### The Showtime Solution
+## 🎪 How It Works
 
 **🎪 GitHub labels become a visual state machine:**
 ```bash
 # User adds trigger label in GitHub UI:
-🎪 trigger-start
+🎪 ⚡ showtime-trigger-start
 
 # System responds with state labels:
 🎪 abc123f 🚦 building      # Environment abc123f is building
@@ -101,64 +113,40 @@ Superset Showtime replaces the complex GitHub Actions scripts for ephemeral envi
 🎪 abc123f 🌐 52-1-2-3      # Available at http://52.1.2.3:8080
 ```
 
-## 🚀 Quick Start for Superset Contributors
-
-### 1. As a Contributor (Using GitHub Labels)
+## 📊 For Maintainers (CLI Operations)
 
-**Create an ephemeral environment:**
-1. Go to your PR in GitHub
-2. Add label: `🎪 trigger-start`
-3. Watch the magic happen - labels will update automatically
-4. When you see `🎪 🚦 {sha} running`, your environment is ready!
-5. Get URL from `🎪 🌐 {sha} {ip}` → `http://{ip}:8080`
+> **Note**: CLI is mainly for debugging or developing Showtime itself. Primary interface is GitHub labels above.
 
-**Configure your environment:**
-```bash
-# Add these labels to enable Superset feature flags:
-🎪 conf-enable-ALERTS              # Enable alerts feature
-🎪 conf-enable-DASHBOARD_RBAC      # Enable dashboard RBAC
-🎪 conf-disable-SSH_TUNNELING      # Disable SSH tunneling
-```
-
-**Clean up when done:**
-```bash
-# Add this label:
-🎪 trigger-stop
-# All circus labels disappear, AWS resources cleaned up
-```
-
-### 2. As a Maintainer (Using CLI)
-
-**Install the CLI:**
+**Install CLI for debugging:**
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_token
 ```
 
-**Monitor all environments:**
+**Monitor and debug:**
 ```bash
 showtime list                    # See all active environments
-showtime status 1234            # Check specific PR environment
-showtime labels                 # Learn the complete label system
+showtime status 1234            # Debug specific environment
+showtime labels                 # Complete label reference
 ```
 
-**Test and debug:**
+**Testing/development:**
 ```bash
-showtime start 1234 --dry-run-aws      # Test environment creation
+showtime start 1234 --dry-run-aws      # Test without AWS costs
 showtime test-lifecycle 1234           # Full workflow simulation
 ```
 
+> **Dependency**: This CLI coordinates with Superset's existing GitHub Actions build infrastructure. It orchestrates environments but relies on Superset's build workflows for container creation.
+
 ## 🎪 Complete Label Reference
 
 ### 🎯 Trigger Labels (Add These to Your PR)
 
 | Label | Action | Result |
 |-------|---------|---------|
-| `🎪 trigger-start` | Create environment | Builds and deploys ephemeral environment |
-| `🎪 trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |
-| `🎪 trigger-sync` | Update to latest commit | Zero-downtime rolling update |
-| `🎪 conf-enable-ALERTS` | Enable feature flag | Sets `SUPERSET_FEATURE_ALERTS=True` |
-| `🎪 conf-disable-DASHBOARD_RBAC` | Disable feature flag | Sets `SUPERSET_FEATURE_DASHBOARD_RBAC=False` |
+| `🎪 ⚡ showtime-trigger-start` | Create environment | Builds and deploys ephemeral environment with blue-green deployment |
+| `🎪 🛑 showtime-trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |
+| `🎪 🧊 showtime-freeze` | Freeze environment | Prevents auto-sync on new commits (for testing specific SHAs) |
 
 ### 📊 State Labels (Automatically Managed)
 
@@ -168,16 +156,27 @@ showtime test-lifecycle 1234           # Full workflow simulation
 | `🎪 🎯 {sha}` | Active environment pointer | `🎪 🎯 abc123f` |
 | `🎪 🏗️ {sha}` | Building environment pointer | `🎪 🏗️ def456a` |
 | `🎪 {sha} 📅 {timestamp}` | Creation time | `🎪 abc123f 📅 2024-01-15T14-30` |
-| `🎪 {sha} 🌐 {ip-with-dashes}` | Environment IP | `🎪 abc123f 🌐 52-1-2-3` |
+| `🎪 {sha} 🌐 {ip:port}` | Environment URL | `🎪 abc123f 🌐 52.1.2.3:8080` |
 | `🎪 {sha} ⌛ {ttl}` | Time-to-live policy | `🎪 abc123f ⌛ 24h` |
 | `🎪 {sha} 🤡 {username}` | Who requested | `🎪 abc123f 🤡 maxime` |
-| `🎪 {sha} ⚙️ {config}` | Feature flags enabled | `🎪 abc123f ⚙️ alerts,debug` |
+
+## 🔧 Testing Configuration Changes
+
+**Approach**: Modify configuration directly in your PR code, then trigger environment.
+
+**Workflow**:
+1. Modify `superset_config.py` with your changes
+2. Push commit → Creates new SHA (e.g., `def456a`)
+3. Add `🎪 ⚡ showtime-trigger-start` → Deploys with your config
+4. Test environment reflects your exact code changes
+
+This approach creates traceable, reviewable changes that are part of your git history.
 
 ## 🔄 Complete Workflows
 
 ### Creating Your First Environment
 
-1. **Add trigger label** in GitHub UI: `🎪 trigger-start`
+1. **Add trigger label** in GitHub UI: `🎪 ⚡ showtime-trigger-start`
 2. **Watch state labels appear:**
    ```
    🎪 abc123f 🚦 building      ← Environment is building
@@ -187,17 +186,15 @@ showtime test-lifecycle 1234           # Full workflow simulation
 3. **Wait for completion:**
    ```
    🎪 abc123f 🚦 running       ← Now ready!
-   🎪 abc123f 🌐 52-1-2-3      ← Visit http://52.1.2.3:8080
+   🎪 abc123f 🌐 52.1.2.3:8080  ← Visit http://52.1.2.3:8080
    ```
 
-### Enabling Feature Flags
+### Testing Specific Commits
 
-1. **Add config label:** `🎪 conf-enable-ALERTS`
-2. **Watch config update:**
-   ```
-   🎪 abc123f ⚙️ standard     ← Before
-   🎪 abc123f ⚙️ alerts       ← After (feature enabled!)
-   ```
+1. **Add freeze label:** `🎪 🧊 showtime-freeze`
+2. **Result:** Environment won't auto-update on new commits
+3. **Use case:** Test specific SHA while continuing development
+4. **Override:** Add `🎪 ⚡ showtime-trigger-start` to force update despite freeze
 
 ### Rolling Updates (Automatic!)
 
@@ -230,18 +227,18 @@ You'll see:
 - **❌ External contributors** cannot trigger environments (no write access to add labels)
 - **🔒 Secure by design** - only trusted users can create expensive AWS resources
 
-### How GitHub Actions Work
+### GitHub Actions Integration
 
-The new system replaces complex GHA scripts with simple ones:
+Showtime is designed to be called by Superset's GitHub Actions workflows:
 
 ```yaml
-# .github/workflows/circus.yml (replaces current ephemeral-env.yml)
+# .github/workflows/showtime.yml - Integrates with Superset's existing build workflows
 on:
   pull_request_target:
     types: [labeled, unlabeled, synchronize]
 
 jobs:
-  circus-handler:
+  showtime-handler:
     if: contains(github.event.label.name, '🎪')
     steps:
       - name: Install Showtime from PyPI
@@ -251,66 +248,70 @@ jobs:
         run: python -m showtime handle-trigger ${{ github.event.pull_request.number }}
 ```
 
-**Security benefits:**
-- **Always runs trusted code** (from PyPI, not PR code)
-- **Simple workflow logic** (just install CLI and run)
-- **Same permission model** as current system
+**Integration approach:**
+- **Coordinates with Superset builds** - Uses existing container build workflows
+- **Runs trusted code** (from PyPI, not PR code)
+- **Simple orchestration logic** (install CLI and run commands)
+- **Leverages existing infrastructure** - Same AWS resources and permissions
 
 ## 🛠️ Installation & Setup
 
 ### For Contributors (GitHub Labels Only)
-No installation needed! Just use the GitHub label system.
+No installation needed! Just use GitHub labels to trigger environments.
 
-### For Maintainers (CLI Access)
+### For Maintainers (Manual CLI Operations)
 
-**Install CLI:**
+**Install CLI for debugging/testing:**
 ```bash
 pip install superset-showtime
 export GITHUB_TOKEN=your_personal_access_token
 ```
 
-**Test CLI:**
+**Manual operations:**
 ```bash
-showtime list                    # See all active environments
-showtime status 1234            # Check specific environment
-showtime labels                 # Learn complete label system
+showtime list                    # Monitor all active environments
+showtime status 1234            # Debug specific environment
+showtime labels                 # Reference complete label system
 ```
 
-### For Repository Setup (One-Time)
+### For Repository Integration (GitHub Actions)
 
 **1. Install GitHub workflows:**
-Copy `.github/workflows/circus.yml` and `.github/workflows/circus-cleanup.yml` to your Superset repo.
+Copy `workflows-reference/showtime-trigger.yml` and `workflows-reference/showtime-cleanup.yml` to Superset's `.github/workflows/`.
+
+**2. Configure secrets (already exist in Superset):**
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `GITHUB_TOKEN`
 
-**2. Add repository secrets:**
-- `AWS_ACCESS_KEY_ID` (already exists)
-- `AWS_SECRET_ACCESS_KEY` (already exists)
-- `GITHUB_TOKEN` (already exists)
+**3. Dependencies:**
+Showtime coordinates with Superset's existing build infrastructure - no additional setup needed.
 
-**3. Replace old workflows:**
-Remove or disable the current `ephemeral-env.yml` and `ephemeral-env-pr-close.yml`.
+## 📊 CLI Reference (For Development/Debugging)
 
-## 📊 CLI Commands Reference
+> **Primary Interface**: Use GitHub labels in PR interface. CLI is mainly for maintainers debugging or developing Showtime itself.
 
-### Core Commands
+### Debugging Commands
 ```bash
-showtime start 1234             # Create environment (with dry-run options)
-showtime stop 1234              # Delete environment
-showtime status 1234            # Show environment status
-showtime list                   # List all environments across org
-showtime labels                 # Complete label reference guide
+showtime list                         # Monitor all environments
+showtime status 1234                  # Debug specific environment
+showtime labels                       # Complete label reference
+showtime test-lifecycle 1234          # Full workflow simulation
 ```
 
-### Testing & Development
+### Manual Operations (Advanced)
 ```bash
-showtime start 1234 --dry-run-aws          # Mock AWS, real GitHub labels
-showtime test-lifecycle 1234 --real-github # Full workflow simulation
-showtime handle-trigger 1234 --dry-run-aws # Simulate GitHub Actions
+showtime start 1234                    # Manually create environment
+showtime start 1234 --sha abc123f     # Create environment (specific SHA)
+showtime stop 1234                    # Manually delete environment
+showtime sync 1234                    # Force sync to desired state
+showtime cleanup --respect-ttl        # Manual cleanup
 ```
 
-### Advanced Operations
+### GitHub Actions Commands
 ```bash
-showtime cleanup --older-than 48h          # Clean up old environments
-showtime list --status running --user maxime  # Filter environments
+showtime handle-trigger 1234          # Process trigger labels (called by GHA)
+showtime cleanup --older-than 48h     # Scheduled cleanup (called by GHA)
 ```
 
 ## 🎪 Benefits for Superset
@@ -319,7 +320,7 @@ showtime list --status running --user maxime  # Filter environments
 - **🎯 Simple workflow** - Just add/remove GitHub labels
 - **👀 Visual feedback** - See environment status in PR labels
 - **⚡ Automatic updates** - New commits update environments automatically
-- **🔧 Live configuration** - Enable/disable feature flags without rebuilding
+- **🔧 Configuration testing** - Test config changes through code commits
 
 ### For Maintainers
 - **📊 Complete visibility** - `showtime list` shows all environments

superset_showtime-0.2.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+showtime/__init__.py,sha256=7gr2XH2j64TZrVs2xN0IPQPim10DF_fa9SncnotBqUI,420
+showtime/__main__.py,sha256=EVaDaTX69yIhCzChg99vqvFSCN4ELstEt7Mpb9FMZX8,109
+showtime/cli.py,sha256=oPjTUHYo2N1VLR68manw8OjwVOVQs-C18yZL2Pi-fM0,60751
+showtime/commands/__init__.py,sha256=M2wn5hYgwNCryMjLT79ncobvK884r-xk3znkCmINN_0,28
+showtime/commands/start.py,sha256=DPGbgvGPh7I60LK_VioDljUhdmhNFVjEy6BchFv1lCo,1026
+showtime/core/__init__.py,sha256=54hbdFNGrzuNMBdraezfjT8Zi6g221pKlJ9mREnKwCw,34
+showtime/core/aws.py,sha256=H-m_E0WFqxJ7s5GCaIsFpemYew9CoAT3XSF8WAc9ncc,32483
+showtime/core/circus.py,sha256=c7eKHZ4CzB03IN2pEuuqcDT_mp_RLqPHl-68pzPbJi8,8770
+showtime/core/emojis.py,sha256=MHEDuPIdfNiop4zbNLuviz3eY05QiftYSHHCVbkfKhw,2129
+showtime/core/github.py,sha256=HWhM8_Yq4P-AHq0FV3UfrfQHUHXxkhn74vvc_9RguKA,9822
+showtime/core/label_colors.py,sha256=efhbFnz_3nqEnEqmgyF6_hZbxtCu_fmb68BIIUpSsnk,3895
+showtime/data/ecs-task-definition.json,sha256=GcEbmmGGav0Sl9ksrrQ4acU-Q2utt2KE9IkFep7Bm0M,1856
+superset_showtime-0.2.2.dist-info/METADATA,sha256=9Y9uVAoeb7bA1varsduAOghIogVPnRDV0kYVY8wgao0,14635
+superset_showtime-0.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+superset_showtime-0.2.2.dist-info/entry_points.txt,sha256=rDW7oZ57mqyBUS4N_3_R7bZNGVHB-104jwmY-hHC_ck,85
+superset_showtime-0.2.2.dist-info/RECORD,,

showtime/core/config.py

@@ -1,152 +0,0 @@
-"""
-🎪 Showtime configuration management
-
-Handles configuration for GitHub API, AWS credentials, and showtime settings.
-"""
-
-import os
-from dataclasses import asdict, dataclass
-from pathlib import Path
-from typing import Optional
-
-import yaml
-from rich.console import Console
-from rich.prompt import Prompt
-
-console = Console()
-
-
-@dataclass
-class ShowtimeConfig:
-    """Showtime configuration settings"""
-
-    # GitHub settings
-    github_token: str
-    github_org: str
-    github_repo: str
-
-    # AWS settings
-    aws_profile: str = "default"
-    aws_region: str = "us-west-2"
-
-    # Circus settings
-    default_ttl: str = "24h"
-    default_size: str = "standard"
-
-    # ECS settings
-    ecs_cluster: str = "superset-ci"
-    ecs_task_family: str = "superset-ci"
-    ecr_repository: str = "superset-ci"
-
-    @property
-    def config_path(self) -> Path:
-        """Path to configuration file"""
-        config_dir = Path.home() / ".showtime"
-        config_dir.mkdir(exist_ok=True)
-        return config_dir / "config.yml"
-
-    @classmethod
-    def get_config_path(cls) -> Path:
-        """Get path to configuration file"""
-        config_dir = Path.home() / ".showtime"
-        config_dir.mkdir(exist_ok=True)
-        return config_dir / "config.yml"
-
-    @classmethod
-    def load(cls) -> "ShowtimeConfig":
-        """Load configuration from file"""
-        config_path = cls.get_config_path()
-
-        if not config_path.exists():
-            raise FileNotFoundError(
-                f"Configuration file not found at {config_path}. "
-                f"Run 'showtime init' to create it."
-            )
-
-        with open(config_path) as f:
-            data = yaml.safe_load(f)
-
-        return cls(**data)
-
-    def save(self) -> None:
-        """Save configuration to file"""
-        with open(self.config_path, "w") as f:
-            yaml.safe_dump(asdict(self), f, default_flow_style=False)
-
-    @classmethod
-    def create_interactive(
-        cls,
-        github_token: Optional[str] = None,
-        aws_profile: Optional[str] = None,
-        region: Optional[str] = None,
-    ) -> "ShowtimeConfig":
-        """Create configuration interactively"""
-
-        console.print("🎪 [bold blue]Welcome to Showtime! Let's set up your circus...[/bold blue]")
-        console.print()
-
-        # GitHub configuration
-        if not github_token:
-            github_token = Prompt.ask(
-                "GitHub personal access token", default=os.getenv("GITHUB_TOKEN", ""), password=True
-            )
-
-        github_org = Prompt.ask("GitHub organization", default="apache")
-
-        github_repo = Prompt.ask("GitHub repository", default="superset")
-
-        # AWS configuration
-        if not aws_profile:
-            aws_profile = Prompt.ask("AWS profile", default="default")
-
-        if not region:
-            region = Prompt.ask("AWS region", default="us-west-2")
-
-        # Circus settings
-        default_ttl = Prompt.ask(
-            "Default environment TTL",
-            default="24h",
-            choices=["24h", "48h", "1w", "close", "manual"],
-        )
-
-        default_size = Prompt.ask(
-            "Default environment size", default="standard", choices=["standard", "large"]
-        )
-
-        # ECS settings (with smart defaults)
-        ecs_cluster = Prompt.ask("ECS cluster name", default="superset-ci")
-
-        console.print()
-        console.print("🎪 [bold green]Configuration complete![/bold green]")
-
-        return cls(
-            github_token=github_token,
-            github_org=github_org,
-            github_repo=github_repo,
-            aws_profile=aws_profile,
-            aws_region=region,
-            default_ttl=default_ttl,
-            default_size=default_size,
-            ecs_cluster=ecs_cluster,
-        )
-
-    def validate(self) -> bool:
-        """Validate configuration settings"""
-        errors = []
-
-        if not self.github_token:
-            errors.append("GitHub token is required")
-
-        if not self.github_org:
-            errors.append("GitHub organization is required")
-
-        if not self.github_repo:
-            errors.append("GitHub repository is required")
-
-        if errors:
-            console.print("🎪 [bold red]Configuration errors:[/bold red]")
-            for error in errors:
-                console.print(f"  • {error}")
-            return False
-
-        return True

superset_showtime-0.1.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-showtime/__init__.py,sha256=vyBFCZ0eKSRhMQAI7O2Qkwiv7-eAkiSjkg6RHIBIU1U,482
-showtime/__main__.py,sha256=EVaDaTX69yIhCzChg99vqvFSCN4ELstEt7Mpb9FMZX8,109
-showtime/cli.py,sha256=CXV3HNkwijdUla92txSy6XVV-M925PxVK6jIfMzIsQc,54440
-showtime/commands/__init__.py,sha256=M2wn5hYgwNCryMjLT79ncobvK884r-xk3znkCmINN_0,28
-showtime/commands/start.py,sha256=DPGbgvGPh7I60LK_VioDljUhdmhNFVjEy6BchFv1lCo,1026
-showtime/core/__init__.py,sha256=54hbdFNGrzuNMBdraezfjT8Zi6g221pKlJ9mREnKwCw,34
-showtime/core/aws.py,sha256=GXJc3h55J5n5czjqkJpWLhvLMCdcZjZaOdVSsdvu7PQ,30008
-showtime/core/circus.py,sha256=avvcFqvHRKo2o_Yxm0V1jVRMF2RSLABTqhe_nMO3GAM,9504
-showtime/core/config.py,sha256=jISjWE79vFaIX1nqeNhRfs_jM5Xoe-p7LTmJzT1OsSI,4348
-showtime/core/emojis.py,sha256=iq2EginrCKN_oMh3XmZF9SgbMNSXV6e-JgwUAtRwUuM,2430
-showtime/core/github.py,sha256=U8H9tudJjmHVr1aWKDd7o5AJkmgUnX_AIC2lqh4voTg,7967
-showtime/data/ecs-task-definition.json,sha256=r1cgkZJ2SS1gul-WFuV-QlzdFjr5n3g-kdKka79N-Jk,1687
-superset_showtime-0.1.0.dist-info/METADATA,sha256=_gobO4ZLHlyTeyOrwhzSBgxLIHcElL6M0p8mc0Pb4Zs,13938
-superset_showtime-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-superset_showtime-0.1.0.dist-info/entry_points.txt,sha256=rDW7oZ57mqyBUS4N_3_R7bZNGVHB-104jwmY-hHC_ck,85
-superset_showtime-0.1.0.dist-info/RECORD,,