🐍 Python Queen - Queen Claude Python Template

Complete Python project generator with multiple pathways - CLI tools, REST APIs, AI applications, automation scripts, and libraries.

What This Is

Python Queen is a dynamic project generator that creates complete, production-ready Python applications from scratch. It's NOT a template repository - it's a generator that builds exactly what you need based on your choices.

Available Pathways

1. CLI Tool 🖥️

• Framework: Typer + Rich
• Use Case: Command-line applications, developer tools, scripts
• Features: Beautiful terminal UI, subcommands, progress bars, tables

2. REST API 🌐

• Framework: FastAPI
• Use Case: Web services, microservices, backend APIs
• Features: Auto-documentation, async support, type safety, validation

3. AI Application 🤖

• Frameworks: OpenAI/Anthropic/Ollama + Pydantic AI
• Use Case: Chatbots, agents, AI-powered tools
• Features: Type-safe agents, function calling, streaming, embeddings

4. Automation 🔄

• Framework: APScheduler
• Use Case: Cron jobs, background tasks, data pipelines
• Features: Scheduled execution, job monitoring, async tasks

5. Python Library 📦

• Framework: Standard packaging
• Use Case: Reusable packages, PyPI distribution
• Features: Proper structure, build config, version management

Quick Start

With Claude (Recommended)

1. Setup Python Project:

   User: /1-setup-python
   Claude: What type of Python project?
   User: 2 (for REST API)
   Claude: *Creates complete FastAPI project*

2. Add Database (Optional):

   User: /2-setup-database
   Claude: Database type? (1=SQLite, 2=PostgreSQL)
   User: 2
   Claude: *Adds SQLAlchemy + migrations*

3. Add AI (Optional):

   User: /3-setup-ai
   Claude: AI Provider? (1=OpenAI, 2=Anthropic, 3=Local)
   User: 1
   Claude: *Adds OpenAI integration*

Direct MCP Usage

// Create a FastAPI project
await mcp_queen_mcp_setup_python_foundation({
  project_path: "/path/to/my-api",
  project_type: "api",
  database_type: "postgresql"
});

// Add database
await mcp_queen_mcp_setup_python_database({
  project_path: "/path/to/my-api",
  database_type: "postgresql",
  auth_type: "simple"
});

// Add AI capabilities
await mcp_queen_mcp_setup_python_ai({
  project_path: "/path/to/my-api",
  ai_provider: "openai",
  vector_store: "chroma"
});

What Gets Created

Base Structure (All Types)

my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── main.py              # Entry point
│       ├── core/
│       │   ├── config.py        # Pydantic settings
│       │   └── logging.py       # Structured logging
│       └── utils/              # Utility functions
├── tests/
│   ├── unit/
│   └── integration/
├── .env.example                # Environment template
├── pyproject.toml              # Dependencies & config
├── README.md                   # Complete documentation
└── .gitignore

Type-Specific Additions

CLI Tool:

• commands/ - Typer subcommands
• models/ - Data models
• Rich tables and progress bars
• YAML config support

REST API:

• routers/ - API endpoints
• models/ - SQLAlchemy models
• middleware/ - CORS, auth
• Swagger UI at /docs

AI Application:

• agents/ - AI agent definitions
• prompts/ - Prompt templates
• tools/ - Function tools
• Provider integrations

Automation:

• jobs/ - Scheduled tasks
• services/ - Business logic
• Scheduler configuration
• Job monitoring

Library:

• Proper package structure
• __version__.py
• Build configuration
• PyPI metadata

Running Generated Projects

CLI Tools

cd my-cli-tool
uv run python -m src.my_cli_tool.main --help

REST APIs

cd my-api
uv run uvicorn src.my_api.main:app --reload
# API at http://localhost:8000
# Docs at http://localhost:8000/docs

AI Applications

cd my-ai-app
export OPENAI_API_KEY="sk-..."
uv run python -m src.my_ai_app.main

Automation Scripts

cd my-automation
uv run python -m src.my_automation.main
# Runs scheduler with configured jobs

Libraries

cd my-library
uv run pytest                    # Run tests
uv run python -m build           # Build package
uv run twine upload dist/*       # Upload to PyPI

Development Commands

All projects include:

# Dependency management
uv add package-name              # Add dependency
uv add --dev package-name        # Add dev dependency
uv sync                          # Install all deps

# Code quality
uv run ruff check .              # Lint code
uv run ruff format .             # Format code
uv run mypy src/                 # Type checking

# Testing
uv run pytest                    # Run tests
uv run pytest --cov              # With coverage
uv run pytest -v                 # Verbose output

# Database (if applicable)
uv run alembic revision --autogenerate -m "message"  # Create migration
uv run alembic upgrade head                          # Apply migrations

Environment Configuration

Each project includes .env.example:

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

# Database (if added)
DATABASE_URL=postgresql://user:pass@localhost/dbname

# AI Provider (if added)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_HOST=http://localhost:11434

# Security (if auth enabled)
SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

Key Features

🚀 Instant Start

• Projects run immediately after generation
• All dependencies installed
• Configuration ready
• Example code included

🎯 Type Safety

• Pydantic models everywhere
• Full type hints
• Mypy configuration
• Runtime validation

🧪 Testing Ready

• Pytest configured
• Test structure created
• Fixtures included
• Coverage setup

📦 Modern Python

• Python 3.11+ features
• Async/await support
• UV package manager
• Ruff for linting

🔧 Production Ready

• Structured logging
• Error handling
• Environment management
• Docker support

System Requirements

• Python 3.11 or higher
• uv package manager
• Git (for version control)

How It Works

1. You Choose: Select your project type (CLI, API, AI, etc.)
2. Generator Creates: Complete project structure with all files
3. Dependencies Install: Via uv automatically
4. Ready to Run: Immediately functional application

This is NOT a template you clone. It's a generator that creates fresh projects tailored to your specific needs.

Integration with Queen Claude

Python Queen is part of the larger Queen Claude ecosystem:

• Queen Claude: Main autonomous development system
• Python Queen: Python project generator (this)
• Next.js Queen: Next.js/React project generator
• Queen MCP: Model Context Protocol server

All work together to provide complete full-stack development capabilities.

License

MIT