Metadata-Version: 2.4
Name: superset-showtime
Version: 0.6.4
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/
Project-URL: Repository, https://github.com/apache/superset-showtime.git
Project-URL: Bug Tracker, https://github.com/apache/superset-showtime/issues
Project-URL: Changelog, https://github.com/apache/superset-showtime/blob/main/CHANGELOG.md
Author-email: Maxime Beauchemin <maximebeauchemin@gmail.com>
License-Expression: Apache-2.0
Keywords: aws,circus,devops,environments,ephemeral,github,showtime,superset
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Requires-Dist: boto3>=1.26.0
Requires-Dist: botocore>=1.29.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=10.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: azure-mgmt-containerinstance>=10.0.0; extra == 'all'
Requires-Dist: azure-storage-blob>=12.0.0; extra == 'all'
Requires-Dist: boto3>=1.26.0; extra == 'all'
Requires-Dist: botocore>=1.29.0; extra == 'all'
Requires-Dist: google-cloud-compute>=1.11.0; extra == 'all'
Requires-Dist: google-cloud-storage>=2.8.0; extra == 'all'
Requires-Dist: kubernetes>=26.0.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.26.0; extra == 'aws'
Requires-Dist: botocore>=1.29.0; extra == 'aws'
Provides-Extra: azure
Requires-Dist: azure-mgmt-containerinstance>=10.0.0; extra == 'azure'
Requires-Dist: azure-storage-blob>=12.0.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: boto3-stubs[ec2,ecr,ecs]>=1.40.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.9; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: google-cloud-compute>=1.11.0; extra == 'gcp'
Requires-Dist: google-cloud-storage>=2.8.0; extra == 'gcp'
Provides-Extra: k8s
Requires-Dist: kubernetes>=26.0.0; extra == 'k8s'
Description-Content-Type: text/markdown

# 🎪 Superset Showtime

**Modern ephemeral environment management for Apache Superset using circus tent emoji labels**

[![PyPI version](https://badge.fury.io/py/superset-showtime.svg)](https://badge.fury.io/py/superset-showtime)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## 🎯 What is Showtime?

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.

## 🚀 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)

**Clean up when done:**
```bash
# Add this label:
🎪 🛑 showtime-trigger-stop
# All circus labels disappear, AWS resources cleaned up
```

## 🎪 How It Works

**🎪 GitHub labels become a visual state machine:**
```bash
# User adds trigger label in GitHub UI:
🎪 ⚡ showtime-trigger-start

# System responds with state labels:
🎪 abc123f 🚦 building      # Environment abc123f is building
🎪 🎯 abc123f               # abc123f is the active environment
🎪 abc123f 📅 2024-01-15T14-30  # Created timestamp
🎪 abc123f ⌛ 24h           # Time-to-live policy
🎪 abc123f 🤡 maxime        # Requested by maxime (clown emoji!)

# When ready:
🎪 abc123f 🚦 running       # Environment is now running
🎪 abc123f 🌐 52-1-2-3      # Available at http://52.1.2.3:8080
```

### 🔄 Showtime Workflow

```mermaid
flowchart TD
    A[User adds 🎪 ⚡ trigger-start] --> B[GitHub Actions: sync]
    B --> C{Current state?}

    C -->|No environment| D[🔒 Claim: Remove trigger + Set building]
    C -->|Running + new SHA| E[🔒 Claim: Remove trigger + Set building]
    C -->|Already building| F[❌ Exit: Another job active]
    C -->|No triggers| G[❌ Exit: Nothing to do]

    D --> H[📋 State: building]
    E --> H
    H --> I[🐳 Docker build]
    I -->|Success| J[📋 State: built]
    I -->|Fail| K[📋 State: failed]

    J --> L[📋 State: deploying]
    L --> M[☁️ AWS Deploy]
    M -->|Success| N[📋 State: running]
    M -->|Fail| O[📋 State: failed]

    N --> P[🎪 Environment ready!]

    Q[User adds 🎪 🛑 trigger-stop] --> R[🧹 Cleanup AWS + Remove labels]
```


**Install CLI for debugging:**
```bash
pip install superset-showtime
export GITHUB_TOKEN=your_token
```

**Monitor and debug:**
```bash
showtime list                    # See all active environments
showtime status 1234            # Debug specific environment
showtime labels                 # Complete label reference
```

**Testing/development:**
```bash
showtime sync 1234 --dry-run-aws --dry-run-docker  # Test without costs
showtime cleanup --dry-run --older-than 1h         # Test cleanup logic
```

> **Architecture**: This CLI implements ACID-style atomic transactions with direct Docker integration. It handles complete environment lifecycle from Docker build to AWS deployment with race condition prevention.

## 🎪 Complete Label Reference

### 🎯 Trigger Labels (Add These to Your PR)

| Label | Action | Result |
|-------|---------|---------|
| `🎪 ⚡ 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)

| Label Pattern | Meaning | Example |
|---------------|---------|---------|
| `🎪 {sha} 🚦 {status}` | Environment status | `🎪 abc123f 🚦 running` |
| `🎪 🎯 {sha}` | Active environment pointer | `🎪 🎯 abc123f` |
| `🎪 🏗️ {sha}` | Building environment pointer | `🎪 🏗️ def456a` |
| `🎪 {sha} 📅 {timestamp}` | Creation time | `🎪 abc123f 📅 2024-01-15T14-30` |
| `🎪 {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` |

## 🔧 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: `🎪 ⚡ showtime-trigger-start`
2. **Watch state labels appear:**
   ```
   🎪 abc123f 🚦 building      ← Environment is building
   🎪 🎯 abc123f               ← This is the active environment
   🎪 abc123f 📅 2024-01-15T14-30  ← Started building at this time
   ```
3. **Wait for completion:**
   ```
   🎪 abc123f 🚦 running       ← Now ready!
   🎪 abc123f 🌐 52.1.2.3:8080  ← Visit http://52.1.2.3:8080
   ```

### Testing Specific Commits

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!)

When you push new commits, Showtime automatically:
1. **Detects new commit** via GitHub webhook
2. **Builds new environment** alongside old one
3. **Switches traffic** when new environment is ready
4. **Cleans up old environment**

You'll see:
```bash
# During update:
🎪 abc123f 🚦 running       # Old environment still serving
🎪 def456a 🚦 building      # New environment building
🎪 🎯 abc123f               # Traffic still on old
🎪 🏗️ def456a               # New one being prepared

# After update:
🎪 def456a 🚦 running       # New environment live
🎪 🎯 def456a               # Traffic switched
🎪 def456a 🌐 52-4-5-6      # New IP address
# All abc123f labels removed automatically
```

## 🔒 Security & Permissions

### Who Can Use This?

- **✅ Superset maintainers** (with write access) can add trigger labels
- **❌ External contributors** cannot trigger environments (no write access to add labels)
- **🔒 Secure by design** - only trusted users can create expensive AWS resources

### GitHub Actions Integration

**🎯 Live Workflow**: [showtime-trigger.yml](https://github.com/apache/superset/actions/workflows/showtime-trigger.yml)

**How it works:**
- Triggers on PR label changes, commits, and closures
- Installs `superset-showtime` from PyPI (trusted code, not PR code)
- Runs `showtime sync` to handle trigger processing and deployments
- Supports manual testing via `workflow_dispatch` with specific SHA override

**Commands used:**
```bash
showtime sync PR_NUMBER --check-only    # Determine build_needed + target_sha
showtime sync PR_NUMBER --sha SHA       # Execute atomic claim + build + deploy
```

## 🛠️ CLI Usage

The CLI is primarily used by GitHub Actions, but available for debugging and advanced users:

```bash
pip install superset-showtime
export GITHUB_TOKEN=your_token

# Core commands:
showtime sync PR_NUMBER              # Sync to desired state (main command)
showtime start PR_NUMBER             # Create new environment
showtime stop PR_NUMBER              # Delete environment
showtime status PR_NUMBER            # Show current state
showtime list                        # List all environments
showtime cleanup --older-than 48h    # Clean up expired environments
```



## 🤝 Contributing

### Testing Your Changes

**Test with real PRs safely:**
```bash
# Test full workflow without costs:
showtime sync YOUR_PR_NUMBER --dry-run-aws --dry-run-docker

# Test cleanup logic:
showtime cleanup --dry-run --older-than 24h
```

### Development Setup

```bash
git clone https://github.com/mistercrunch/superset-showtime
cd superset-showtime

# Using uv (recommended):
uv pip install -e ".[dev]"
make pre-commit
make test

# Traditional pip:
pip install -e ".[dev]"
pre-commit install
pytest
```

## 📄 License

Apache License 2.0 - same as Apache Superset.

---

**🎪 "Ladies and gentlemen, welcome to Superset Showtime - where ephemeral environments are always under the big top!"** 🎪🤡✨
