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

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