@kenkaiiii/queen-python/README.md

Create modern Python projects with uv, ruff, mypy, FastAPI, AI integration, and Queen Claude foundation - universal for APIs, AI applications, CLI tools, and automation

# Python Queen 🐍👑

Create modern Python projects with the latest tools and best practices. Part of the Queen Claude ecosystem.

## ⚡ Quick Start

```bash
# Install Queen Claude ecosystem (includes Python support)
npm install -g @kenkaiiii/queen-claude

# Create a new Python project
queen-python my-awesome-project

# Or specify project type directly
queen-python my-cli-tool cli
```

## 🚀 What You Get

**Modern Python Stack (2024-2025):**
- **uv** - Ultra-fast package manager (10-100x faster than pip)
- **ruff** - Lightning-fast linter & formatter (replaces black+isort+flake8)
- **mypy** - Strict type checking
- **pytest** - Testing with coverage
- **pre-commit** - Git hooks for quality

**Project Types:**
- 🖥️ **CLI Tool** - Click/Typer command-line applications
- 🌐 **Web API** - FastAPI/Django REST services
- 🤖 **Automation** - Task automation and scripting
- 📊 **Data Science** - Jupyter, pandas, analysis projects
- 📦 **Library** - Reusable Python packages
- ⚡ **Minimal** - Basic structure with core tooling

## 🛠️ Features

### Cross-Platform Excellence
- **Windows, macOS, Linux** - native binaries, no compilation
- **Docker** - production-ready containers included
- **GitHub Actions** - CI/CD pipeline configured
- **VS Code** - complete development environment

### Developer Experience
- **Single command setup** - everything configured automatically
- **Zero configuration** - works out of the box
- **Modern pyproject.toml** - no more setup.py complexity
- **Rich tooling** - pre-commit hooks, VS Code tasks, debugging

### Performance
- **uv**: 10-100x faster package operations
- **ruff**: 100x faster linting (0.2s vs 2s+)
- **Incremental tooling** - fast feedback loops

## 📦 Installation

Install via Queen Claude ecosystem:

```bash
npm install -g @kenkaiiii/queen-claude
queen-python <project-name> [type]
```

## 🎯 Usage Examples

```bash
# Interactive mode (prompts for project type)
queen-python my-project

# CLI application
queen-python my-cli cli

# FastAPI web service
queen-python my-api api

# Data science project
queen-python my-analysis datascience

# Python library
queen-python my-lib library

# Automation scripts
queen-python my-bot automation
```

## 🏗️ Project Structure

```
my-project/
├── src/my_project/          # Source code
│   ├── __init__.py
│   └── main.py
├── tests/                   # Test suite
│   ├── __init__.py
│   └── test_main.py
├── .github/workflows/       # CI/CD pipelines
├── .vscode/                 # VS Code configuration
├── pyproject.toml          # Modern Python configuration
├── uv.lock                 # Dependency lock file
├── Dockerfile              # Container support
├── docker-compose.yml      # Local development stack
└── README.md               # Project documentation
```

## ⚡ Daily Workflow

```bash
cd my-project

# Run your application
uv run python src/my_project/main.py

# Development commands
uv run ruff format .        # Format code
uv run ruff check .         # Lint code
uv run mypy src/           # Type check
uv run pytest             # Run tests

# Dependency management
uv add requests            # Add dependency
uv add --dev black         # Add dev dependency
uv sync                    # Sync environment
```

## 🔧 What's Configured

### Code Quality (Zero Setup)
- **ruff** replaces: black + isort + flake8 + pyupgrade + autoflake
- **mypy** strict mode for type safety
- **pytest** with coverage reporting
- **pre-commit** hooks for git commits

### Development Environment
- **VS Code** settings, tasks, and debugging
- **GitHub Actions** for CI/CD
- **Docker** for containerization
- **Environment** configuration with .env support

### Modern Standards
- **Python 3.11+** support
- **pyproject.toml** configuration
- **Type hints** enforced
- **Documentation** with examples

## 🚦 Quality Gates

Every project includes:
- ✅ **100% type coverage** (mypy strict mode)
- ✅ **Zero linting violations** (ruff)
- ✅ **Automated testing** (pytest)
- ✅ **Security scanning** (bandit)
- ✅ **Dependency validation** (uv)

## 🌟 Why Python Queen?

**Eliminates Setup Pain:**
- No more pip/venv/requirements.txt complexity
- No more black+isort+flake8 configuration hell
- No more "works on my machine" issues

**Modern Best Practices:**
- Latest Python tooling (2024-2025)
- Security-first configuration
- Production-ready from day one

**Universal Application:**
- CLI tools, web APIs, automation, data science
- Cross-platform compatibility
- Container and cloud ready

## 🔗 Part of Queen Claude Ecosystem

- **initialize-queen** - Core foundation & database
- **nextjs-queen** - Next.js applications
- **python-queen** - Python projects (this package)
- **queen-mcp** - Claude MCP integration

## 📊 Performance Comparison

| Operation | Traditional | Python Queen | Speedup |
|-----------|-------------|--------------|---------|
| Package install | 2-3 min | 15-20 sec | 10x |
| Linting | 2.5 sec | 0.2 sec | 12x |
| Formatting | 1.2 sec | 0.1 sec | 12x |
| Type checking | 0.8 sec | 0.3 sec | 3x |

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Test your changes: `npm test`
4. Commit: `git commit -m 'feat: add amazing feature'`
5. Push: `git push origin feature/amazing-feature`
6. Open a Pull Request

## 📄 License

MIT License - see LICENSE file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/kenkaiiii/queen-claude/issues)
- **Docs**: [Queen Claude Documentation](https://docs.queen-claude.com)
- **Examples**: [Example Projects](https://github.com/kenkaiiii/queen-claude-examples)

---

**Made with ❤️ by the Queen Claude Development Team**

*Empowering developers with modern Python tooling since 2024*