flowlab 0.1.0__py3-none-any.whl

flowlab/__init__.py

@@ -0,0 +1,109 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Cookie,
+    Depends,
+    File,
+    Form,
+    Header,
+    HTTPException,
+    Path,
+    Query,
+    Request,
+    Response,
+    Security,
+    UploadFile,
+    WebSocket,
+    WebSocketDisconnect,
+    status,
+)
+from fastmcp.dependencies import Depends as MCPDepends
+
+from flowlab._cache import Cache, get_cache
+from flowlab._database import DB, INTEGRITY_ERRORS, get_db
+from flowlab._exceptions import (
+    AuthNotEnabled,
+    FlowLabAlreadyInitialized,
+    FlowLabError,
+    FlowLabNotInitialized,
+    NotConnected,
+    SchemaMismatch,
+)
+from flowlab._flowlab import FlowLab
+from flowlab._module import Module
+from flowlab._queue import get_queue
+from flowlab._routing import Command, CommandRouter, MCPRouter
+from flowlab._settings import (
+    AppEnv,
+    AuthSettings,
+    CacheDriver,
+    CacheSettings,
+    DatabaseSettings,
+    DBDriver,
+    FastAPISettings,
+    FastMCPSettings,
+    QueueDriver,
+    QueueSettings,
+    TyperSettings,
+)
+from flowlab._state import get_app
+
+try:
+    __version__ = version("flowlab")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without metadata
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DB",
+    "INTEGRITY_ERRORS",
+    "APIRouter",
+    "AppEnv",
+    "AuthNotEnabled",
+    "AuthSettings",
+    "BackgroundTasks",
+    "Body",
+    "Cache",
+    "CacheDriver",
+    "CacheSettings",
+    "Command",
+    "CommandRouter",
+    "Cookie",
+    "DBDriver",
+    "DatabaseSettings",
+    "Depends",
+    "FastAPISettings",
+    "FastMCPSettings",
+    "File",
+    "FlowLab",
+    "FlowLabAlreadyInitialized",
+    "FlowLabError",
+    "FlowLabNotInitialized",
+    "Form",
+    "HTTPException",
+    "Header",
+    "MCPDepends",
+    "MCPRouter",
+    "Module",
+    "NotConnected",
+    "Path",
+    "Query",
+    "QueueDriver",
+    "QueueSettings",
+    "Request",
+    "Response",
+    "SchemaMismatch",
+    "Security",
+    "TyperSettings",
+    "UploadFile",
+    "WebSocket",
+    "WebSocketDisconnect",
+    "__version__",
+    "get_app",
+    "get_cache",
+    "get_db",
+    "get_queue",
+    "status",
+]

flowlab/__main__.py

@@ -0,0 +1,3 @@
+from flowlab._console import main
+
+main()

flowlab/_cache.py

@@ -0,0 +1,42 @@
+from collections.abc import Generator
+from typing import Annotated
+
+from fastapi import Depends
+
+from flowlab._settings import CacheDriver, CacheSettings
+from flowlab._state import get_app
+from flowlab.modules.cache import Cache as CacheStore
+from flowlab.modules.db.database import DB as Database
+
+
+def connect_cache_store(settings: CacheSettings, db: Database) -> CacheStore:
+    driver = settings.cache_driver
+    options = settings.cache_options()
+
+    if driver is CacheDriver.MEMORY:
+        return CacheStore.shared_memory()
+
+    if driver is CacheDriver.DATABASE:
+        return CacheStore.connect_database(db, **options)
+
+    if driver is CacheDriver.REDIS:
+        return CacheStore.connect_redis(**options)
+
+    if driver is CacheDriver.VALKEY:
+        return CacheStore.connect_valkey(**options)
+
+    if driver is CacheDriver.MEMCACHED:
+        return CacheStore.connect_memcached(**options)
+
+    raise ValueError(f"Unsupported CACHE_DRIVER: {driver!r}")
+
+
+def get_cache() -> CacheStore:
+    return get_app().cache
+
+
+def connect_cache() -> Generator[CacheStore, None, None]:
+    yield get_cache()
+
+
+Cache = Annotated[CacheStore, Depends(connect_cache)]

flowlab/_commands.py

@@ -0,0 +1,101 @@
+import os
+import subprocess
+import sys
+from typing import Annotated
+
+import typer
+import uvicorn
+
+from flowlab._routing import CommandRouter
+from flowlab._state import get_app
+from flowlab.modules.migrator import drop_all_tables
+from flowlab.modules.migrator._schema import scaffold
+
+RELOAD_TARGET_ENV = "FLOWLAB_RELOAD_TARGET"
+
+commands = CommandRouter()
+
+
+@commands.command("server:start", lifespan=False)
+def server_start(
+    host: Annotated[str | None, typer.Option(help="Interface to bind. Defaults to SERVER_HOST.")] = None,
+    port: Annotated[int | None, typer.Option(help="Port to bind. Defaults to SERVER_PORT.")] = None,
+    reload: Annotated[
+        bool | None, typer.Option(help="Restart on code changes. Defaults to on when APP_ENV=local.")
+    ] = None,
+) -> None:
+    app = get_app()
+    settings = app.fastapi_settings
+    host = settings.server_host if host is None else host
+    port = settings.server_port if port is None else port
+    reload = settings.is_local if reload is None else reload
+
+    if not reload:
+        uvicorn.run(app, host=host, port=port)
+        return
+
+    os.environ[RELOAD_TARGET_ENV] = app._import_string()
+
+    uvicorn.run(
+        "flowlab._console:reload_target",
+        factory=True,
+        host=host,
+        port=port,
+        reload=True,
+        app_dir=str(app.project_dir),
+        reload_dirs=[str(app.project_dir)],
+    )
+
+
+@commands.command("migrations:init")
+def migrations_init() -> None:
+    _ = get_app().migrator
+    typer.echo("Migrations table is ready.")
+
+
+@commands.command("migrations:up")
+def migrations_up() -> None:
+    get_app().migrator.up()
+    typer.echo("Migrated.")
+
+
+@commands.command("migrations:down")
+def migrations_down() -> None:
+    get_app().migrator.down()
+    typer.echo("Rolled back the last batch.")
+
+
+@commands.command("migrations:fresh")
+def migrations_fresh(
+    force: Annotated[bool, typer.Option("--force", help="Required when APP_ENV is production.")] = False,
+) -> None:
+    app = get_app()
+
+    if app.fastapi_settings.is_production and not force:
+        typer.echo("Refusing to drop every table in production without --force.", err=True)
+        raise typer.Exit(1)
+
+    for table in drop_all_tables(app.db):
+        typer.echo(f"Dropped {table}")
+
+    app.migrator.up()
+    typer.echo("Migrated.")
+
+
+@commands.command("migrations:make")
+def migrations_make(
+    name: Annotated[str, typer.Argument(help="snake_case description, e.g. create_posts_table")],
+) -> None:
+    app = get_app()
+    typer.echo(scaffold(app.db, app.migrations_dir, name))
+
+
+@commands.command(
+    "test",
+    lifespan=False,
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run_tests(ctx: typer.Context) -> None:
+    result = subprocess.run([sys.executable, "-m", "pytest", *ctx.args], cwd=get_app().project_dir, check=False)
+
+    raise typer.Exit(result.returncode)

flowlab/_console.py

@@ -0,0 +1,37 @@
+import importlib
+import os
+import sys
+
+from flowlab._commands import RELOAD_TARGET_ENV
+from flowlab._flowlab import FlowLab
+
+DEFAULT_APP = "main:app"
+
+
+def load_app(target: str) -> FlowLab:
+    module_name, _, attribute = target.partition(":")
+    sys.path.insert(0, os.getcwd())
+
+    app = getattr(importlib.import_module(module_name), attribute or "app")
+
+    if not isinstance(app, FlowLab):
+        raise SystemExit(f"{target} is not a FlowLab application")
+
+    return app
+
+
+def reload_target() -> FlowLab:
+    if FlowLab.initialized():
+        return FlowLab.instance()
+
+    return load_app(os.environ[RELOAD_TARGET_ENV])
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    target = os.environ.get("FLOWLAB_APP", DEFAULT_APP)
+
+    if len(args) >= 2 and args[0] == "--app":
+        target, args = args[1], args[2:]
+
+    load_app(target).run(args)

flowlab/_database.py

@@ -0,0 +1,64 @@
+import contextlib
+import importlib
+import sqlite3
+from collections.abc import Generator
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import Depends
+
+from flowlab._settings import DatabaseSettings, DBDriver
+from flowlab._state import get_app
+from flowlab.modules.db.database import DB as Database
+
+DB_API_DRIVER_MODULES = ("psycopg", "mysql.connector")
+
+ASYNCPG_INTEGRITY_ERROR = ("asyncpg.exceptions", "IntegrityConstraintViolationError")
+
+
+def _integrity_errors() -> tuple[type[BaseException], ...]:
+    errors: list[type[BaseException]] = [sqlite3.IntegrityError]
+
+    for module_name in DB_API_DRIVER_MODULES:
+        with contextlib.suppress(ImportError):
+            errors.append(importlib.import_module(module_name).IntegrityError)
+
+    module_name, attribute = ASYNCPG_INTEGRITY_ERROR
+
+    with contextlib.suppress(ImportError, AttributeError):
+        errors.append(getattr(importlib.import_module(module_name), attribute))
+
+    return tuple(errors)
+
+
+INTEGRITY_ERRORS = _integrity_errors()
+
+
+def connect_database(settings: DatabaseSettings, project_dir: Path) -> Database:
+    driver = settings.db_driver
+    options = settings.db_options(project_dir)
+
+    if driver is DBDriver.SQLITE:
+        return Database.connect_sqlite(**options)
+
+    if driver is DBDriver.POSTGRESQL:
+        return Database.connect_postgresql(**options)
+
+    if driver is DBDriver.MYSQL:
+        return Database.connect_mysql(**options)
+
+    if driver is DBDriver.MARIADB:
+        return Database.connect_mariadb(**options)
+
+    raise ValueError(f"Unsupported DB_DRIVER: {driver!r}")
+
+
+def get_db() -> Database:
+    return get_app().db
+
+
+def connect() -> Generator[Database, None, None]:
+    yield get_db()
+
+
+DB = Annotated[Database, Depends(connect)]

flowlab/_exceptions.py

@@ -0,0 +1,31 @@
+class FlowLabError(RuntimeError):
+    pass
+
+
+class FlowLabNotInitialized(FlowLabError):
+    def __init__(self) -> None:
+        super().__init__("No FlowLab application has been initialized; create one with FlowLab(...) first")
+
+
+class FlowLabAlreadyInitialized(FlowLabError):
+    def __init__(self) -> None:
+        super().__init__("A FlowLab application already exists; use FlowLab.instance() to reach it")
+
+
+class NotConnected(FlowLabError):
+    def __init__(self, resource: str) -> None:
+        super().__init__(f"The {resource} is not connected; use it inside app.lifespan() or a running app")
+
+
+class AuthNotEnabled(FlowLabError):
+    def __init__(self) -> None:
+        super().__init__("Auth is not enabled; pass auth_settings=AuthSettings() to FlowLab(...)")
+
+
+class SchemaMismatch(FlowLabError):
+    def __init__(self, module: str, missing: list[str]) -> None:
+        self.missing = missing
+        super().__init__(
+            f"The {module} module needs {', '.join(missing)}. "
+            f"Run `{module}:install` to add its migrations, then `migrations:up`"
+        )