superset-showtime 0.6.10__tar.gz

superset_showtime-0.6.10/.claude/settings.local.json

@@ -0,0 +1,70 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/max/code/superset/.github/workflows/**)",
+      "Bash(showtime stop:*)",
+      "Bash(python:*)",
+      "Bash(uv pip install:*)",
+      "Bash(aws configure:*)",
+      "Bash(env)",
+      "Bash(unset:*)",
+      "Bash(aws sts:*)",
+      "WebSearch",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(ruff check:*)",
+      "Bash(pytest:*)",
+      "Bash(make test:*)",
+      "Bash(uv pip compile:*)",
+      "Bash(chmod:*)",
+      "Read(//Users/max/code/**)",
+      "Bash(aws efs create-file-system:*)",
+      "Bash(export AWS_PROFILE=\"\")",
+      "Bash(AWS_PROFILE=\"\" aws efs create-file-system --tags Key=Name,Value=superset-examples Key=Purpose,Value=shared-examples-duckdb --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs create-file-system --tags Key=Name,Value=superset-examples Key=Purpose,Value=shared-examples-duckdb --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs create-file-system --performance-mode generalPurpose)",
+      "Bash(env -u AWS_PROFILE aws efs describe-file-systems --query 'FileSystems[?Tags[?Key==`Name` && Value==`superset-examples`]]')",
+      "Bash(env -u AWS_PROFILE aws efs describe-file-systems)",
+      "Bash(env:*)",
+      "Bash(grep:*)",
+      "Bash(git grep:*)",
+      "Bash(git push:*)",
+      "Bash(make lint:*)",
+      "Bash(mypy:*)",
+      "Bash(sed:*)",
+      "Bash(git pull:*)",
+      "Bash(git rebase:*)",
+      "Bash(git fetch:*)",
+      "Read(//Users/max/.claudette/worktrees/showtime/**)",
+      "Bash(rg:*)",
+      "Bash(find:*)",
+      "Bash(make:*)",
+      "Bash(showtime status:*)",
+      "Bash(showtime sync:*)",
+      "Bash(AWS_PROFILE=\"\" showtime sync 34831 --dry-run-aws --dry-run-github)",
+      "Bash(git stash:*)",
+      "Bash(showtime list:*)",
+      "Bash(showtime git-check)",
+      "Read(//^def aws_cleanup/,/**)",
+      "WebFetch(domain:github.com)",
+      "Bash(showtime labels:*)",
+      "Read(//Users/max/**)",
+      "Bash(showtime cleanup:*)",
+      "Bash(gh pr view:*)",
+      "Bash(for pr in 34842 35033 35152)",
+      "Bash(do echo \"PR $pr:\")",
+      "Bash(done)",
+      "Bash(cat:*)",
+      "Bash(docker pull:*)",
+      "Bash(docker run:*)",
+      "Bash(docker inspect:*)"
+    ],
+    "deny": [],
+    "ask": [],
+    "additionalDirectories": [
+      "/private/tmp",
+      "/Users/max/code/superset",
+      "/Users/max/.claudette/worktrees/showtime_gha/.github/workflows"
+    ]
+  }
+}

superset_showtime-0.6.10/.gitignore

@@ -0,0 +1,149 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Showtime specific
+.showtime/
+config.yml

superset_showtime-0.6.10/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+# TODO: Re-enable after fixing boto3-stubs type conflicts
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v1.8.0
+  #   hooks:
+  #     - id: mypy
+  #       files: ^showtime/
+  #       additional_dependencies: [types-requests, "boto3-stubs[ecs,ecr,ec2]"]

superset_showtime-0.6.10/CLAUDE.md

@@ -0,0 +1,232 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Superset Showtime is a CLI tool for managing Apache Superset ephemeral environments using "circus tent emoji labels" as a visual state management system on GitHub PRs. The tool integrates with GitHub Actions to provide automated environment provisioning on AWS ECS/ECR.
+
+## Development Commands
+
+**Package Management:**
+```bash
+# Install for development (preferred)
+uv pip install -e ".[dev]"
+
+# Traditional pip installation
+pip install -e ".[dev]"
+```
+
+**Code Quality:**
+```bash
+make lint           # Run ruff and mypy checks
+make format         # Auto-format with ruff
+make pre-commit     # Install pre-commit hooks
+make pre-commit-run # Run all pre-commit hooks
+```
+
+**Testing:**
+```bash
+make test          # Run pytest
+make test-cov      # Run tests with coverage report
+pytest tests/unit/test_circus.py  # Run specific test file
+```
+
+**Build and Distribution:**
+```bash
+make build         # Build package with uv
+make publish       # Publish to PyPI (use with caution)
+make clean         # Clean build artifacts
+```
+
+**Quick Testing:**
+```bash
+make circus        # Test circus emoji parsing logic
+```
+
+## Core Architecture
+
+### Main Components
+
+**CLI Layer (`showtime/cli.py`):**
+- Typer-based CLI with rich output formatting
+- Commands: `sync`, `start`, `stop`, `status`, `list`, `labels`, `cleanup`
+- Primary entry point for GitHub Actions and manual usage
+
+**Core Business Logic (`showtime/core/`):**
+
+1. **PullRequest (`pull_request.py`)** - Main orchestrator
+   - Manages PR-level state and atomic transactions
+   - Handles trigger processing and environment lifecycle
+   - Coordinates between GitHub labels and AWS resources
+   - Implements sync logic for automatic deployments
+
+2. **Show (`show.py`)** - Individual environment representation
+   - Represents a single ephemeral environment
+   - Manages Docker builds and AWS deployments
+   - Handles state transitions (building → running → failed)
+
+3. **GitHubInterface (`github.py`)** - GitHub API client
+   - Label management and PR data fetching
+   - Circus tent emoji label parsing and creation
+   - Token detection from environment or gh CLI
+
+4. **AWSInterface (`aws.py`)** - AWS operations
+   - ECS service deployment and management
+   - ECR image management
+   - Network configuration and service discovery
+
+### State Management Pattern
+
+The system uses GitHub labels as a distributed state machine:
+
+**Trigger Labels (User Actions):**
+- `🎪 ⚡ showtime-trigger-start` - Create environment
+- `🎪 🛑 showtime-trigger-stop` - Destroy environment
+- `🎪 🧊 showtime-freeze` - Prevent auto-sync
+- `🎪 🔒 showtime-blocked` - Block ALL operations (maintenance mode)
+
+**State Labels (System Managed):**
+- `🎪 {sha} 🚦 {status}` - Environment status
+- `🎪 🎯 {sha}` - Active environment pointer
+- `🎪 🏗️ {sha}` - Building environment pointer
+- `🎪 {sha} 🌐 {ip}` - Environment URL
+- `🎪 {sha} 📅 {timestamp}` - Creation timestamp
+
+### Atomic Transaction Model
+
+The `PullRequest.sync()` method implements an atomic claim pattern:
+1. **Claim**: Atomically remove trigger labels and set building state
+2. **Build**: Docker build with deterministic tags (`pr-{number}-{sha}-ci`)
+3. **Deploy**: AWS ECS service deployment with blue-green updates
+4. **Validate**: Health checks and state synchronization
+
+## Testing Approach
+
+**Unit Tests:** Focus on circus label parsing and business logic
+**Integration Tests:** Test with `--dry-run-aws --dry-run-docker` flags
+**Manual Testing:** Use CLI commands with dry-run modes
+
+## Key Design Principles
+
+1. **Deterministic Naming:** All AWS resources use `pr-{number}-{sha}` pattern
+2. **Idempotent Operations:** Safe to retry any operation
+3. **Visual State Management:** GitHub labels provide immediate status visibility
+4. **Zero-Downtime Updates:** Blue-green deployments with automatic traffic switching
+5. **Fail-Safe Defaults:** Conservative cleanup and error handling
+
+## Environment Variables
+
+**Required:**
+- `GITHUB_TOKEN` - GitHub API access
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` - AWS credentials
+
+**Optional:**
+- `AWS_REGION` - Default: us-west-2
+- `ECS_CLUSTER` - Default: superset-ci
+- `ECR_REPOSITORY` - Default: superset-ci
+- `GITHUB_ORG` - Default: apache
+- `GITHUB_REPO` - Default: superset
+
+**Superset Configuration (via ECS task definition):**
+- `SERVER_WORKER_AMOUNT` - Gunicorn worker processes (default: 1)
+- `SERVER_THREADS_AMOUNT` - Threads per worker (default: 20)
+
+See `showtime/data/ecs-task-definition.json` for complete container environment configuration.
+
+## GitHub Actions Integration
+
+The tool is designed to be called from GitHub Actions workflows:
+```yaml
+- name: Install Superset Showtime
+  run: pip install superset-showtime
+
+- name: Sync PR state
+  run: showtime sync ${{ github.event.number }}
+```
+
+Primary workflow file: `workflows-reference/showtime-trigger.yml`
+
+## Common Development Patterns
+
+**Testing without AWS costs:**
+```bash
+showtime sync 1234 --dry-run-aws --dry-run-docker
+```
+
+**Debugging specific PR:**
+```bash
+showtime status 1234 --verbose
+showtime list --status running
+```
+
+**Manual environment management:**
+```bash
+showtime start 1234 --sha abc123f
+showtime stop 1234 --force
+```
+
+## Race Condition Handling
+
+### Problem Description
+
+Double triggers can create race conditions in two scenarios:
+
+1. **Same SHA conflicts**: User pushes commit abc123f twice, creating 2 workflows for identical SHA
+2. **Stale locks**: Jobs crash or get killed, leaving environments stuck in "building/deploying" state indefinitely
+
+### Current Atomic Claim Mechanism
+
+The `PullRequest._atomic_claim()` method handles basic conflicts by:
+1. Checking if target SHA is already in progress states (`building`, `built`, `deploying`)
+2. Removing trigger labels atomically
+3. Setting building state immediately
+
+**Limitations**:
+- No distinction between valid locks and stale locks (>1 hour old)
+- `refresh_labels()` is expensive (~500ms) but called on every claim attempt
+- Crashed jobs can leave permanent locks that block future deployments
+
+### Proposed Smart Lock Detection Strategy
+
+**Two-phase approach optimizing for the common case**:
+
+#### Phase 1: Fast Path (95% of calls, ~5ms)
+```python
+def can_start_job(self, target_sha: str, action: str, use_cached: bool = True) -> tuple[bool, str]:
+    """Fast check using cached self.labels"""
+    # Check cached labels for basic conflicts
+    # Returns (can_start, reason)
+```
+
+#### Phase 2: Recovery Path (5% of calls, ~500ms)
+```python
+def double_check_and_cleanup_stale_locks(self, target_sha: str, stale_hours: int = 1, dry_run: bool = False) -> bool:
+    """Expensive: refresh labels, detect stale locks (>1h), clean them up"""
+    # Only called when fast path detects potential conflict
+    # Refreshes labels, checks timestamps, cleans stale AWS resources + GitHub labels
+```
+
+#### Enhanced Atomic Claim Logic
+```python
+def _atomic_claim(self, target_sha: str, action: str, dry_run: bool = False) -> bool:
+    # 1. Fast check with cached labels
+    can_start, reason = self.can_start_job(target_sha, action, use_cached=True)
+
+    if not can_start:
+        # 2. Expensive double-check and cleanup
+        can_start = self.double_check_and_cleanup_stale_locks(target_sha, stale_hours=1, dry_run=dry_run)
+
+    # 3. Continue with existing trigger removal + building setup
+```
+
+### Key Benefits
+
+- **Performance**: 95% fast path using cached labels (~5ms vs ~500ms)
+- **Reliability**: Automatic recovery from stale locks (crashed/killed jobs)
+- **Clarity**: Clear distinction between valid conflicts and recoverable states
+- **Safety**: Only cleans locks older than configurable threshold (default: 1 hour)
+
+### Implementation Notes
+
+This enhancement can be implemented when race conditions become problematic in practice. The current trigger removal mechanism already handles most same-SHA conflicts effectively due to the speed of GitHub label operations.

superset_showtime-0.6.10/Makefile

@@ -0,0 +1,54 @@
+.PHONY: help install install-dev test test-cov lint format clean pre-commit
+
+help: ## Show this help message
+	@echo 'Usage: make <target>'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-15s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install package dependencies
+	uv pip install -e .
+
+install-dev: ## Install package with development dependencies
+	uv pip install -e ".[dev]"
+
+test: ## Run tests
+	pytest
+
+test-cov: ## Run tests with coverage
+	pytest --cov=showtime --cov-report=term-missing --cov-report=html
+
+lint: ## Run linting
+	ruff check .
+	mypy showtime
+
+format: ## Format code
+	ruff format .
+	ruff check --fix .
+
+clean: ## Clean up build artifacts
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	rm -rf htmlcov/
+	rm -rf .coverage
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+pre-commit: ## Install pre-commit hooks
+	pre-commit install
+
+pre-commit-run: ## Run pre-commit hooks on all files
+	pre-commit run --all-files
+
+build: ## Build package
+	uv build
+
+publish: ## Publish to PyPI (use with caution)
+	uv build
+	uvx twine upload dist/*
+
+circus: ## Quick test of circus emoji parsing
+	python -c "from showtime.core.show import Show; labels=['🎪 abc123f 🚦 running', '🎪 🎯 abc123f']; show=Show.from_circus_labels(1234, labels, 'abc123f'); print(f'Status: {show.status}, SHA: {show.sha}')"