Metadata-Version: 2.3
Name: pyvel-fastapi
Version: 0.1.0
Summary: Laravel-shaped DX for Python API backends on FastAPI — Artisan-like CLI and runtime bases
Keywords: fastapi,laravel,artisan,cli,scaffold,backend,api,pyvel
Author: Al-Amin Islam Nerob
Author-email: Al-Amin Islam Nerob <alamin@aincoder.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.30.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/aincoder/pyvel
Project-URL: Repository, https://github.com/aincoder/pyvel
Project-URL: Documentation, https://github.com/aincoder/pyvel#readme
Description-Content-Type: text/markdown

# pyvel

Batteries-included **Laravel-shaped** DX for **Python API backends** on FastAPI.

Pyvel gives you an Artisan-like CLI (`pyvel` / `artisan`), convention-based project layout, and small runtime bases (`AppError`, `register`, events). It is **backend/API only** — no Blade, Vite, or frontend stack.

> Long-term plans: see the workspace [`roadmap/`](../../roadmap/).

---

## Install

```bash
uv add pyvel-fastapi
# or
pip install pyvel-fastapi
```

The import and CLI stay **`pyvel`**:

```python
from pyvel import AppError, register
```

---

## Quick start

```bash
uvx --from pyvel-fastapi pyvel init myapp
cd myapp
uv sync
uv run dev
```

Scaffold into the current directory:

```bash
mkdir myapp && cd myapp
uvx --from pyvel-fastapi pyvel init
```

Monorepo / unpublished local checkout:

```bash
uv run pyvel init myapp --pyvel-path /path/to/packages/pyvel
```

---

## Stable CLI (0.1)

Entry points: `pyvel`, `artisan` (alias), and `dev`.

| Command | Purpose |
| --- | --- |
| `pyvel init [name]` | Scaffold a new API app (`--force`, `--pyvel-path`) |
| `pyvel make:exc` | Exception + HTTP handler |
| `pyvel make:req` / `make:res` | Request / response models |
| `pyvel make:middleware` | Middleware class |
| `pyvel make:router` | APIRouter module |
| `pyvel make:service` | Service class |
| `pyvel make:dependency` | FastAPI dependency |
| `pyvel make:schema` / `make:enum` / `make:config` | Schema, enum, settings |
| `pyvel make:event` / `make:listener` / `make:job` | Events, listeners, jobs |
| `pyvel make:test` | Pytest stub |
| `pyvel make:resource` | Router + requests + response + service |
| `pyvel list:routes` | List registered FastAPI routes |
| `dev` | Run uvicorn using `pyvel.toml` `[dev]` |

---

## Stable public API (0.1)

Supported imports for application code:

```python
from pyvel import AppError, EventDispatcher, dispatcher, register

# optional
import pyvel
print(pyvel.__version__)
```

| Symbol | Role |
| --- | --- |
| `AppError` | Base application error (override via `[bases].error`) |
| `register(app)` | Auto-register handlers, middleware, routers, listeners |
| `dispatcher` / `EventDispatcher` | In-process events |

Everything else under `pyvel.*` (`templates`, `generate`, `make`, `config` internals, …) is **private** and may change without notice.

See also [`API.md`](API.md).

---

## Config (`pyvel.toml`, optional)

All keys optional. Defaults:

```toml
app = "myapp"       # required in practice — set by `init`
src = "src"

[dev]
module = "myapp.main:app"   # default: "{app}.main:app"
host = "0.0.0.0"
port = 8000
reload = true

[paths]
errors = "http/exception/errors"
handlers = "http/exception/handlers"
requests = "http/requests"
responses = "http/responses"
middleware = "http/middleware"
routers = "http/routers"
dependencies = "http/dependencies"
services = "services"
schemas = "schemas"
enums = "domain/enums"
config = "config"
events = "events"
listeners = "listeners"
jobs = "jobs"
tests = "tests"             # relative to project root

[bases]
error = "pyvel.errors:AppError"
```

Fallback: `[tool.pyvel] app = "..."` in `pyproject.toml`.

---

## Out of scope (for now)

- Laravel-like `routes.py` + `Route` DSL / controllers — **Phase 1**
- Database / migrations — **Phase 2** (`pyvel-db`)
- Auth / policies — **Phase 3** (`pyvel-auth`)
- Queues, cache, mail — **Phase 4+**
- Frontend scaffolding — never (API-only)

---

## Publish (maintainers)

From the package directory, build into a local `dist/` then publish (workspace root builds go to the repo `dist/` by default):

```bash
cd packages/pyvel
uv build --out-dir dist
uv publish
# Uploads as distribution name: pyvel-fastapi
# or TestPyPI:
# uv publish --publish-url https://test.pypi.org/legacy/
```

From the workspace root (if artifacts are already in `./dist`):

```bash
uv publish dist/pyvel_fastapi-* dist/pyvel-fastapi-*
```

Until published, verify locally from a wheel:

```bash
uvx --from ./dist/pyvel_fastapi-0.1.0-py3-none-any.whl pyvel init /tmp/demoapp
# (wheel filename uses underscores; project name uses hyphens)
```

---

## Roadmap

Workspace plans: [`roadmap/README.md`](../../roadmap/README.md). **Phase 0 complete**; next is **Phase 1** (Artisan routing).
