aggregate_api 1.0.0__py3-none-any.whl

aggregate_api/library.py

@@ -0,0 +1,94 @@
+"""The recipe base every build in this process resolves against.
+
+One underwriter, reached through :func:`get_underwriter`, and every path that
+parses a program or reads a recipe goes through it. Before this module the api
+had two: ``examples.py`` built a private :class:`Underwriter` for the menu when
+``--library`` was set, while all three build paths used ``aggregate.build``, the
+shipped singleton. That split is invisible under the default library, because
+both are then the same object, and is wrong under a custom one:
+
+* an entry is browsable in the Examples menu but any entry referencing a sibling
+  by name fails to build, because the base the parser resolves against never
+  read the file;
+* the ``.agg`` download lists the session rows of a base the menu did not come
+  from.
+
+Why a function and not a module-level object: the library is chosen by a setting
+read at process start, and tests flip that setting per case. ``lru_cache`` gives
+the singleton without the import-time evaluation a module-level object would
+force, matching :func:`aggregate_api.config.get_settings`, and
+``create_app`` clears it for the same reason it clears that one.
+
+The base is process-global and mutable: ``build(program)`` registers what it
+parses. Whether that base is shared or per session is a question for the session
+work; this module answers only "which library", and answers it once.
+"""
+
+from __future__ import annotations
+
+import time
+import warnings
+from functools import lru_cache
+from pathlib import Path
+
+from . import status
+
+
+@lru_cache(maxsize=1)
+def get_underwriter():
+    """Return the ``Underwriter`` whose recipe base backs this process.
+
+    Defaults to ``aggregate.build``, the shipped singleton loaded from
+    ``library.agg``. ``AGGAPI_LIBRARY`` overrides it with a custom ``.agg``: a
+    private :class:`Underwriter` is pointed at that file via ``databases=`` and
+    loaded, so a curated library goes through exactly the same recipe machinery
+    as the shipped one.
+
+    Returns
+    -------
+    aggregate.underwriter.Underwriter
+
+    Notes
+    -----
+    A configured but missing path warns and falls back rather than failing every
+    route, which is right for a stale setting on a server. The ``--library``
+    flag is deliberately stricter and exits instead: see
+    :func:`aggregate_api.__main__.resolve_library` for why the asymmetry is
+    intended rather than an oversight.
+
+    **The load is explicit and timed**, for ``GET /v1/status``. ``load()`` with
+    no argument is idempotent (it returns an empty list once the configured
+    request has been read), so calling it here costs nothing when the base is
+    already loaded and moves nothing when it is not: every caller reaches this
+    base through ``fork()``, which loads the parent itself. What it buys is a
+    number. The recorded figure is what *this* call paid, so a process reading
+    the shipped library reports a near-zero time, correctly: the read happened
+    when ``aggregate`` was imported, not here. A custom ``.agg`` reports the
+    real cost of reading it, which is the case where the number is worth
+    knowing.
+    """
+    from .config import get_settings
+
+    started = time.monotonic()
+    custom = get_settings().library
+    if not custom:
+        from aggregate import build
+
+        uw = build
+    else:
+        path = Path(custom)
+        if not path.is_file():
+            warnings.warn(
+                f"AGGAPI_LIBRARY={custom!r} not found; using the shipped library",
+                stacklevel=2,
+            )
+            from aggregate import build
+
+            uw = build
+        else:
+            from aggregate import Underwriter
+
+            uw = Underwriter(databases=(str(path),))
+    uw.load()
+    status.record_library_load((time.monotonic() - started) * 1000)
+    return uw

aggregate_api/library_notes.py

@@ -0,0 +1,96 @@
+"""Telling the library's warnings from everyone else's.
+
+``warnings.catch_warnings(record=True)`` plus ``simplefilter('always')`` is the
+only way to capture what ``aggregate`` says on its way to an answer, and it is a
+blunt instrument: the filters are process global and ``'always'`` lifts the
+default suppressions, so the block catches every warning raised anywhere in the
+interpreter for as long as it is open, including ones this service provokes
+about itself.
+
+That is not hypothetical. The api's audit log leaked sqlite connections until
+a70, and a garbage collection landing inside a capture block reported
+``unclosed database in <sqlite3.Connection ...>`` as something the reader's
+program had done. The leak is fixed; this module is the other half, and it is
+the half that keeps the *next* stray warning, from any library in the
+environment, out of a reader's face.
+
+Every capture site in this package goes through :func:`library_warnings`, and
+the one site that also needs the logging channel (the build route) uses
+:func:`from_library` directly inside its own richer context manager.
+
+The test is **path containment, not the category and not the name.** A library
+``UserWarning`` is indistinguishable from anyone else's by type, and
+``aggregate_api`` contains the string ``aggregate``, so a substring test would
+claim this service's own warnings as the library's.
+"""
+
+from __future__ import annotations
+
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+
+import aggregate as _aggregate_pkg
+
+#: Where the ``aggregate`` package lives on disk. Resolved once at import: the
+#: path cannot move while the process runs, and ``Path.resolve`` on every
+#: warning of every build would be work for an answer that never changes.
+_LIBRARY_ROOT = str(Path(_aggregate_pkg.__file__).resolve().parent)
+
+
+def from_library(filename: str) -> bool:
+    """Was this warning raised from inside ``aggregate``?
+
+    Parameters
+    ----------
+    filename : str
+        ``warnings.WarningMessage.filename``, the source file of the
+        ``warn()`` call.
+
+    Returns
+    -------
+    bool
+        True when the file sits under the installed ``aggregate`` package.
+
+    Notes
+    -----
+    Resolved on both sides so a junctioned or symlinked checkout compares
+    equal, which this repo's ``.venv`` arrangement makes a live concern rather
+    than a theoretical one.
+    """
+    if not filename:
+        return False
+    try:
+        return Path(filename).resolve().is_relative_to(_LIBRARY_ROOT)
+    except (OSError, ValueError):  # pragma: no cover -- unresolvable path
+        return False
+
+
+@contextmanager
+def library_warnings():
+    """Capture ``warnings.warn`` from ``aggregate``, and only from it.
+
+    Yields
+    ------
+    list of str
+        Empty while the block runs and filled on exit, so callers extend their
+        own list *after* the ``with``, not inside it.
+
+    Examples
+    --------
+    >>> with library_warnings() as caught:      # doctest: +SKIP
+    ...     panel = obj.evaluate(premium)
+    >>> warns.extend(caught)                    # doctest: +SKIP
+
+    Notes
+    -----
+    Filled on exit rather than as each warning arrives because
+    ``catch_warnings(record=True)`` hands back a list it appends to itself, and
+    the filtering has to happen once that list is complete.
+    """
+    kept: list[str] = []
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        yield kept
+        kept.extend(str(w.message) for w in caught
+                    if from_library(getattr(w, "filename", "")))