boringpy 0.1.0

Modern Python scaffolding framework inspired by NestJS CLI - scaffold FastAPI projects with Docker, Alembic, and production-ready structure

BoringPy

Modern Python scaffolding framework inspired by NestJS CLI - scaffold production-ready FastAPI projects in seconds.

✨ Features

• 🚀 Instant FastAPI Projects - Generate complete APIs with Docker, Alembic, and tests
• 🗄️ Database Ready - PostgreSQL, MySQL, or SQLite with SQLModel ORM
• 🐳 Docker First - Full docker-compose setup with hot reload
• 📦 UV Powered - Lightning-fast package management with uv
• 🎯 Type Safe - Full type annotations and strict type checking
• 🏗️ Monorepo Ready - Workspace support for multiple APIs and shared libraries
• 🧪 Test Infrastructure - pytest with coverage reporting
• 📝 Professional Makefile - 30+ commands for development workflow

📦 Installation

Requirements

• Python 3.13+
• uv package manager

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install BoringPy

pip install boringpy

Or with uv:

uv tool install boringpy

🚀 Quick Start

1. Create a Workspace

boringpy init my-workspace
cd my-workspace

This creates:

my-workspace/
├── src/
│   ├── apps/       # Generated APIs
│   ├── libs/       # Shared libraries
│   └── scripts/    # Utility scripts
├── boringpy.json   # Workspace config
├── pyproject.toml  # UV workspace
└── README.md

2. Generate Your First API

boringpy generate api my_blog --port 8000 --db postgresql

This creates a complete FastAPI application with:

• ✅ FastAPI with async/await
• ✅ SQLModel ORM + Alembic migrations
• ✅ Docker & docker-compose
• ✅ Environment-based configuration
• ✅ Structured logging
• ✅ pytest test suite
• ✅ Professional Makefile
• ✅ Health check endpoints
• ✅ API documentation (Swagger/ReDoc)

3. Run Your API

cd src/apps/my_blog

# Copy environment file
cp .env.example .env

# Start with Docker (recommended)
make docker-up

# Run migrations
make db-upgrade

# View logs
make docker-logs

# Stop containers
make docker-down

Your API is now running at http://localhost:8000!

• API Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health: http://localhost:8000/health

📖 Usage

Commands

# Show version
boringpy --version

# Show help
boringpy --help

# Initialize workspace
boringpy init <workspace-name>

# Generate FastAPI application
boringpy generate api <name> [OPTIONS]
  --port INTEGER       API port (default: 8000)
  --db TEXT           Database type: postgresql, mysql, sqlite (default: postgresql)

# Coming soon
boringpy generate lib <name>      # Generate shared library
boringpy generate model <name>    # Generate SQLModel

Database Options

PostgreSQL (default):

boringpy generate api my_api --db postgresql

MySQL:

boringpy generate api my_api --db mysql

SQLite (no container needed):

boringpy generate api my_api --db sqlite

Generated API Makefile Commands

Every generated API includes a comprehensive Makefile:

# Development
make dev                    # Run API locally
make dev-reload             # Run with auto-reload
make test                   # Run tests
make test-cov               # Run tests with coverage

# Code Quality
make format                 # Format code with ruff
make lint                   # Lint code
make typecheck              # Type check with ty
make check                  # Run all checks

# Docker
make docker-build           # Build Docker image
make docker-up              # Start containers
make docker-down            # Stop containers
make docker-logs            # View logs
make docker-shell           # Shell into container

# Database
make db-upgrade             # Run migrations
make db-downgrade           # Rollback migration
make db-create-migration MSG="description"  # Create migration
make db-history             # View migration history
make db-shell               # Database shell

🗂️ Project Structure

Generated APIs follow this structure:

my_api/
├── app/
│   ├── core/
│   │   ├── config.py       # Settings & configuration
│   │   ├── database.py     # Database connection
│   │   ├── logger.py       # Logging setup
│   │   └── lifespan.py     # App lifecycle
│   ├── models/
│   │   ├── base.py         # Base SQLModel
│   │   └── example.py      # Example model
│   ├── api/
│   │   ├── deps.py         # Dependencies
│   │   └── v1/
│   │       └── endpoints/
│   │           └── health.py
│   ├── services/           # Business logic
│   └── main.py             # FastAPI app
├── migrations/             # Alembic migrations
├── tests/                  # pytest tests
├── docker-compose.yml      # Multi-container setup
├── Dockerfile              # Multi-stage build
├── Makefile                # Development commands
├── .env.example            # Environment template
├── alembic.ini             # Migration config
└── README.md               # API documentation

🔧 Configuration

Workspace Config (boringpy.json)

{
  "version": "0.1.0",
  "type": "workspace",
  "defaults": {
    "api": {
      "db_type": "postgresql",
      "port": 8000
    }
  },
  "workspace_members": [
    "src/apps/my_api"
  ]
}

API Environment (.env)

# Application
APP_NAME=my_api
APP_VERSION=0.1.0
DEBUG=true

# Server
HOST=0.0.0.0
PORT=8000

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/db
DB_ECHO=false
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Logging
LOG_LEVEL=INFO

🎯 Use Cases

Single API Project

boringpy init my-project
cd my-project
boringpy generate api backend --port 8000

Microservices Monorepo

boringpy init my-company
cd my-company
boringpy generate api users_service --port 8001
boringpy generate api orders_service --port 8002
boringpy generate api payments_service --port 8003

API + Shared Libraries

boringpy init my-platform
cd my-platform
boringpy generate api web_api --port 8000
boringpy generate lib auth_utils     # Coming soon
boringpy generate lib database_models # Coming soon

🛠️ Technology Stack

Generated projects use:

• FastAPI - Modern async web framework
• SQLModel - SQL databases with Python types
• Alembic - Database migrations
• Pydantic - Data validation
• uvicorn - ASGI server
• pytest - Testing framework
• ruff - Linting & formatting
• Docker - Containerization
• uv - Package management

📚 Examples

Minimal Example

# Create and run an API in 4 commands
boringpy init blog
cd blog
boringpy generate api api --db sqlite
cd src/apps/api && make dev

Production Example

# Full production setup with PostgreSQL
boringpy init production-app
cd production-app
boringpy generate api api --port 8000 --db postgresql

cd src/apps/api
cp .env.example .env
# Edit .env with production values

make docker-build
make docker-up
make db-upgrade

🤔 Why BoringPy?

BoringPy takes the "boring" out of project setup. No more:

• ❌ Manual FastAPI boilerplate
• ❌ Copying docker-compose files
• ❌ Setting up Alembic from scratch
• ❌ Writing Makefiles
• ❌ Configuring logging

Just run boringpy generate api and start building features immediately.

Inspired by NestJS CLI - but for Python and FastAPI.

🗺️ Roadmap

• Workspace initialization
• FastAPI API generation
• Multi-database support
• Docker setup
• Alembic migrations
• Library generation
• SQLModel generator
• CRUD endpoint generator
• Authentication templates
• AWS/GCP deployment helpers
• Plugin system

🤝 Contributing

Contributions welcome! Please check out our contributing guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Inspired by NestJS CLI
• Powered by Astral tooling (uv, ruff)
• Built with Typer and Rich

---

Built with ❤️ for the Python community

⭐ Star us on GitHub | 📦 PyPI Package | 📖 Documentation