Metadata-Version: 2.4
Name: moltpy
Version: 0.1.0
Summary: Interactive CLI tool for generating production-ready FastAPI project templates
Project-URL: Homepage, https://github.com/iolimat/moltpy
Project-URL: Documentation, https://github.com/iolimat/moltpy#readme
Project-URL: Repository, https://github.com/iolimat/moltpy
Project-URL: Issues, https://github.com/iolimat/moltpy/issues
Author: MoltPy Contributors
License: MIT
License-File: LICENSE
Keywords: cli,fastapi,generator,scaffold,template,uv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: inquirer>=3.0
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=25.5.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# MoltPy

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

[![CI](https://img.shields.io/github/actions/workflow/status/iolimat/moltpy/ci.yml?branch=main)](https://github.com/iolimat/moltpy/actions)
[![PyPI](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/moltpy/)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![UV](https://img.shields.io/badge/uv-package%20manager-purple)](https://docs.astral.sh/uv/)

## 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

```bash
# Install with UV (recommended)
uv tool install moltpy

# Or with pip
pip install moltpy
```

## Demo

<!-- TODO: Replace with an asciinema cast or GIF demo of `moltpy new` -->

```bash
$ 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

```bash
moltpy new
```

Follow the prompts to configure your project.

### Preset Mode

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

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

### Custom Modules

```bash
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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](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](docs/usage/custom-modules.md) 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](LICENSE)

## Acknowledgments

- [FastAPI](https://fastapi.tiangolo.com/) — The web framework
- [UV](https://docs.astral.sh/uv/) — The modern Python package manager
- [Jinja2](https://jinja.palletsprojects.com/) — The templating engine
