pyvel-fastapi 0.1.0__py3-none-any.whl

pyvel/__init__.py

@@ -0,0 +1,8 @@
+"""pyvel — FastAPI scaffolding CLI and shared runtime bases."""
+
+from pyvel.errors import AppError
+from pyvel.events import EventDispatcher, dispatcher
+from pyvel.registry import register
+
+__all__ = ["AppError", "EventDispatcher", "dispatcher", "register"]
+__version__ = "0.1.0"

pyvel/app.py

@@ -0,0 +1,46 @@
+"""pyvel CLI entrypoints (`pyvel`, `artisan`, and `dev`)."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+import uvicorn
+
+from pyvel import init_cmd, list_cmd, make
+from pyvel.config import clear_settings_cache, load_settings
+
+app = typer.Typer(
+    name="pyvel",
+    help="Laravel-shaped scaffolding CLI for Python API backends on FastAPI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+init_cmd.register(app)
+make.register(app)
+list_cmd.register(app)
+
+
+def _clear_terminal() -> None:
+    """Clear the screen and scrollback buffer."""
+    sys.stdout.write("\033[2J\033[3J\033[H")
+    sys.stdout.flush()
+
+
+def dev() -> None:
+    """Run the API with settings from optional `pyvel.toml`."""
+    clear_settings_cache()
+    settings = load_settings()
+    dev_cfg = settings.resolved_dev()
+    _clear_terminal()
+    uvicorn.run(
+        dev_cfg.module,
+        host=dev_cfg.host,
+        port=dev_cfg.port,
+        reload=dev_cfg.reload,
+    )
+
+
+if __name__ == "__main__":
+    app()

pyvel/config.py

@@ -0,0 +1,172 @@
+"""Load optional project-root `pyvel.toml` with built-in defaults."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, replace
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_PATHS: dict[str, str] = {
+    "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",
+}
+
+DEFAULT_ERROR_BASE = "pyvel.errors:AppError"
+
+
+@dataclass(frozen=True, slots=True)
+class DevSettings:
+    """Uvicorn settings for `pyvel` / `dev`."""
+
+    module: str
+    host: str = "0.0.0.0"
+    port: int = 8000
+    reload: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class PyvelSettings:
+    """Resolved project settings for generators and runtime registration."""
+
+    root: Path
+    app: str
+    src: str = "src"
+    paths: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_PATHS))
+    error_base: str = DEFAULT_ERROR_BASE
+    dev: DevSettings | None = None
+
+    @property
+    def app_dir(self) -> Path:
+        """Filesystem path to the application package."""
+        return self.root / self.src / self.app
+
+    @property
+    def tests_dir(self) -> Path:
+        """Filesystem path to the tests directory."""
+        return self.root / self.paths.get("tests", "tests")
+
+    def path(self, key: str) -> Path:
+        """Return an absolute path under the app package for a `[paths]` key."""
+        relative = self.paths.get(key, DEFAULT_PATHS[key])
+        return self.app_dir / relative
+
+    def package(self, key: str) -> str:
+        """Return a dotted package name for a `[paths]` key under the app."""
+        relative = self.paths.get(key, DEFAULT_PATHS[key])
+        return f"{self.app}." + relative.replace("/", ".").replace("\\", ".")
+
+    def error_base_parts(self) -> tuple[str, str]:
+        """Split `error_base` into `(module, attr)`."""
+        module, _, attr = self.error_base.partition(":")
+        if not module or not attr:
+            raise ValueError(f"Invalid [bases].error value: {self.error_base!r}")
+        return module, attr
+
+    def resolved_dev(self) -> DevSettings:
+        """Return dev settings, defaulting module to `{app}.main:app`."""
+        if self.dev is not None:
+            return self.dev
+        return DevSettings(module=f"{self.app}.main:app")
+
+
+def find_project_root(start: Path | None = None) -> Path:
+    """Walk upward until `pyvel.toml` or `pyproject.toml` is found."""
+    current = (start or Path.cwd()).resolve()
+    for path in [current, *current.parents]:
+        if (path / "pyvel.toml").is_file() or (path / "pyproject.toml").is_file():
+            return path
+    raise FileNotFoundError("Could not find project root (pyvel.toml or pyproject.toml).")
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    with path.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+def _app_from_pyproject(root: Path) -> str | None:
+    data = _read_toml(root / "pyproject.toml")
+    tool = data.get("tool", {})
+    for key in ("pyvel", "artisan"):
+        app = tool.get(key, {}).get("app")
+        if isinstance(app, str) and app:
+            return app
+    return None
+
+
+@lru_cache(maxsize=8)
+def load_settings(start: str | None = None) -> PyvelSettings:
+    """Load settings from `pyvel.toml` / pyproject with defaults.
+
+    Pass *start* as a string path for cacheability; use ``None`` for cwd.
+    """
+    root = find_project_root(Path(start) if start else None)
+    file_data = _read_toml(root / "pyvel.toml")
+
+    app = file_data.get("app") or _app_from_pyproject(root)
+    if not app:
+        # Last resort: first package under src/ that isn't a known tool package
+        src_dir = root / str(file_data.get("src", "src"))
+        candidates = [
+            p.name
+            for p in src_dir.iterdir()
+            if p.is_dir() and (p / "__init__.py").exists() and p.name not in {"pyvel", "cli"}
+        ] if src_dir.is_dir() else []
+        if not candidates:
+            raise RuntimeError(
+                "Could not determine app package name. "
+                "Set `app` in pyvel.toml or run `pyvel init <name>`."
+            )
+        app = sorted(candidates)[0]
+
+    src = str(file_data.get("src", "src"))
+    paths = dict(DEFAULT_PATHS)
+    paths.update({k: str(v) for k, v in (file_data.get("paths") or {}).items()})
+
+    bases = file_data.get("bases") or {}
+    error_base = str(bases.get("error", DEFAULT_ERROR_BASE))
+
+    dev_data = file_data.get("dev") or {}
+    module = dev_data.get("module") or f"{app}.main:app"
+    dev = DevSettings(
+        module=str(module),
+        host=str(dev_data.get("host", "0.0.0.0")),
+        port=int(dev_data.get("port", 8000)),
+        reload=bool(dev_data.get("reload", True)),
+    )
+
+    return PyvelSettings(
+        root=root,
+        app=str(app),
+        src=src,
+        paths=paths,
+        error_base=error_base,
+        dev=dev,
+    )
+
+
+def clear_settings_cache() -> None:
+    """Clear the cached settings (useful after init / tests)."""
+    load_settings.cache_clear()
+
+
+def with_overrides(settings: PyvelSettings, **kwargs: Any) -> PyvelSettings:
+    """Return a copy of *settings* with selected fields replaced."""
+    return replace(settings, **kwargs)

pyvel/errors.py

@@ -0,0 +1,17 @@
+"""Shared application error base class."""
+
+
+class AppError(Exception):
+    """Base class for domain/HTTP-mapped application errors."""
+
+    status_code: int = 400
+    code: str = "app_error"
+    message: str = "Application error"
+
+    def __init__(self, message: str | None = None, *, code: str | None = None) -> None:
+        """Optionally override the default message and error code."""
+        if message is not None:
+            self.message = message
+        if code is not None:
+            self.code = code
+        super().__init__(self.message)

pyvel/events.py

@@ -0,0 +1,41 @@
+"""In-process event dispatcher for generated listeners."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections import defaultdict
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+Listener = Callable[[Any], Any | Awaitable[Any]]
+
+
+class EventDispatcher:
+    """Subscribe handlers to event types and dispatch payloads in-process."""
+
+    def __init__(self) -> None:
+        self._listeners: dict[type, list[Listener]] = defaultdict(list)
+
+    def subscribe(self, event_type: type, listener: Listener) -> None:
+        """Register *listener* for *event_type*."""
+        self._listeners[event_type].append(listener)
+
+    async def dispatch(self, event: Any) -> None:
+        """Invoke all listeners registered for the event's type."""
+        for listener in self._listeners.get(type(event), []):
+            result = listener(event)
+            if inspect.isawaitable(result):
+                await result
+
+    def dispatch_sync(self, event: Any) -> None:
+        """Dispatch from sync code by running the async path when needed."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            asyncio.run(self.dispatch(event))
+            return
+        loop.create_task(self.dispatch(event))
+
+
+dispatcher = EventDispatcher()

pyvel/generate.py

@@ -0,0 +1,42 @@
+"""Naming helpers and file writers for generators."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import typer
+
+from pyvel.paths import ensure_package
+
+
+def to_snake(name: str) -> str:
+    """Convert PascalCase / camelCase / kebab-case to snake_case."""
+    cleaned = name.replace("-", "_").replace(" ", "_")
+    cleaned = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", cleaned)
+    cleaned = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", cleaned)
+    return cleaned.lower().strip("_")
+
+
+def to_pascal(name: str) -> str:
+    """Convert a name to PascalCase."""
+    parts = re.split(r"[-_\s]+", name)
+    if len(parts) == 1 and name[:1].isupper() and "_" not in name and "-" not in name:
+        return name[0].upper() + name[1:] if name else name
+    return "".join(part.capitalize() for part in parts if part)
+
+
+def ensure_suffix(pascal: str, suffix: str) -> str:
+    """Append *suffix* when the PascalCase name does not already end with it."""
+    if pascal.endswith(suffix):
+        return pascal
+    return f"{pascal}{suffix}"
+
+
+def write_file(path: Path, content: str, *, force: bool = False) -> Path:
+    """Write *content* to *path*, creating parent packages as needed."""
+    ensure_package(path.parent)
+    if path.exists() and not force:
+        raise typer.BadParameter(f"File already exists: {path} (use --force to overwrite)")
+    path.write_text(content.lstrip("\n"), encoding="utf-8")
+    return path

pyvel/init_cmd.py

@@ -0,0 +1,250 @@
+"""`pyvel init` — scaffold a Laravel-like FastAPI backend project."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import typer
+
+from pyvel.config import DEFAULT_PATHS, clear_settings_cache
+from pyvel.generate import to_snake
+from pyvel.paths import ensure_package
+
+
+_SCAFFOLD_MARKERS = (
+    "pyproject.toml",
+    "pyvel.toml",
+    "src",
+    "tests",
+    "README.md",
+    ".gitignore",
+)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the init command to *app*."""
+
+    @app.command("init")
+    def init(
+        name: str | None = typer.Argument(
+            None,
+            help="Project/app name. Omit to scaffold into the current directory.",
+        ),
+        force: bool = typer.Option(False, "--force", help="Overwrite conflicting scaffold files"),
+        pyvel_path: Path | None = typer.Option(
+            None,
+            "--pyvel-path",
+            help="Local path to pyvel package (adds a uv path source; useful before PyPI publish)",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ) -> None:
+        """Scaffold a Laravel-like FastAPI backend (dual-mode: cwd or new directory)."""
+        cwd = Path.cwd().resolve()
+        if name:
+            app_name = _normalize_app_name(name)
+            target = cwd / app_name
+            if target.exists() and any(target.iterdir()) and not force:
+                raise typer.BadParameter(
+                    f"Directory {target} is not empty (use --force to scaffold anyway)"
+                )
+            target.mkdir(parents=True, exist_ok=True)
+        else:
+            app_name = _normalize_app_name(cwd.name)
+            target = cwd
+            if _cwd_blocked(target) and not force:
+                raise typer.BadParameter(
+                    "Current directory already looks initialized "
+                    "(pyproject.toml / pyvel.toml / src). Use --force to continue."
+                )
+
+        _scaffold(target, app_name, force=force, pyvel_path=pyvel_path)
+        clear_settings_cache()
+        typer.secho(f"Initialized FastAPI app '{app_name}' in {target}", fg=typer.colors.GREEN)
+        _maybe_uv_sync(target)
+        typer.echo(f"Next: cd {target if name else '.'} && uv run dev")
+
+
+def _normalize_app_name(raw: str) -> str:
+    """Normalize a user-given name into a valid Python package identifier."""
+    snake = to_snake(raw.replace(".", "_"))
+    snake = re.sub(r"[^a-z0-9_]", "_", snake)
+    snake = re.sub(r"_+", "_", snake).strip("_")
+    if not snake or snake[0].isdigit():
+        raise typer.BadParameter(f"Invalid app name: {raw!r}")
+    return snake
+
+
+def _cwd_blocked(target: Path) -> bool:
+    """Return True when cwd already has scaffold markers."""
+    return any((target / marker).exists() for marker in _SCAFFOLD_MARKERS)
+
+
+def _scaffold(
+    target: Path,
+    app_name: str,
+    *,
+    force: bool,
+    pyvel_path: Path | None = None,
+) -> None:
+    """Write project files for *app_name* under *target*."""
+    _write(
+        target / "pyproject.toml",
+        _pyproject(app_name, pyvel_path=pyvel_path, target=target),
+        force=force,
+    )
+    _write(target / "pyvel.toml", _pyvel_toml(app_name), force=force)
+    _write(target / "README.md", _readme(app_name), force=force)
+    _write(target / ".gitignore", _gitignore(), force=force)
+
+    app_dir = target / "src" / app_name
+    ensure_package(app_dir)
+    _write(app_dir / "__init__.py", f'"""{app_name} application package."""\n\n__version__ = "0.1.0"\n', force=True)
+    _write(app_dir / "main.py", _main_py(app_name), force=force)
+
+    for key, relative in DEFAULT_PATHS.items():
+        if key == "tests":
+            continue
+        ensure_package(app_dir / relative)
+
+    (target / "tests").mkdir(exist_ok=True)
+    _write(target / "tests" / ".gitkeep", "", force=True)
+
+
+def _write(path: Path, content: str, *, force: bool) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not force and path.stat().st_size > 0:
+        typer.secho(f"Skip existing {path}", fg=typer.colors.YELLOW)
+        return
+    path.write_text(content, encoding="utf-8")
+    typer.echo(f"Created {path}")
+
+
+def _pyproject(app: str, *, pyvel_path: Path | None = None, target: Path | None = None) -> str:
+    sources = ""
+    if pyvel_path is not None and target is not None:
+        rel = Path(os.path.relpath(pyvel_path, target)).as_posix()
+        sources = f'''
+
+[tool.uv.sources]
+pyvel-fastapi = {{ path = "{rel}", editable = true }}
+'''
+    return f'''\
+[project]
+name = "{app}"
+version = "0.1.0"
+description = "{app} FastAPI backend"
+requires-python = ">=3.11"
+dependencies = [
+    "pyvel-fastapi",
+    "fastapi[standard]>=0.115.0",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.scripts]
+dev = "pyvel.app:dev"
+pyvel = "pyvel.app:app"
+artisan = "pyvel.app:app"
+
+[build-system]
+requires = ["uv_build>=0.12.18,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "{app}"
+
+[tool.pyvel]
+app = "{app}"
+{sources}'''
+
+
+def _pyvel_toml(app: str) -> str:
+    return f'''\
+# pyvel project config (all keys optional — omit sections to use defaults)
+
+app = "{app}"
+src = "src"
+
+[dev]
+module = "{app}.main:app"
+host = "0.0.0.0"
+port = 8000
+reload = true
+
+# [paths]
+# errors = "http/exception/errors"
+# handlers = "http/exception/handlers"
+# ...
+
+# [bases]
+# error = "pyvel.errors:AppError"
+'''
+
+
+def _main_py(app: str) -> str:
+    title = app.replace("_", " ").title()
+    return f'''\
+"""{title} FastAPI application."""
+
+from fastapi import FastAPI
+
+from pyvel import register
+
+app = FastAPI(title="{title}")
+register(app)
+
+
+@app.get("/")
+def read_root() -> dict[str, str]:
+    """Health/root endpoint."""
+    return {{"message": "Hello from {app}"}}
+'''
+
+
+def _readme(app: str) -> str:
+    return f"""\
+# {app}
+
+FastAPI backend scaffolded with [pyvel](https://pypi.org/project/pyvel/).
+
+## Commands
+
+```bash
+uv sync
+uv run dev
+uv run pyvel --help
+uv run pyvel make:resource User
+uv run pyvel list:routes
+```
+
+Configure the app in `pyvel.toml`.
+"""
+
+
+def _gitignore() -> str:
+    return """\
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.DS_Store
+"""
+
+
+def _maybe_uv_sync(target: Path) -> None:
+    """Run `uv sync` in *target* when uv is available."""
+    try:
+        subprocess.run(["uv", "sync"], cwd=target, check=False)
+    except FileNotFoundError:
+        typer.secho("uv not found on PATH — skip `uv sync`. Install uv then run it manually.", fg=typer.colors.YELLOW)

pyvel/list_cmd.py

@@ -0,0 +1,55 @@
+"""Inspection commands such as `list:routes`."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Iterator
+
+import typer
+from fastapi.routing import APIRoute, _IncludedRouter
+from starlette.routing import BaseRoute
+
+from pyvel.paths import get_app_name
+
+
+def register(app: typer.Typer) -> None:
+    """Attach inspection commands to *app*."""
+
+    @app.command("list:routes")
+    def list_routes() -> None:
+        """Print registered FastAPI routes for the configured app."""
+        app_name = get_app_name()
+        module = importlib.import_module(f"{app_name}.main")
+        fastapi_app = getattr(module, "app", None)
+        if fastapi_app is None:
+            raise typer.BadParameter(f"No FastAPI `app` found on {app_name}.main")
+
+        rows = list(_collect_routes(fastapi_app.routes))
+        if not rows:
+            typer.echo("No routes registered.")
+            return
+
+        method_width = max(len(method) for method, _, _ in rows)
+        path_width = max(len(path) for _, path, _ in rows)
+        for method, path, name in sorted(rows, key=lambda item: (item[1], item[0])):
+            typer.echo(f"{method:<{method_width}}  {path:<{path_width}}  {name}")
+
+
+def _collect_routes(routes: list[BaseRoute]) -> Iterator[tuple[str, str, str]]:
+    """Yield `(method, path, name)` for API routes, including nested routers."""
+    for route in routes:
+        if isinstance(route, APIRoute):
+            methods = sorted(route.methods or [])
+            for method in methods:
+                if method == "HEAD":
+                    continue
+                yield method, route.path, route.name or ""
+            continue
+
+        if isinstance(route, _IncludedRouter):
+            yield from _collect_routes(route.original_router.routes)
+            continue
+
+        nested = getattr(route, "routes", None)
+        if nested:
+            yield from _collect_routes(list(nested))