Metadata-Version: 2.4
Name: snapstack
Version: 1.0.0
Summary: The create-next-app experience for Python — zero-config FastAPI/Django/Flask scaffolding
Project-URL: Homepage, https://github.com/thewizard2030/pysnap
Project-URL: Repository, https://github.com/thewizard2030/pysnap
Project-URL: Issues, https://github.com/thewizard2030/pysnap/issues
Author-email: Your Name <you@example.com>
License: MIT
License-File: LICENSE
Keywords: boilerplate,cli,django,fastapi,flask,project-starter,scaffolding,snapstack
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# snapstack

**The `create-next-app` experience for Python backend projects.**

Scaffold a fully wired FastAPI, Django, or Flask project in seconds -- not hours.

[![PyPI version](https://img.shields.io/pypi/v/snapstack?color=blue&label=PyPI)](https://pypi.org/project/snapstack/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-59%20passed-brightgreen)](https://github.com/thewizard2030/pysnap/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

</div>

---

Every Python developer knows the drill: new project, 45 minutes of boilerplate. Folder structure, config, Docker, CI, tests, auth -- all wired up by hand, every single time.

JavaScript solved this years ago with `create-next-app`. Python didn't have an equivalent. **Until now.**

```bash
pip install snapstack
snapstack create my-api
```

Answer a few prompts. Get a production-ready project. Start coding your actual features.

---

## What You Get

Every generated project includes:

- **Working code on first run** -- zero manual edits required
- **Health check endpoint** already wired and tested
- **pyproject.toml** with hatchling, typed config, and dev extras
- **pytest test suite** with fixtures and a passing test
- **Dockerfile + docker-compose** with multi-stage build and health checks
- **GitHub Actions CI** with lint + test pipeline
- **JWT authentication** (optional) with login, register, and refresh
- **SQLAlchemy 2 / Django ORM** with async support and migrations
- **.env.example** with documented config variables
- **.pysnap.json manifest** for future `snapstack update` upgrades

## Frameworks

<table>
<tr>
<td width="33%">

### FastAPI

Async API with Pydantic v2, SQLAlchemy 2, uvicorn

```bash
snapstack create my-api \
  --framework fastapi \
  --db postgresql \
  --auth --docker --ci
```

</td>
<td width="33%">

### Django

Classic Django with DRF, SimpleJWT, python-decouple

```bash
snapstack create my-app \
  --framework django \
  --db postgresql \
  --auth --docker --ci
```

</td>
<td width="33%">

### Flask

Minimal Flask with Blueprints, SQLAlchemy 2, factory pattern

```bash
snapstack create my-service \
  --framework flask \
  --db sqlite \
  --docker --ci
```

</td>
</tr>
</table>

## Generated Project Structure

```
my-api/
├── app/
│   ├── api/routes/          # Route handlers
│   ├── core/config.py       # Typed settings (.env)
│   ├── core/security.py     # JWT auth (optional)
│   ├── db/session.py        # Async database session
│   ├── models/              # ORM models
│   ├── schemas/             # Pydantic schemas
│   └── main.py              # App entrypoint
├── tests/
│   ├── conftest.py
│   └── test_health.py
├── .github/workflows/ci.yml
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .env.example
├── .pysnap.json             # Manifest for `snapstack update`
└── README.md
```

## Install

```bash
# Recommended
uv tool install snapstack

# Or with pip
pip install snapstack
```

Requires Python 3.11+.

## Quick Start

### Interactive mode (guided prompts)

```bash
snapstack create my-api
```

### Non-interactive mode (CI-friendly)

```bash
snapstack create my-api \
  --framework fastapi \
  --db sqlite \
  --no-auth \
  --docker \
  --ci \
  --tests \
  --pm uv
```

### Preview before generating

```bash
snapstack create my-api
# Shows a file tree preview before writing anything
```

### Add features to existing projects

```bash
cd my-existing-project
snapstack add docker        # Add Dockerfile + docker-compose
snapstack add ci            # Add GitHub Actions workflow
snapstack add auth          # Add JWT authentication
snapstack add tests         # Add pytest boilerplate
```

### Update infrastructure files

```bash
snapstack update            # Interactive diff review
snapstack update --dry-run  # See changes without applying
snapstack update --accept-all
```

### Community templates

```bash
# Browse available templates
snapstack templates list
snapstack templates search "graphql"
```

## Plugin System

Third-party packages can register custom framework templates via Python entry points:

```toml
# In a plugin's pyproject.toml
[project.entry-points."pysnap.plugins"]
my-template = "my_package.plugin:register"
```

Plugins appear automatically in prompts after `pip install`.

## CLI Reference

| Command                                | Description                                        |
| -------------------------------------- | -------------------------------------------------- |
| `snapstack create <name>`              | Scaffold a new project                             |
| `snapstack add <component>`            | Add docker, ci, auth, or tests to existing project |
| `snapstack update`                     | Update infrastructure files from latest templates  |
| `snapstack templates list`             | List all available templates                       |
| `snapstack templates search <keyword>` | Search community template registry                 |
| `snapstack --version`                  | Show version                                       |

## Flags for `snapstack create`

| Flag                       | Values                         | Default                   |
| -------------------------- | ------------------------------ | ------------------------- |
| `--framework`, `-f`        | `fastapi`, `django`, `flask`   | `fastapi`                 |
| `--db`, `-d`               | `sqlite`, `postgresql`, `none` | `sqlite`                  |
| `--auth` / `--no-auth`     |                                | `--no-auth`               |
| `--docker` / `--no-docker` |                                | `--docker`                |
| `--ci` / `--no-ci`         |                                | `--ci`                    |
| `--tests` / `--no-tests`   |                                | `--tests`                 |
| `--pm`                     | `uv`, `pip`, `poetry`          | `uv`                      |
| `--output`, `-o`           | path                           | `.`                       |
| `--no-preview`             |                                | show preview              |
| `--no-validate`            |                                | validate after generation |

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Development setup
git clone https://github.com/thewizard2030/pysnap.git
cd pysnap
pip install -e ".[dev]"
pytest
```

## License

[MIT](LICENSE)
