trendify2 2.0.4__py3-none-any.whl

trendify/styling/legend.py

@@ -0,0 +1,217 @@
+"""
+`Legend` (matplotlib/Plotly legend styling: location, title, opacity, border) and the
+`LegendLocation` enum of matplotlib-recognized location strings it validates against.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from trendify.base.helpers import HashableBase
+
+__all__ = ["Legend", "LegendLocation"]
+
+
+class LegendLocation(StrEnum):
+    """
+    Matplotlib-recognized legend anchor locations.
+    """
+
+    BEST = "best"
+    """Matplotlib chooses the location that overlaps plotted data the least."""
+
+    UPPER_RIGHT = "upper right"
+    """Upper right corner of the axes."""
+
+    UPPER_LEFT = "upper left"
+    """Upper left corner of the axes."""
+
+    LOWER_LEFT = "lower left"
+    """Lower left corner of the axes."""
+
+    LOWER_RIGHT = "lower right"
+    """Lower right corner of the axes."""
+
+    RIGHT = "right"
+    """Right edge of the axes, vertically centered."""
+
+    CENTER_LEFT = "center left"
+    """Left edge of the axes, vertically centered."""
+
+    CENTER_RIGHT = "center right"
+    """Right edge of the axes, vertically centered."""
+
+    LOWER_CENTER = "lower center"
+    """Bottom edge of the axes, horizontally centered."""
+
+    UPPER_CENTER = "upper center"
+    """Top edge of the axes, horizontally centered."""
+
+    CENTER = "center"
+    """Center of the axes."""
+
+
+class Legend(HashableBase):
+    """
+    Configuration container for Matplotlib legend styling and placement.
+
+    Placement is governed by a combination of the `loc` and `bbox_to_anchor`
+    parameters, mirroring Matplotlib's `Axes.legend()`.
+    """
+
+    visible: bool = True
+    """Whether the legend should be displayed."""
+
+    title: str | None = None
+    """Title displayed above the legend entries."""
+
+    framealpha: float = 1
+    """Opacity of the legend background. 1 is fully opaque, 0 is fully transparent."""
+
+    loc: LegendLocation = LegendLocation.BEST
+    """Anchor point for the legend (e.g., upper right, lower left). See `LegendLocation`
+    enum for options."""
+
+    ncol: int = 1
+    """Number of columns to arrange legend entries into."""
+
+    fancybox: bool = True
+    """Whether to draw a rounded (True) or square (False) legend frame."""
+
+    edgecolor: str = "black"
+    """Color of the legend frame border."""
+
+    zorder: int = 1000
+    """Prioritization of the legend relative to plotted data."""
+
+    bbox_to_anchor: tuple[float, float] | None = None
+    """Offset position of the legend in figure or axes coordinates. If `None`, the legend
+    is placed inside the axes using `loc`."""
+
+    def to_kwargs(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "framealpha": self.framealpha,
+            "loc": self.loc,
+            "ncol": self.ncol,
+            "fancybox": self.fancybox,
+        }
+
+    @property
+    def plotly_location(self) -> dict:
+        """
+        Convert matplotlib legend location to Plotly legend position parameters.
+
+        Returns:
+            dict: Dictionary containing Plotly legend position parameters (x, y, xanchor, yanchor)
+
+        """
+        # Default position mappings for standard locations
+        location_map = {
+            LegendLocation.BEST: {
+                "x": 1.02,
+                "y": 1,
+                "xanchor": "left",
+                "yanchor": "top",
+            },
+            LegendLocation.UPPER_RIGHT: {
+                "x": 0.98,
+                "y": 0.98,
+                "xanchor": "right",
+                "yanchor": "top",
+            },
+            LegendLocation.UPPER_LEFT: {
+                "x": 0.02,
+                "y": 0.98,
+                "xanchor": "left",
+                "yanchor": "top",
+            },
+            LegendLocation.LOWER_LEFT: {
+                "x": 0.02,
+                "y": 0.02,
+                "xanchor": "left",
+                "yanchor": "bottom",
+            },
+            LegendLocation.LOWER_RIGHT: {
+                "x": 0.98,
+                "y": 0.02,
+                "xanchor": "right",
+                "yanchor": "bottom",
+            },
+            LegendLocation.RIGHT: {
+                "x": 1.02,
+                "y": 0.5,
+                "xanchor": "left",
+                "yanchor": "middle",
+            },
+            LegendLocation.CENTER_LEFT: {
+                "x": -0.02,
+                "y": 0.5,
+                "xanchor": "right",
+                "yanchor": "middle",
+            },
+            LegendLocation.CENTER_RIGHT: {
+                "x": 1.02,
+                "y": 0.5,
+                "xanchor": "left",
+                "yanchor": "middle",
+            },
+            LegendLocation.LOWER_CENTER: {
+                "x": 0.5,
+                "y": 0.02,
+                "xanchor": "center",
+                "yanchor": "bottom",
+            },
+            LegendLocation.UPPER_CENTER: {
+                "x": 0.5,
+                "y": 0.98,
+                "xanchor": "center",
+                "yanchor": "top",
+            },
+            LegendLocation.CENTER: {
+                "x": 0.5,
+                "y": 0.5,
+                "xanchor": "center",
+                "yanchor": "middle",
+            },
+        }
+
+        # If bbox_to_anchor is provided, use it to override the position
+        if self.bbox_to_anchor is not None:
+            x, y = self.bbox_to_anchor
+            # Determine anchors based on location
+            if self.loc in [
+                LegendLocation.CENTER_LEFT,
+                LegendLocation.UPPER_LEFT,
+                LegendLocation.LOWER_LEFT,
+            ]:
+                xanchor = "right"
+            elif self.loc in [
+                LegendLocation.CENTER_RIGHT,
+                LegendLocation.UPPER_RIGHT,
+                LegendLocation.LOWER_RIGHT,
+            ]:
+                xanchor = "left"
+            else:
+                xanchor = "center"
+
+            if self.loc in [
+                LegendLocation.UPPER_RIGHT,
+                LegendLocation.UPPER_LEFT,
+                LegendLocation.UPPER_CENTER,
+            ]:
+                yanchor = "top"
+            elif self.loc in [
+                LegendLocation.LOWER_RIGHT,
+                LegendLocation.LOWER_LEFT,
+                LegendLocation.LOWER_CENTER,
+            ]:
+                yanchor = "bottom"
+            else:
+                yanchor = "middle"
+
+            return {"x": x, "y": y, "xanchor": xanchor, "yanchor": yanchor}
+
+        # Use predefined mapping if no bbox_to_anchor
+        return location_map[self.loc]

trendify/styling/marker.py

@@ -0,0 +1,168 @@
+"""
+`Marker`: scatter-point styling (color, size, alpha, symbol) for `Point2D`, including the
+`from_pen` conversion used when a `Trace2D`'s `Pen` needs to render as scattered markers.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from matplotlib.colors import to_rgba
+from pydantic import ConfigDict
+
+from trendify.base.helpers import HashableBase
+from trendify.base.pen import Pen
+
+__all__ = ["Marker"]
+
+logger = logging.getLogger(__name__)
+
+
+class Marker(HashableBase):
+    """
+    Defines marker for scattering to matplotlib
+    """
+
+    color: tuple[float, float, float] | tuple[float, float, float, float] | str = "k"
+    """Color of line"""
+
+    size: float = 5
+    """Line width"""
+
+    alpha: float = 1
+    """Opacity from 0 to 1 (inclusive)"""
+
+    zorder: float = 0
+    """Prioritization"""
+
+    label: str | None = None
+    """Legend label"""
+
+    symbol: str = "."
+    """Matplotlib symbol string"""
+
+    @classmethod
+    def from_pen(
+        cls,
+        pen: Pen,
+        symbol: str = ".",
+    ):
+        """
+        Converts Pen to marker with the option to specify a symbol.
+
+        `Pen` has one field (`linestyle`) that `Marker` doesn't, so its dumped dict can't be
+        splatted directly as `**kwargs` into `Marker`. This drops that one field and splats
+        what's left (color/size/alpha/zorder/label, which line up 1:1 with `Marker`'s fields).
+        """
+        data = pen.model_dump()
+        data.pop("linestyle", None)
+        return cls(symbol=symbol, **data)
+
+    model_config = ConfigDict(extra="forbid")
+
+    def as_scatter_plot_kwargs(self) -> dict[str, Any]:
+        """
+        Returns:
+            (dict): dictionary of `kwargs` for [matplotlib scatter][matplotlib.axes.Axes.scatter]
+
+        """
+        return {
+            "marker": self.symbol,
+            "color": self.color,
+            "s": self.size,
+            "alpha": self.alpha,
+            "zorder": self.zorder,
+            "label": self.label,
+        }
+
+    @property
+    def plotly_symbol(self) -> str:
+        """Convert matplotlib marker symbol to plotly symbol"""
+        symbol_map = {
+            ".": "circle",
+            "o": "circle",
+            "v": "triangle-down",
+            "^": "triangle-up",
+            "<": "triangle-left",
+            ">": "triangle-right",
+            "s": "square",
+            "p": "pentagon",
+            "*": "star",
+            "h": "hexagon",
+            "+": "cross",
+            "x": "x",
+            "D": "diamond",
+        }
+        return symbol_map.get(self.symbol, "circle")
+
+    @property
+    def rgba(self) -> str:
+        """
+        Convert the pen's color to rgba string format.
+
+        Returns:
+            str: Color in 'rgba(r,g,b,a)' format where r,g,b are 0-255 and a is 0-1
+
+        """
+        # Handle different color input formats
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            # Use matplotlib's color converter
+            rgba_vals = to_rgba(self.color, self.alpha)
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        return f"rgba({r}, {g}, {b}, {a})"
+
+    def get_contrast_color(self, background_luminance: float = 1.0) -> str:
+        """
+        Returns 'white' or 'black' to provide the best contrast against the pen's color,
+        taking into account the alpha (transparency) value of the line.
+
+        Args:
+            background_luminance (float): The luminance of the background (default is 1.0 for white).
+
+        Returns:
+            str: 'white' or 'black'
+
+        """
+        # Convert the pen's color to RGB (0-255 range) and get alpha
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            rgba_vals = to_rgba(self.color, self.alpha)
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        # Calculate relative luminance of the pen's color
+        def luminance(channel: float) -> float:
+            channel /= 255.0
+            return (
+                channel / 12.92
+                if channel <= 0.03928
+                else ((channel + 0.055) / 1.055) ** 2.4
+            )
+
+        color_luminance = (
+            0.2126 * luminance(r) + 0.7152 * luminance(g) + 0.0722 * luminance(b)
+        )
+
+        # Blend the color luminance with the background luminance based on alpha
+        blended_luminance = (1 - a) * background_luminance + a * color_luminance
+
+        # Return white for dark blended colors, black for light blended colors
+        return "white" if blended_luminance < 0.5 else "black"

trendify/typing.py

@@ -0,0 +1,26 @@
+"""
+Shared numeric array type aliases (`VecN`, `MatN`) used across `trendify.plotting`/
+`trendify.styling` for fields like `Trace2D.x`/`Trace2D.y` and `HistogramStyle.bins`. Backed by
+`numpydantic.NDArray` for runtime pydantic validation, with a plain `TypeAlias` swapped in under
+`TYPE_CHECKING` so static type checkers see an ordinary array/list/tuple union instead of
+`numpydantic`'s shape-annotated generic.
+"""
+
+from typing import TYPE_CHECKING, Annotated
+
+import numpy as np
+from numpydantic import NDArray, Shape
+
+__all__ = ["MatN", "VecN"]
+
+if TYPE_CHECKING:
+    type _VecBase = np.ndarray | list[float | int] | tuple[float | int, ...]
+
+    type VecN = _VecBase
+    """An N-element numeric array of arbitrary length."""
+
+    type MatN = _VecBase
+    """An NxN numeric matrix of arbitrary length."""
+else:
+    VecN = Annotated[NDArray[Shape["*"], float | int], ...]  # noqa: F722
+    MatN = Annotated[NDArray[Shape["*, *"], float | int], ...]  # noqa: F722

trendify/viewer/__init__.py

@@ -0,0 +1,41 @@
+"""FastAPI dashboard for browsing a `trendify.db` in the browser."""
+
+from trendify.viewer import app as viewer_app
+from trendify.viewer import plot_config, routes, tag_tree
+from trendify.viewer.app import (
+    create_app,
+    create_app_from_env,
+)
+from trendify.viewer.plot_config import (
+    HoverMode,
+    InterpMode,
+    LineMode,
+    PlotConfig,
+    camel_case_dict,
+)
+from trendify.viewer.routes import (
+    api,
+    pages,
+)
+from trendify.viewer.tag_tree import (
+    TagNode,
+    build_tag_tree,
+)
+
+__all__ = [
+    "HoverMode",
+    "InterpMode",
+    "LineMode",
+    "PlotConfig",
+    "TagNode",
+    "api",
+    "build_tag_tree",
+    "camel_case_dict",
+    "create_app",
+    "create_app_from_env",
+    "pages",
+    "plot_config",
+    "routes",
+    "tag_tree",
+    "viewer_app",
+]

trendify/viewer/app.py

@@ -0,0 +1,208 @@
+"""
+FastAPI app factory for the trendify dashboard. See `trendify.cli`'s `serve` command for how
+this gets launched.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import os
+from collections import OrderedDict
+from collections.abc import AsyncGenerator, Sequence
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+from trendify.__about__ import __version__
+from trendify.store.record_store import RecordStore
+from trendify.viewer.hydration import HydrationRunner
+from trendify.viewer.routes import api, pages
+
+if TYPE_CHECKING:
+    import socket
+
+    import uvicorn
+
+__all__ = ["close_runners", "create_app", "create_app_from_env", "make_server"]
+
+_DB_PATH_ENV_VAR = "TRENDIFY_DB_PATH"
+
+logger = logging.getLogger(__name__)
+
+_VIEWER_DIR = Path(__file__).parent
+_TEMPLATES_DIR = _VIEWER_DIR / "templates"
+_STATIC_DIR = _TEMPLATES_DIR / "static"
+
+
+def create_app(
+    db_path: Path | str,
+    *,
+    show_db_path: bool = True,
+    cors_origins: Sequence[str] = (),
+) -> FastAPI:
+    """
+    Builds the dashboard FastAPI app for `db_path`.
+
+    The app runs on its own or mounted inside another FastAPI/Starlette app, either at a path
+    prefix (`host.mount("/viz", create_app(db_path))`) or on its own hostname, and needs nothing
+    from the host: no lifespan, no shared state. Pages and scripts build their URLs from the
+    prefix the app is mounted under, so they work wherever it is served.
+
+    All database and plot-building work runs on two dedicated worker threads
+    (`app.state.runner` for real requests and `app.state.hydration_runner` for background
+    prefetch, see `routes.api`), each with its own read-only `RecordStore` connection opened on
+    first use. A slow request therefore never blocks the event loop, which matters when that loop
+    is shared with a host site's other endpoints, and a prefetch never queues ahead of a click.
+    A SQLite connection belongs to the thread that opens it, which is why each one lives
+    entirely on its worker thread. The lifespan only closes those connections at shutdown; a
+    mounted app doesn't get one, and its connections then close with the interpreter.
+
+    This app is meant to run as a single process (each process would keep its own caches).
+
+    Args:
+        db_path (Path | str): path to the `.db` file to serve. Must already exist.
+        show_db_path (bool): show the server-side path of `db_path` in the page header. Turn
+            off when the viewer is exposed to people who shouldn't see the server's file layout.
+        cors_origins (Sequence[str]): origins whose browser JavaScript may call this app's API
+            from another origin (an exact list; no wildcard is added for you). Empty by
+            default, which adds no CORS headers. Not needed to show the viewer in an `<iframe>`:
+            the page then calls its own origin. Only needed if the host page's own scripts fetch
+            from the viewer's API.
+
+    Returns:
+        (FastAPI): the configured app, ready for `uvicorn.run`, `host.mount`, or a `TestClient`.
+
+    """
+    db_path = Path(db_path)
+    RecordStore.open(
+        db_path, readonly=True
+    ).close()  # fail now, not on the first request
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+        try:
+            yield
+        finally:
+            close_runners(app)
+
+    app = FastAPI(title="trendify", version=__version__, lifespan=lifespan)
+    app.state.runner = HydrationRunner(db_path)
+    app.state.hydration_runner = HydrationRunner(db_path)
+    app.state.response_cache = OrderedDict()
+    app.state.db_path = db_path
+    app.state.db_mtime = None
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(cors_origins),
+            allow_methods=["GET"],
+            allow_headers=["x-trendify-hydrate"],
+        )
+
+    templates = Jinja2Templates(directory=_TEMPLATES_DIR)
+    # Jinja's `Environment.globals` is inferred from its default namespace (range, dict, ...),
+    # so it isn't typed as the open `dict[str, Any]` it behaves as.
+    env_globals = cast("dict[str, Any]", templates.env.globals)
+    env_globals["current_year"] = datetime.datetime.now().year
+    env_globals["app_version"] = __version__
+    env_globals["db_path"] = str(db_path) if show_db_path else ""
+    app.state.templates = templates
+
+    app.mount("/static", StaticFiles(directory=_STATIC_DIR), name="static")
+    app.include_router(pages.router)
+    app.include_router(api.router, prefix="/api")
+
+    return app
+
+
+def create_app_from_env() -> FastAPI:
+    """
+    `create_app`, reading `db_path` from the `TRENDIFY_DB_PATH` environment variable instead of
+    a direct argument.
+
+    This exists solely as a uvicorn ASGI factory target (`uvicorn.run(..., factory=True)`) for
+    `trendify serve --reload`: uvicorn's reload mode re-imports the app in a fresh subprocess on
+    every file change, so it needs an importable `module:attribute` string rather than a live app
+    instance; there is no other way to hand it a runtime value like `db_path` across that
+    re-import boundary.
+    """
+    db_path = os.environ[_DB_PATH_ENV_VAR]
+    return create_app(Path(db_path))
+
+
+def close_runners(app: FastAPI) -> None:
+    """
+    Stops a viewer app's worker threads and releases every request still waiting on them (those
+    answer 503), without waiting for a plot that is mid-build. The app calls this itself at
+    shutdown; a server that wants to stop quickly calls it as soon as shutdown begins (see
+    `make_server`). Safe to call more than once.
+
+    Args:
+        app (FastAPI): an app made by `create_app`.
+
+    """
+    app.state.runner.close()
+    app.state.hydration_runner.close()
+
+
+def make_server(
+    app: FastAPI,
+    *,
+    host: str,
+    port: int,
+    log_level: str = "critical",
+    viewers: Sequence[FastAPI] | None = None,
+) -> uvicorn.Server:
+    """
+    Builds a uvicorn server for `app` that stops promptly and quietly on Ctrl+C.
+
+    The page prefetches every tag in the background, so when Ctrl+C arrives there can be many
+    requests in flight, and plain uvicorn waits for all of them before it exits (or, after a
+    timeout, cancels them with a traceback each). This server releases the viewer's waiting
+    requests the moment shutdown begins, so they finish at once with a 503.
+
+    Args:
+        app (FastAPI): the app to serve.
+        host (str): interface to bind.
+        port (int): port to bind.
+        log_level (str): uvicorn log level.
+        viewers (Sequence[FastAPI] | None): viewer apps (from `create_app`) to release at
+            shutdown. Defaults to `app` itself; pass the mounted viewers when `app` is a host
+            site that mounts them.
+
+    Returns:
+        (uvicorn.Server): call `.run()` on it.
+
+    """
+    import uvicorn
+
+    targets = (app,) if viewers is None else tuple(viewers)
+
+    class ViewerServer(uvicorn.Server):
+        async def shutdown(self, sockets: list[socket.socket] | None = None) -> None:
+            for viewer in targets:
+                close_runners(viewer)
+            await super().shutdown(sockets)
+
+        def run(self, sockets: list[socket.socket] | None = None) -> None:
+            try:
+                super().run(sockets)
+            except KeyboardInterrupt:
+                pass  # uvicorn re-raises Ctrl+C once it has shut down cleanly; that's the end
+
+    return ViewerServer(
+        uvicorn.Config(
+            app,
+            host=host,
+            port=port,
+            log_level=log_level,
+            timeout_graceful_shutdown=3,  # a safety net; requests are already released
+        )
+    )