aggregate_api 1.0.0__py3-none-any.whl

aggregate_api/__init__.py

@@ -0,0 +1,41 @@
+"""FastAPI service for the :mod:`aggregate` library.
+
+This package stands up an HTTP/JSON wrapper around ``build()``,
+the live ``Aggregate`` / ``Portfolio`` objects, plotting, pricing,
+and DecL helpers (completions, lexing, grammar).
+
+Quickstart
+----------
+
+::
+
+    pip install aggregate_api
+    aggregate-api --port 8001
+
+Then ``POST http://127.0.0.1:8001/v1/objects`` with body
+``{"decl": "agg Dice dfreq [3] dsev [1:6]"}`` to build and cache an
+object, and follow up with ``GET /v1/objects/{id}/info`` etc.
+
+Public surface
+--------------
+
+``create_app()`` returns a configured :class:`fastapi.FastAPI`
+instance. The ``aggregate-api`` console script launches it under
+uvicorn. Tests build their own ``TestClient`` against
+``create_app()``.
+
+Note for Flask users
+--------------------
+
+FastAPI uses an *application factory* (``create_app``) plus an ASGI
+server (uvicorn) instead of Flask's ``app = Flask(__name__)`` + WSGI.
+Routes are grouped on ``APIRouter`` objects (analogous to Flask
+``Blueprint``) and mounted onto the app in :func:`app.create_app`.
+Request bodies are *validated* by Pydantic models (one model per
+endpoint) rather than read out of ``request.json``; the model is a
+function parameter and FastAPI deserializes for you.
+"""
+
+from .app import create_app
+
+__all__ = ["create_app"]

aggregate_api/__main__.py

@@ -0,0 +1,154 @@
+"""Entry point for ``python -m aggregate_api`` and ``aggregate-api``.
+
+This is the bootstrap that turns the :func:`create_app` factory
+into a running uvicorn process. CLI flags (``--host``, ``--port``,
+``--reload``, ``--library``, ``--headless``) override the env-var-driven
+config; with no flags the server picks up everything from ``AGGAPI_*``.
+
+``--library`` points the whole process at an alternate ``.agg``
+instead of ``aggregate``'s shipped ``library.agg``: the Examples
+dropdown, every build and the ``.agg`` download all read it. A short
+library is how you get a list to review against.
+
+``--headless`` drops the web app and serves the api alone, for a deploy
+whose front end is somebody else's.
+
+Flask users
+-----------
+
+Equivalent to ``flask run`` -- but with the production server
+(uvicorn) baked in. There's no equivalent of Flask's dev/prod
+switch; uvicorn is fast enough to be both, and ``--reload``
+gives you the dev-mode file-watching behavior.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def resolve_library(raw: str) -> str:
+    """Validate a ``--library`` path and return it absolute.
+
+    Parameters
+    ----------
+    raw : str
+        The path as typed.
+
+    Returns
+    -------
+    str
+        The resolved absolute path.
+
+    Raises
+    ------
+    SystemExit
+        If the path is not a readable file.
+
+    Notes
+    -----
+    Deliberately stricter than the environment variable it feeds.
+    ``library.py`` warns and falls back to the shipped library when
+    ``AGGAPI_LIBRARY`` names a missing file, which is right for a stale
+    setting on a server. It is wrong for a flag typed on purpose: falling back to
+    the full library is the exact outcome someone passing ``--library`` is trying
+    to avoid, and a warning scrolling past in a server log is not a refusal. So
+    this exits, naming the path it could not read.
+
+    Absolute because the api resolves the library through an ``Underwriter``
+    pointed at the file's directory, and a relative path would be read against
+    whatever the working directory happens to be by then.
+    """
+    path = Path(raw).expanduser()
+    try:
+        resolved = path.resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise SystemExit(f"aggregate-api: --library: no such file: {path}") from None
+    if not resolved.is_file():
+        raise SystemExit(f"aggregate-api: --library: not a file: {resolved}")
+    return str(resolved)
+
+
+def main() -> None:
+    """Parse CLI flags and launch uvicorn."""
+    parser = argparse.ArgumentParser(
+        prog="aggregate-api",
+        description="Launch the aggregate api (FastAPI + uvicorn).",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help="Bind address (defaults to AGGAPI_HOST, then 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="TCP port (defaults to AGGAPI_PORT, then 8000).",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Auto-reload on source changes (dev only -- prohibits "
+             "multi-worker mode and adds a watchgod thread).",
+    )
+    parser.add_argument(
+        "--library",
+        default=None,
+        metavar="PATH",
+        help="Read the recipe base from this .agg file instead of "
+             "aggregate's shipped library.agg: the Examples menu, every build "
+             "and the .agg download. A short library makes review quicker. "
+             "Same as AGGAPI_LIBRARY, but it fails rather than falling back "
+             "when the path is wrong.",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Do not serve the web app. Everything under /v1 stays, as do "
+             "/docs and /openapi.json; only / stops answering. For a deploy "
+             "whose front end is somebody else's, which also wants "
+             "AGGAPI_CORS_ORIGINS. Same as AGGAPI_SERVE_SPA=0.",
+    )
+    args = parser.parse_args()
+
+    # Set the environment, not the Settings object. `--reload` builds the app in
+    # a *child* process, which inherits os.environ and would never see a value
+    # poked into this process's cached Settings. It also has to happen before the
+    # first `get_settings()` below, which caches.
+    if args.library is not None:
+        os.environ["AGGAPI_LIBRARY"] = resolve_library(args.library)
+    if args.headless:
+        os.environ["AGGAPI_SERVE_SPA"] = "0"
+
+    # Import inside ``main`` so ``aggregate-api --help`` doesn't pay
+    # the cost of loading FastAPI / uvicorn / aggregate.
+    import uvicorn
+
+    from .config import get_settings
+
+    settings = get_settings()
+    if args.library is not None:
+        print(f"library: {settings.library}", file=sys.stderr)
+    if not settings.serve_spa:
+        print("headless: serving /v1, /docs and /openapi.json; / is not served",
+              file=sys.stderr)
+    # The ``factory=True`` flag tells uvicorn that the target is a
+    # *callable* returning an app rather than an app instance --
+    # so we hand it ``aggregate_api.app:create_app`` and it calls
+    # the factory itself. This plays nicely with --reload: the
+    # factory re-runs on each worker restart, picking up code edits.
+    uvicorn.run(
+        "aggregate_api.app:create_app",
+        factory=True,
+        host=args.host or settings.host,
+        port=args.port or settings.port,
+        reload=args.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

aggregate_api/app.py

@@ -0,0 +1,206 @@
+"""FastAPI application factory.
+
+``create_app()`` is the single entry point: it builds a fresh
+:class:`fastapi.FastAPI`, installs CORS if configured, mounts the
+``v1`` routers, and -- if the Plan D web bundle is present --
+serves it as static files at ``/``.
+
+Flask users
+-----------
+
+The factory pattern (``create_app``) lets uvicorn launch the app
+lazily (one app per worker) and lets tests build a fresh instance
+per test if they want. The Flask-equivalent is the standard
+"application factory" used by larger Flask apps.
+
+Routing model
+-------------
+
+Each ``routes/*.py`` module defines an :class:`APIRouter`
+(``router`` global). The factory mounts all of them under
+``/v1``. The OpenAPI schema (``/openapi.json``) and the
+Swagger UI (``/docs``) are added by FastAPI automatically.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+from aggregate import plugins as agg_plugins
+from fastapi import FastAPI
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from . import resources, status
+from .config import Settings, get_settings
+from .cors import install_cors
+from .library import get_underwriter
+from .routes import decl as decl_routes
+from .routes import examples as examples_routes
+from .routes import meta as meta_routes
+from .routes import objects as objects_routes
+from .routes import status as status_routes
+
+logger = logging.getLogger(__name__)
+
+
+def _load_plugins(settings: Settings) -> None:
+    """Run third-party ``aggregate.plugins`` registrations, once per process.
+
+    Parameters
+    ----------
+    settings : Settings
+        Read for ``plugins_enabled`` and ``plugins_allow``.
+
+    Notes
+    -----
+    The library does not auto-load on import, by design: ``build()`` has to be
+    reproducible, so a notebook's answers must not depend on what happens to be
+    installed. The host decides, and a server is a deployment that may declare
+    what it trusts, which is why this is here and behind a setting.
+
+    :func:`aggregate.plugins.load` is idempotent, so the many apps a test run
+    builds pay for discovery once. It never raises: a plugin whose import or
+    ``register()`` fails is recorded on its own :class:`~aggregate.plugins.LoadedPlugin`
+    and skipped, and one broken experiment must not take the server down. The
+    failure is logged here, at WARNING, **and** reported on ``GET /v1/meta``,
+    because a plugin that silently did not load is otherwise debugged by
+    wondering why a tab is empty.
+    """
+    if not settings.plugins_enabled:
+        return
+    loaded = agg_plugins.load(allow=settings.plugins_allow)
+    for plugin in loaded:
+        if plugin.ok:
+            continue
+        logger.warning("plugin %r failed to load and was skipped: %s",
+                       plugin.name, plugin.error)
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Build the FastAPI app.
+
+    Parameters
+    ----------
+    settings : Settings | None
+        Optional pre-built settings object. ``None`` means "read
+        from environment via :func:`get_settings`" -- the normal
+        path. Tests can inject a custom ``Settings`` to bypass
+        env-var setup.
+
+    Returns
+    -------
+    FastAPI
+        Configured app, routers mounted, ready for uvicorn.
+    """
+    if settings is None:
+        # Force a fresh read so config-affecting monkeypatches in
+        # tests are honored. Cache the result so subsequent
+        # ``Depends(get_settings)`` calls return the same object.
+        get_settings.cache_clear()
+        settings = get_settings()
+    # Drop cached cache+audit singletons -- the next request
+    # rebuilds them against the (possibly just-changed) config.
+    objects_routes.reset_singletons()
+    # And the underwriter, for the same reason: which library it reads is a
+    # setting, and a test that just changed that setting would otherwise get the
+    # base built for the previous case.
+    get_underwriter.cache_clear()
+    # Process-lifetime facts for GET /v1/status. Both are idempotent and both
+    # are here rather than at import time, because a module-level record would
+    # be made when the first import happens rather than when the process starts
+    # serving, and the second is the number an operator reads uptime against.
+    # ``status.mark_started`` records once per process even though tests build
+    # many apps: see its Notes for why an uptime that resets under a test client
+    # would make every "since process start" label on the page a lie.
+    status.mark_started()
+    resources.seed()
+    _load_plugins(settings)
+
+    app = FastAPI(
+        title="aggregate api",
+        description=(
+            "HTTP/JSON wrapper around the aggregate library. "
+            "Stand up DecL parsing, FFT-based compound distributions, "
+            "and risk-pricing as a web service."
+        ),
+        version=_pkg_version("aggregate_api"),
+        # Disable the default Pydantic-validation 422 schema in
+        # OpenAPI -- it's noisy and we override the parse path
+        # with our own ErrorReport response model.
+    )
+
+    # Compress responses. A density payload is the whole point: the exhibits ask
+    # for every grid point (2**16 rows), which is 3.6 MB of JSON for one
+    # aggregate and 7 MB for a portfolio's per-unit frame. Those are floats
+    # rendered as decimal text, so they compress about 10 to 1: 0.35 MB and
+    # 1.3 MB on the wire, which is what an image costs.
+    #
+    # 1 kB minimum, so a health check or a one-row pentagon is not worth the
+    # round trip through zlib. Installed before CORS so the middleware stack
+    # unwinds with CORS headers on the outside, where a browser needs them even
+    # on a compressed response.
+    app.add_middleware(GZipMiddleware, minimum_size=1024)
+
+    install_cors(app, settings.cors_origins)
+
+    # Mount all routers under /v1. FastAPI's include_router accepts
+    # a prefix, similar to Flask's blueprint url_prefix kwarg.
+    app.include_router(meta_routes.router, prefix="/v1", tags=["meta"])
+    app.include_router(objects_routes.router, prefix="/v1", tags=["objects"])
+    app.include_router(decl_routes.router, prefix="/v1", tags=["decl"])
+    app.include_router(examples_routes.router, prefix="/v1", tags=["examples"])
+    # The operator's page. Mounted with the rest, and ahead of the static mount
+    # below, which is why it lives under /v1: an unmatched top-level path falls
+    # through to StaticFiles(html=True) and would be answered with index.html
+    # rather than a 404, so a top-level /status could be shadowed by a
+    # registration-order mistake and would fail by serving the SPA. Its own
+    # routes are include_in_schema=False and behind require_private; the public
+    # Caddy block 404s the whole /v1/status prefix before any of that is
+    # reached. See routes/status.py.
+    app.include_router(status_routes.router, prefix="/v1", tags=["status"])
+
+    # Static-file mount for the SPA (Plan D). Conditional because
+    # the api ships independently of the web build; if the web
+    # bundle isn't present, the api is api-only and ``/`` returns
+    # 404 (which is fine for backend-only deploys).
+    static_dir = _resolve_static_dir(settings)
+    if static_dir is not None and static_dir.exists():
+        # ``html=True`` tells StaticFiles to serve index.html for /
+        # *and* fall back to it for unknown paths -- the SPA-style
+        # client-side routing behavior the web app needs.
+        app.mount(
+            "/",
+            StaticFiles(directory=str(static_dir), html=True),
+            name="static",
+        )
+
+    return app
+
+
+def _resolve_static_dir(settings: Settings) -> Path | None:
+    """Locate the SPA bundle directory.
+
+    Order of precedence:
+
+    0. ``AGGAPI_SERVE_SPA=0`` (``settings.serve_spa``) refuses outright, which
+       is what ``aggregate-api --headless`` sets. Ahead of the other two so
+       this stays the single place that decides whether to mount, rather than
+       adding a second condition at the mount site.
+    1. ``AGGAPI_STATIC_DIR`` env var (handed via ``settings.static_dir``).
+       Useful for developing the SPA out of a separate tree.
+    2. ``src/aggregate_api/static`` inside the installed package.
+
+    Returns None if serving is off, or if neither location is set / exists.
+    """
+    if not settings.serve_spa:
+        return None
+    if settings.static_dir:
+        return Path(settings.static_dir)
+    # importlib.resources style: the static dir lives next to
+    # this file. We use Path rather than files() because StaticFiles
+    # needs a real filesystem path, not a Traversable.
+    pkg_root = Path(__file__).resolve().parent
+    return pkg_root / "static"