moltpy 0.1.0

Interactive CLI tool for generating production-ready FastAPI project templates

MoltPy

MoltPy is an interactive CLI tool that generates production-ready, customizable FastAPI project templates from modular building blocks.

Features

• Interactive Wizard — Step-by-step CLI prompts with sensible defaults and live dependency visualization
• Modular Architecture — 36 modules; enable only what you need
• Declarative Configuration — Generate and reuse moltpy.yaml or JSON configuration files
• UV Integration — Modern, fast Python package management
• Docker Ready — Multi-stage Dockerfile and Docker Compose setup
• Authentication — JWT and OAuth2 password flow out of the box
• Database — SQLAlchemy 2.0 with Alembic migrations
• Background Jobs — Celery or ARQ with Redis broker
• Testing — pytest with async support and coverage
• Logging — Structured JSON logging with structlog
• CI/CD — GitHub Actions workflows included
• Documentation — MkDocs with Material theme
• Resource Scaffolder — Generate CRUD layers (model, schema, router, service, tests) with moltpy generate resource
• Dry Run — Preview projects before generating with --dry-run
• Safe Defaults — Overwrite protection with --force opt-in
• Syntax Validation — Generated Python is validated with py_compile before delivery
• Email Templates — Responsive HTML and plain-text templates for welcome, password reset, and receipts
• Grafana Dashboards — Pre-configured observability dashboard when observability and docker are selected
• Frontend SDK Generation — Auto-generate typed TypeScript clients from your OpenAPI specification
• Terraform IaC — Production-ready AWS/GCP infrastructure configurations
• Auto-Generated Docs — docs/modules.md and CONTRIBUTING.md generated for every project
• External Modules — Load modules from GitHub repositories (github:user/repo#module-name) or ~/.config/moltpy/modules/
• Custom Template Overrides — Override built-in templates with --template-dir for corporate branding or internal conventions

Installation

# Install with UV (recommended)
uv tool install moltpy

# Or with pip
pip install moltpy

Demo

$ moltpy new --preset standard --name my-api

✅ Project my-api created at ./my-api
   10 modules included

Next steps:
   cd my-api
   uv sync
   make run-dev

Quick Start

Interactive Mode

moltpy new

Follow the prompts to configure your project.

Preset Mode

# Use a built-in preset
moltpy new --preset standard --name my-api

# Available presets: minimal, standard, full-stack, microservice

Custom Modules

moltpy new --name my-api --modules auth,database,docker,testing

# With a GitHub module
moltpy new --name my-api --modules auth,github:user/repo#my-module --no-interactive

# With custom template overrides
moltpy new --name my-api --preset standard --template-dir ./my-templates --no-interactive

Resource Scaffolding (Day-2)

After creating a project, scaffold new CRUD resources without writing boilerplate:

cd my-api

# Generate a complete CRUD resource
moltpy generate resource Post title:str content:text is_published:bool

# Preview without writing
moltpy generate resource Post title:str --dry-run

# Skip the Alembic migration
moltpy generate resource Post title:str --skip-alembic

Declarative Configuration

# Generate a starter config file
moltpy init-config --preset standard --output moltpy.yaml

# Edit moltpy.yaml, then generate from it
moltpy new --config-file moltpy.yaml --no-interactive

# Or use JSON
moltpy new --config-file moltpy.json --no-interactive

Available Modules

Module	Description	Category
admin	Database admin panel with SQLAdmin	core
api_versioning	URL path versioning with /v1/, /v2/ prefix support	api
arq	ARQ lightweight async job queue with Redis	background_jobs
auth	JWT + OAuth2 password flow authentication with bcrypt hashing	security
auth_social	Google and GitHub OAuth2 login with JWT integration	security
celery	Celery background job processor with Redis broker	background_jobs
cors	CORS middleware configuration with environment-based origins	api
database	SQLAlchemy 2.0 async setup with Alembic migrations	core
docker	Multi-stage Dockerfile and Docker Compose setup	deployment
docs	MkDocs documentation structure with Material theme	documentation
email	Async email sending via SMTP or SendGrid	core
events	In-memory async event bus for decoupled domain events	core
github_actions	GitHub Actions CI/CD workflows	deployment
graphql	GraphQL API with Strawberry	api
grpc	gRPC services for high-performance inter-service communication	api
health	Health check endpoints for /health, /health/live, /health/ready	api
kubernetes	Raw Kubernetes YAML manifests	deployment
logging	Structured JSON logging with structlog and request ID middleware	infrastructure
makefile	Common development commands (lint, test, format, migrate, run-dev)	development
notifications	Push notifications with Firebase Cloud Messaging	infrastructure
observability	OpenTelemetry middleware and Prometheus /metrics endpoint	infrastructure
openapi	Custom OpenAPI schema customization and documentation	api
pagination	Generic pagination utilities with cursor and offset support	api
payments	Payment processing with Stripe (checkout, webhooks, customer portal)	infrastructure
pre_commit	Pre-commit hooks for ruff linting and formatting	development
rate_limit	SlowAPI rate limiting with Redis-backed sliding window	security
redis	Redis connection pool and dependency injection	infrastructure
scheduler	Background scheduled jobs with APScheduler	core
search	Full-text search with Meilisearch	infrastructure
seeding	Database seeding with Faker	development
sentry	Sentry error tracking integration with release tagging	infrastructure
storage	S3 / Cloud Storage boilerplate with aiobotocore	infrastructure
terraform	Infrastructure-as-Code with Terraform for AWS and GCP	deployment
testing	pytest + pytest-asyncio + httpx with factory-boy fixtures	development
users	User model, CRUD service, and admin endpoints	core
websockets	WebSockets with Redis Pub/Sub for multi-worker broadcasting	infrastructure

CLI Commands

# Create a new project
moltpy new

# Preview without writing files
moltpy new --name my_api --preset standard --dry-run --no-interactive

# Generate from a config file
moltpy new --config-file moltpy.yaml --no-interactive

# Skip post-generation hooks (uv sync, git init, pre-commit)
moltpy new --name my_api --preset standard --skip-post-generation --no-interactive

# Generate a starter config file
moltpy init-config --preset standard --output moltpy.yaml

# List available modules
moltpy modules list

# Show module details
moltpy modules info auth

# List presets
moltpy presets list

# Save custom preset
moltpy preset save --name my-preset --modules auth,database,docker

# Generate a CRUD resource in an existing project
moltpy generate resource Post title:str content:text is_published:bool

Generated Project Structure

my-api/
├── app/
│   ├── __init__.py
│   ├── main.py              # Application entry point
│   ├── config.py            # Configuration management
│   ├── dependencies.py      # Dependency injection
│   ├── routers/             # API route handlers
│   ├── models/              # Database models
│   ├── services/            # Business logic
│   ├── templates/email/     # Email templates (when email module selected)
│   └── utils/               # Utility functions
├── tests/                   # Test suite
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── grafana/                 # Grafana provisioning and dashboards (when observability selected)
├── terraform/               # Infrastructure-as-Code (when terraform selected)
├── .github/
│   └── workflows/
│       └── ci.yml
├── docs/
│   └── modules.md           # Auto-generated module catalog
├── pyproject.toml           # Project dependencies
├── Makefile                 # Common commands
├── CONTRIBUTING.md          # Auto-generated contributing guide
├── .pre-commit-config.yaml  # Pre-commit hooks
├── .env.example             # Environment template
└── README.md                # Project documentation

Development

# Clone the repository
git clone https://github.com/iolimat/moltpy.git
cd moltpy

# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

Contributing

We welcome contributions. Please see CONTRIBUTING.md for guidelines.

External Modules

MoltPy supports loading modules from external sources:

• Local directory: Place modules in ~/.config/moltpy/modules/<name>/
• GitHub: Reference with github:user/repo#module-name

See Custom Modules for details.

Adding a New Module

1. Create src/moltpy/modules/<module_name>/
2. Add manifest.json with metadata
3. Add templates/ with Jinja2 files
4. Add snippets/ for shared-file injections (optional)
5. Open a pull request

License

MIT

Acknowledgments

• FastAPI — The web framework
• UV — The modern Python package manager
• Jinja2 — The templating engine