@kenkaiiii/queen-python/template/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

# {{PROJECT_NAME}}

A modern Python {{PROJECT_TYPE}} project built with the latest tools and best practices.

## 🚀 Tech Stack

- **Python 3.11+** - Modern Python with latest features
- **uv** - Ultra-fast Python package manager
- **ruff** - Lightning-fast linter and formatter
- **mypy** - Static type checking
- **pytest** - Testing framework with coverage

## 📦 Installation

### Prerequisites

This project uses [uv](https://docs.astral.sh/uv/) for dependency management. Install it first:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### Setup

```bash
# Clone and setup
git clone <your-repo-url>
cd {{PROJECT_NAME}}

# Install dependencies (uv handles virtual environment automatically)
uv sync

# Activate the virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate     # Windows
```

## 🏃‍♂️ Quick Start

```bash
# Run the application
uv run src/{{PROJECT_NAME}}/main.py

# Or use the installed command
uv run {{PROJECT_NAME}}
```

## 🛠️ Development

### Code Quality

```bash
# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Fix linting issues automatically
uv run ruff check . --fix

# Type checking
uv run mypy src/
```

### Testing

```bash
# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Run tests in watch mode
uv run pytest --watch
```

### Adding Dependencies

```bash
# Add runtime dependency
uv add requests

# Add development dependency
uv add --dev black

# Remove dependency
uv remove requests
```

## 📝 Project Structure

```
{{PROJECT_NAME}}/
├── src/
│   └── {{PROJECT_NAME}}/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── .env.example
├── .gitignore
├── .pre-commit-config.yaml
├── pyproject.toml
└── README.md
```

## 🔧 Configuration

All configuration is centralized in `pyproject.toml`:

- **ruff** - Linting and formatting rules
- **mypy** - Type checking configuration
- **pytest** - Test discovery and coverage
- **uv** - Dependency management

## 🚀 Deployment

### Building

```bash
# Build distribution packages
uv build

# Install from local build
uv pip install dist/{{PROJECT_NAME}}-*.whl
```

### Docker

```bash
# Build container
docker build -t {{PROJECT_NAME}} .

# Run container
docker run {{PROJECT_NAME}}
```

## 📊 Code Quality Metrics

- **Type Coverage**: 100% (enforced by mypy strict mode)
- **Test Coverage**: Target 90%+ (measured by pytest-cov)
- **Linting**: Zero violations (enforced by ruff)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Run quality checks: `uv run ruff format . && uv run ruff check . && uv run mypy src/ && uv run pytest`
5. Commit: `git commit -m "feat: add feature"`
6. Push: `git push origin feature-name`
7. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## ⚡ Performance

This project uses modern Python tooling for optimal performance:

- **uv**: 10-100x faster than pip for package operations
- **ruff**: 100x faster than traditional linters (black + isort + flake8)
- **mypy**: Incremental type checking for fast feedback

## 🔗 Resources

- [uv Documentation](https://docs.astral.sh/uv/)
- [ruff Documentation](https://docs.astral.sh/ruff/)
- [mypy Documentation](https://mypy.readthedocs.io/)
- [pytest Documentation](https://docs.pytest.org/)