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/.

Install

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

The import and CLI stay pyvel:

from pyvel import AppError, register

Quick start

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

Scaffold into the current directory:

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

Monorepo / unpublished local checkout:

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

Stable CLI (0.1)

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

Stable public API (0.1)

Supported imports for application code:

from pyvel import AppError, EventDispatcher, dispatcher, register

# optional
import pyvel
print(pyvel.__version__)

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

See also API.md.

Config (pyvel.toml, optional)

All keys optional. Defaults:

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):

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):

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

Until published, verify locally from a wheel:

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. Phase 0 complete; next is Phase 1 (Artisan routing).