coasti-planner 0.1.0__tar.gz

coasti_planner-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+dist/
+build/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Node (frontend)
+node_modules/
+
+# Nix / direnv
+.direnv/
+
+# OS / editor
+.DS_Store
+
+# Module Federation
+@mf-types
+.mf

coasti_planner-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

coasti_planner-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: coasti-planner
+Version: 0.1.0
+Summary: Backend service for the Coasti Planning Framework.
+Author-email: "Sebastian B. Mohr" <sebastian@mohrenclan.de>, "F. Paul Spitzner" <paul.spitzner@linkfish.eu>
+Requires-Python: >=3.13
+Requires-Dist: eyconf[pydantic]>=0.8.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: typer>=0.27.3
+Requires-Dist: uvicorn[standard]>=0.34.0
+Description-Content-Type: text/markdown
+
+# Coasti Planning Framework — Backend
+
+The backend is a Python 3.13 FastAPI application managed with
+[uv](https://docs.astral.sh/uv/). It serves the framework and content-package
+assets from local Vite build directories.
+
+## Setup
+
+Run this command from the repository root:
+
+```bash
+uv sync --directory backend --locked
+```
+
+The repository root also provides a Nix/direnv development shell that installs
+the required tools automatically. See the root [README](../README.md).
+
+## Build the frontend distributions
+
+The backend does not build frontend assets itself. Build the framework and the
+example extension before running the backend in local distribution mode.
+
+### Framework distribution
+
+Install the frontend workspace dependencies and build the planner framework:
+
+```bash
+pnpm --dir frontend install --frozen-lockfile
+pnpm --dir frontend build
+```
+
+This creates the framework distribution in `frontend/planner/dist`.
+
+### Example extension distribution
+
+Install the extension dependencies and build the example content package:
+
+```bash
+pnpm --dir cp_example_extension install --frozen-lockfile
+pnpm --dir cp_example_extension build
+```
+
+This creates the extension distribution in `cp_example_extension/dist`. The
+build includes the generated `manifest.json` and Module Federation entry point.
+
+## Configuration
+
+The server accepts a `server` command and an optional YAML configuration path.
+The legacy form with only the configuration path remains supported.
+
+The example configuration is available at
+[config.example.yml](../cp_example_extension/config.example.yml):
+
+```yaml
+backend:
+  host: 127.0.0.1
+  port: 8000
+framework:
+  dist_folder: ../frontend/planner/dist
+extension:
+  dist_folder: ./dist
+```
+
+Configuration is loaded by [EYConf](https://eyconf.readthedocs.io/) using its
+Pydantic validation backend. The configuration is represented by three pairs of
+schema/runtime types in `coasti_planner.config`:
+
+- `BackendConfigSchema` / `BackendConfig` define the listening host and port.
+- `AssetSourceSchema` / `AssetSource` define a local distribution or remote
+  development server.
+- `ServerConfigSchema` / `ServerConfig` combine the backend, framework, and
+  extension settings.
+
+Each asset source defines a local `dist_folder`. Relative paths are resolved
+relative to the configuration file, not relative to the current working
+directory.
+
+## Run the backend
+
+From the repository root, after building both distributions:
+
+```bash
+uv run --directory backend coasti-planner ../cp_example_extension/config.example.yml
+```
+
+### Run the full stack in development mode
+
+Development mode does not require either frontend distribution directory. Run
+the backend from the backend project directory:
+
+```bash
+cd backend
+uv run backend server --dev
+```
+
+The backend uses Uvicorn autoreload and the example configuration by default.
+Run the Vite development servers in separate terminals:
+
+```bash
+pnpm --dir frontend dev
+pnpm --dir cp_example_extension dev
+```
+
+The frontend development server proxies API requests to the autoreloading
+backend, while the frontend and extension servers reload their own source files.
+
+## HTTP endpoints
+
+- `/` serves the framework `index.html` and its root-relative assets.
+- `/api_v1/framework/{path}` serves framework distribution files.
+- `/api_v1/extension/{path}` serves extension distribution files.
+- `/api_v1/extension/manifest.json` serves the extension's generated manifest.
+
+The manifest is read from the extension distribution. It is not duplicated in
+the backend.

coasti_planner-0.1.0/README.md

@@ -0,0 +1,115 @@
+# Coasti Planning Framework — Backend
+
+The backend is a Python 3.13 FastAPI application managed with
+[uv](https://docs.astral.sh/uv/). It serves the framework and content-package
+assets from local Vite build directories.
+
+## Setup
+
+Run this command from the repository root:
+
+```bash
+uv sync --directory backend --locked
+```
+
+The repository root also provides a Nix/direnv development shell that installs
+the required tools automatically. See the root [README](../README.md).
+
+## Build the frontend distributions
+
+The backend does not build frontend assets itself. Build the framework and the
+example extension before running the backend in local distribution mode.
+
+### Framework distribution
+
+Install the frontend workspace dependencies and build the planner framework:
+
+```bash
+pnpm --dir frontend install --frozen-lockfile
+pnpm --dir frontend build
+```
+
+This creates the framework distribution in `frontend/planner/dist`.
+
+### Example extension distribution
+
+Install the extension dependencies and build the example content package:
+
+```bash
+pnpm --dir cp_example_extension install --frozen-lockfile
+pnpm --dir cp_example_extension build
+```
+
+This creates the extension distribution in `cp_example_extension/dist`. The
+build includes the generated `manifest.json` and Module Federation entry point.
+
+## Configuration
+
+The server accepts a `server` command and an optional YAML configuration path.
+The legacy form with only the configuration path remains supported.
+
+The example configuration is available at
+[config.example.yml](../cp_example_extension/config.example.yml):
+
+```yaml
+backend:
+  host: 127.0.0.1
+  port: 8000
+framework:
+  dist_folder: ../frontend/planner/dist
+extension:
+  dist_folder: ./dist
+```
+
+Configuration is loaded by [EYConf](https://eyconf.readthedocs.io/) using its
+Pydantic validation backend. The configuration is represented by three pairs of
+schema/runtime types in `coasti_planner.config`:
+
+- `BackendConfigSchema` / `BackendConfig` define the listening host and port.
+- `AssetSourceSchema` / `AssetSource` define a local distribution or remote
+  development server.
+- `ServerConfigSchema` / `ServerConfig` combine the backend, framework, and
+  extension settings.
+
+Each asset source defines a local `dist_folder`. Relative paths are resolved
+relative to the configuration file, not relative to the current working
+directory.
+
+## Run the backend
+
+From the repository root, after building both distributions:
+
+```bash
+uv run --directory backend coasti-planner ../cp_example_extension/config.example.yml
+```
+
+### Run the full stack in development mode
+
+Development mode does not require either frontend distribution directory. Run
+the backend from the backend project directory:
+
+```bash
+cd backend
+uv run backend server --dev
+```
+
+The backend uses Uvicorn autoreload and the example configuration by default.
+Run the Vite development servers in separate terminals:
+
+```bash
+pnpm --dir frontend dev
+pnpm --dir cp_example_extension dev
+```
+
+The frontend development server proxies API requests to the autoreloading
+backend, while the frontend and extension servers reload their own source files.
+
+## HTTP endpoints
+
+- `/` serves the framework `index.html` and its root-relative assets.
+- `/api_v1/framework/{path}` serves framework distribution files.
+- `/api_v1/extension/{path}` serves extension distribution files.
+- `/api_v1/extension/manifest.json` serves the extension's generated manifest.
+
+The manifest is read from the extension distribution. It is not duplicated in
+the backend.

coasti_planner-0.1.0/pyproject.toml

@@ -0,0 +1,128 @@
+[project]
+name = "coasti-planner"
+version = "0.1.0"
+description = "Backend service for the Coasti Planning Framework."
+readme = "README.md"
+authors = [
+    { name = "Sebastian B. Mohr", email = "sebastian@mohrenclan.de" },
+    { name = "F. Paul Spitzner", email = "paul.spitzner@linkfish.eu" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "eyconf[pydantic]>=0.8.0",
+    "fastapi>=0.115.0",
+    "ruamel-yaml>=0.19.1",
+    "sqlalchemy>=2.0.0",
+    "typer>=0.27.3",
+    "uvicorn[standard]>=0.34.0",
+]
+
+[project.scripts]
+coasti-planner = "coasti_planner.__main__:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coasti_planner"]
+
+[dependency-groups]
+dev = [
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "typed" },
+    "pre-commit>=4.5.1",
+]
+lint = [
+    "ruff"
+]
+typed = [
+    "mypy>=1.19.1",
+]
+test = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.ruff]
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+future-annotations = true
+select = [
+    "A",   # flake8-builtins
+    "ANN", # flake8-annotations
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "I",   # isort
+    "ISC", # flake8-implicit-str-concat
+    "N",   # pep8-naming
+    "PIE", # flake8-pie
+    "PT",  # flake8-pytest-style
+    "RUF", # ruff
+    "RET", # flake8-return
+    "SIM", # flake8-simplify
+    "UP",  # pyupgrade
+    "TC",  # flake8-type-checking
+    "PTH", # Use pathlib instead of os.path
+    "D",   # pydocstyle
+    "W",   # pycodestyle
+]
+ignore = [
+    # Docstrings are not mandatory for public functions.
+    "D10",
+    "D202",
+    "TC006", # no need to quote 'cast's since we use 'from __future__ import annotations'
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.flake8-type-checking]
+# FastAPI route decorators evaluate annotations at import time, so dependency
+# imports used in endpoints must remain runtime imports.
+runtime-evaluated-decorators = [
+    "fastapi.APIRouter.delete",
+    "fastapi.APIRouter.get",
+    "fastapi.APIRouter.head",
+    "fastapi.APIRouter.options",
+    "fastapi.APIRouter.patch",
+    "fastapi.APIRouter.post",
+    "fastapi.APIRouter.put",
+    "fastapi.APIRouter.trace",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ANN", # full annotations on tests add noise; mypy still checks them
+    "D",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["coasti_planner"]
+
+[tool.mypy]
+files = ["src", "tests"]
+python_version = "3.13"
+mypy_path = ["src"]
+warn_unreachable = true
+strict = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+allow_redefinition = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"
+
+[tool.coverage.run]
+source = ["coasti_planner"]
+omit = ["*/__main__.py"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true

coasti_planner-0.1.0/src/coasti_planner/__main__.py

@@ -0,0 +1,54 @@
+"""Coasti Planner backend package and CLI entry point."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import uvicorn
+
+from coasti_planner.config import Config
+
+app = typer.Typer(help="Run the Coasti Planner backend.")
+
+
+@app.command()
+def server(
+    config_file: Annotated[
+        Path | None,
+        typer.Argument(help="Path to the YAML config file"),
+    ] = None,
+    dev: Annotated[
+        bool,
+        typer.Option(
+            help="Run with Uvicorn autoreload and without distribution assets",
+        ),
+    ] = False,
+) -> None:
+    """Start the backend server."""
+    config_file = config_file or Path.cwd() / "config.yml"
+    if not config_file.is_file():
+        raise FileNotFoundError(f"Configuration file does not exist: {config_file}")
+
+    # We just validate the config here to raise early
+    resolved_config_file = config_file.resolve()
+
+    # setting the env var propagates the config file to the server init in server.py
+    os.environ["EYCONF_CONFIG_FILE"] = str(resolved_config_file)
+    config = Config()
+
+    if dev:
+        print("Running uvicorn in dev mode with live reloading")
+
+    uvicorn.run(
+        "coasti_planner.server:app",
+        host=config.backend.host,
+        port=config.backend.port,
+        reload=dev,
+    )
+
+
+if __name__ == "__main__":
+    app()

coasti_planner-0.1.0/src/coasti_planner/config.py

@@ -0,0 +1,80 @@
+"""Runtime configuration schema and loading for the backend."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from eyconf import EYConf
+from eyconf.validation.backends.pydantic import PydanticValidator
+from sqlalchemy.engine import make_url
+
+
+@dataclass(frozen=True)
+class BackendConfig:
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+
+@dataclass
+class DatabaseConfig:
+    connection_string: str = "sqlite:///:memory:"
+
+
+@dataclass
+class AssetSource:
+    """Configuration for a local build or a running development server."""
+
+    dist_folder: Path = field(
+        default_factory=lambda: Path(__file__).parent.parent / "dist"
+    )
+    sql_folder: Path = field(default_factory=lambda: Path("sql"))
+
+
+@dataclass
+class ServerConfigSchema:
+    """Configuration for the framework and content-package assets."""
+
+    backend: BackendConfig = field(default_factory=BackendConfig)
+    database: DatabaseConfig = field(default_factory=DatabaseConfig)
+    framework: AssetSource = field(default_factory=AssetSource)
+    extension: AssetSource = field(default_factory=AssetSource)
+
+
+class Config(EYConf[ServerConfigSchema]):
+    """Configuration for the Coasti Planner backend."""
+
+    def __init__(self) -> None:
+        super().__init__(ServerConfigSchema, validator=PydanticValidator())
+
+        # absolute paths for dist bundles
+        for source in (self.data.framework, self.data.extension):
+            if not source.dist_folder.is_absolute():
+                source.dist_folder = (
+                    self.get_file().parent / source.dist_folder
+                ).resolve()
+            if not source.sql_folder.is_absolute():
+                source.sql_folder = (
+                    self.get_file().parent / source.sql_folder
+                ).resolve()
+
+        # abs path for sqlite database
+        database_url = make_url(self.data.database.connection_string)
+        if database_url.drivername == "sqlite" and database_url.database:
+            database_path = Path(database_url.database)
+            if not database_path.is_absolute() and database_path.name != ":memory:":
+                self.data.database.connection_string = str(
+                    database_url.set(
+                        database=str(self.get_file().parent / database_path)
+                    )
+                )
+
+    @property
+    def framework(self) -> AssetSource:
+        return self.data.framework
+
+    @property
+    def extension(self) -> AssetSource:
+        return self.data.extension
+
+    @property
+    def backend(self) -> BackendConfig:
+        return self.data.backend

coasti_planner-0.1.0/src/coasti_planner/database.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import create_engine, text
+
+
+class Database:
+    """Execute SQL against the configured database."""
+
+    def __init__(self, connection_string: str) -> None:
+        self._engine = create_engine(connection_string)
+
+    def execute_query(
+        self,
+        query: str,
+        parameters: dict[str, Any] | None = None,
+    ) -> tuple[list[str], list[dict[str, Any]]]:
+        with self._engine.connect() as connection:
+            result = connection.execute(text(query), parameters or {})
+            columns = list(result.keys())
+            rows = [dict(row) for row in result.mappings()]
+        return columns, rows

coasti_planner-0.1.0/src/coasti_planner/dependencies.py

@@ -0,0 +1,27 @@
+"""Dependencies shared by the FastAPI route handlers."""
+
+from __future__ import annotations
+
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+
+from coasti_planner.config import Config
+from coasti_planner.database import Database
+from coasti_planner.sql_io import SQLIO
+
+
+def get_config(request: Request) -> Config:
+    """Return the configuration stored on the application state."""
+    return cast("Config", request.app.state.config)
+
+
+def get_sqlio(request: Request, config: ConfigDep) -> SQLIO:
+    """Load and return the SQL interaction layer."""
+
+    database = Database(config.data.database.connection_string)
+    return SQLIO(config.data.extension.sql_folder, database)
+
+
+ConfigDep = Annotated[Config, Depends(get_config)]
+SqlioDep = Annotated[SQLIO, Depends(get_sqlio)]

coasti_planner-0.1.0/src/coasti_planner/exceptions.py

@@ -0,0 +1,25 @@
+"""Serialization of backend exceptions for the frontend error format."""
+
+from __future__ import annotations
+
+import traceback
+
+from pydantic import BaseModel
+
+
+class SerializedException(BaseModel):
+    type: str
+    message: str
+    description: str | None
+    trace: str | None
+
+
+def to_serialized_exception(exception: Exception) -> SerializedException:
+    """Convert a backend exception into the frontend error format."""
+    trace = "".join(traceback.format_exception(exception))
+    return SerializedException(
+        type=type(exception).__name__,
+        message=str(exception),
+        description=exception.__doc__,
+        trace=trace,
+    )