connectionsphere-fastapi-cli 0.2.1
CLI tool to generate production-ready FastAPI projects with modern tooling, Docker, and GitHub Actions
License: MIT
Requires Python: >=3.10
Keywords: boilerplate, cli, docker, fastapi, generator, github-actions, modern-python, mypy, ruff, scaffold, template, uv

# ConnectionSphere FastAPI CLI

A command-line tool to quickly scaffold production-ready FastAPI projects with modern Python tooling, Docker support, and GitHub Actions CI/CD pipelines.

## Features

- FastAPI with modern tooling
- Docker and docker-compose ready
- GitHub Actions CI/CD
- UV for fast dependency management
- MyPy strict type checking
- Ruff linting and formatting
- Pytest with async support
- Pre-commit hooks
- Pydantic v2 settings
- Structured project layouts

## Installation
```bash
pip install connectionsphere-fastapi-cli
```

Alternative installation methods:
```bash
# Using pipx (recommended for CLI tools)
pipx install connectionsphere-fastapi-cli

# Using uvx (no installation needed)
uvx connectionsphere-fastapi-cli create my-api
```

## Usage

### Basic Usage
```bash
# Create a new FastAPI project
fastapi-cli create my-api

# Navigate to project and start developing
cd my-api
source .venv/bin/activate
uv run uvicorn my_api.main:app --reload
```

### Advanced Options
```bash
# Specify GitHub organization
fastapi-cli create my-api --org my-company

# Choose Python version
fastapi-cli create my-api --python 3.11

# Use flat layout instead of src layout
fastapi-cli create my-api --layout flat

# Skip Docker configuration
fastapi-cli create my-api --no-docker

# Skip coverage configuration
fastapi-cli create my-api --no-coverage

# Specify target directory
fastapi-cli create my-api --dir /path/to/projects
```

### Complete Example
```bash
fastapi-cli create user-service \
    --org acme-corp \
    --python 3.12 \
    --layout src \
    --dir ~/projects
```

## Command Reference
```
fastapi-cli create <name> [options]

Arguments:
  name                  Project name (e.g., my-api, user_service)

Options:
  --org TEXT           GitHub organization name (default: your_org)
  --python TEXT        Python version: 3.10, 3.11, 3.12, 3.13 (default: 3.12)
  --layout TEXT        Project layout: flat or src (default: src)
  --no-coverage        Disable coverage reporting
  --no-docker          Skip Docker files
  --dir TEXT           Target directory (default: current directory)
  --help               Show help message
```

## Generated Project Structure

### Source Layout (default)
```
my-api/
├── src/
│   └── my_api/
│       ├── __init__.py
│       ├── main.py           # FastAPI application
│       ├── config.py         # Pydantic settings
│       ├── api/              # API routes
│       └── models/           # Data models
├── tests/
│   ├── __init__.py
│   └── test_main.py          # Example tests
├── .github/
│   └── workflows/
│       └── ci.yml            # CI/CD pipeline
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .pre-commit-config.yaml
├── .gitignore
├── LICENSE
└── README.md
```

### Flat Layout
```
my-api/
├── my_api/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── api/
│   └── models/
└── tests/
    └── test_main.py
```

## What's Included

### FastAPI Application

- Basic FastAPI app with health check endpoint
- CORS middleware configured
- Pydantic settings for configuration
- Structured project layout
- OpenAPI/Swagger documentation at `/docs`
- ReDoc documentation at `/redoc`

### Testing Infrastructure

- Pytest with async support
- Example test cases
- FastAPI TestClient configured
- Optional coverage reporting (80% minimum threshold)
- Parallel test execution with pytest-xdist

### Code Quality Tools

- Ruff for linting and code formatting
- MyPy with strict type checking enabled
- Pre-commit hooks for automated quality checks
- Consistent code style enforcement

### Docker Support

- Multi-stage Dockerfile optimized for production
- Docker Compose configuration for local development
- Hot reload enabled in development mode
- Production-ready container images

### CI/CD Pipeline

- GitHub Actions workflow included
- Automated testing on push and pull requests
- Code quality checks (Ruff)
- Type checking (MyPy)
- Docker image build and validation
- Package building verification

## Development Workflow

After creating a project:
```bash
# Navigate to project
cd my-api

# Activate virtual environment
source .venv/bin/activate

# Run development server with hot reload
uv run uvicorn my_api.main:app --reload

# Access API documentation
# Swagger UI: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc

# Run test suite
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Type checking
uv run mypy src/my_api tests

# Code linting
uv run ruff check .

# Code formatting
uv run ruff format .

# Run all quality checks
uv run pre-commit run --all-files
```

## Docker Usage
```bash
# Build and run with docker-compose
docker-compose up

# Build Docker image
docker build -t my-api .

# Run Docker container
docker run -p 8000:8000 my-api
```

## Requirements

- Python 3.10 or higher
- UV (installed automatically if not present)
- Git
- Docker (optional, for containerization features)

## Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run quality checks
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues, questions, or contributions, please visit the GitHub repository.