trendify2 2.0.4__py3-none-any.whl

trendify/plotting/point.py

@@ -0,0 +1,89 @@
+"""
+`Point2D`: a single scattered (x, y) point, styled with a `Marker`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import plotly.graph_objects as go
+from pydantic import ConfigDict
+
+from trendify.formats.format2d import XYData
+from trendify.plotting.figure import PlotlyFigure
+from trendify.styling.marker import Marker
+
+__all__ = ["Point2D"]
+
+logger = logging.getLogger(__name__)
+
+
+class Point2D(XYData):
+    """
+    Defines a point to be scattered onto xy plot.
+    """
+
+    x: float | str
+    """X value for the point."""
+
+    y: float | str
+    """Y value for the point."""
+
+    marker: Marker | None = Marker()
+    """Style and label information for scattering points to matplotlib axes. Only the label
+    information is used in Grafana. Eventually style information will be used in Grafana."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    def add_to_plotly(self, plotly_figure: PlotlyFigure) -> PlotlyFigure:
+        """Add point to plotly figure with legendgroup support"""
+        legend_key = (
+            f"{self.marker.label}_{self.marker.color}_{self.marker.symbol}"
+            if self.marker
+            else None
+        )
+        # Prepare metadata for the tooltip
+        metadata_html = (
+            "<br>".join([f"{key}: {value}" for key, value in self.metadata.items()])
+            if self.metadata
+            else ""
+        )
+
+        # Define hovertemplate for the tooltip
+        hovertemplate = (
+            f"<b>{self.marker.label if self.marker else ''}</b><br>"
+            "x: %{x}<br>"
+            "y: %{y}<br>"
+            f"{metadata_html}<extra></extra>"
+        )
+
+        plotly_figure.fig.add_trace(
+            go.Scatter(
+                x=[self.x],
+                y=[self.y],
+                name=self.marker.label if self.marker else None,
+                mode="markers",
+                marker=dict(
+                    color=self.marker.rgba if self.marker else None,
+                    size=self.marker.size if self.marker else None,
+                    symbol=self.marker.plotly_symbol if self.marker else None,
+                ),
+                zorder=int(self.marker.zorder) if self.marker else None,
+                legendgroup=legend_key,
+                hovertemplate=hovertemplate,
+                hoverlabel=dict(
+                    bgcolor=(self.marker.rgba if self.marker else None),
+                    font=dict(
+                        color=self.marker.get_contrast_color() if self.marker else None
+                    ),
+                ),
+                showlegend=(
+                    True if legend_key not in plotly_figure.legend_groups else False
+                ),
+            )
+        )
+
+        if legend_key and legend_key not in plotly_figure.legend_groups:
+            plotly_figure.legend_groups.add(legend_key)
+
+        return plotly_figure

trendify/plotting/scatter.py

@@ -0,0 +1,100 @@
+"""
+`Scatter2D`: a bulk collection of (x, y) points sharing one `Marker`, drawn as unconnected
+scatter points.
+
+Use this instead of many individual `Point2D` records when a single generation call
+produces a large array of points that all share one style and don't need distinct per-point
+tags/metadata (e.g. a raw scatter of measurements from one run). `Point2D` remains the right
+choice when each point is its own taggable/hoverable entity, such as one point summarizing
+one run, aggregated across many runs that share a tag.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import plotly.graph_objects as go
+from pydantic import ConfigDict
+
+from trendify.formats.format2d import XYData
+from trendify.plotting.figure import PlotlyFigure
+from trendify.styling.marker import Marker
+from trendify.typing import VecN
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+__all__ = ["Scatter2D"]
+
+logger = logging.getLogger(__name__)
+
+
+class Scatter2D(XYData):
+    """
+    A collection of unconnected scattered points sharing one `Marker`.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    x: VecN
+    """x values"""
+
+    y: VecN
+    """y values"""
+
+    marker: Marker = Marker()
+    """Style and label information shared by every point in this scatter."""
+
+    def plot_to_ax(self, ax: Axes) -> None:
+        """
+        Scatters xy data to a matplotlib axes object.
+
+        Args:
+            ax (Axes): axes to which xy data should be plotted
+
+        """
+        ax.scatter(self.x, self.y, **self.marker.as_scatter_plot_kwargs())
+
+    def add_to_plotly(self, plotly_figure: PlotlyFigure) -> PlotlyFigure:
+        legend_key = f"{self.marker.label}_{self.marker.color}_{self.marker.symbol}"
+
+        metadata_html = (
+            "<br>".join(f"{key}: {value}" for key, value in self.metadata.items())
+            if self.metadata
+            else ""
+        )
+        hovertemplate = (
+            f"<b>{self.marker.label or ''}</b><br>"
+            "x: %{x}<br>"
+            "y: %{y}<br>"
+            f"{metadata_html}<extra></extra>"
+        )
+
+        plotly_figure.fig.add_trace(
+            go.Scatter(
+                x=self.x,
+                y=self.y,
+                name=self.marker.label,
+                mode="markers",
+                marker=dict(
+                    color=self.marker.rgba,
+                    size=self.marker.size,
+                    symbol=self.marker.plotly_symbol,
+                ),
+                zorder=int(self.marker.zorder),
+                legendgroup=legend_key,
+                hovertemplate=hovertemplate,
+                hoverlabel=dict(
+                    bgcolor=self.marker.rgba,
+                    font=dict(color=self.marker.get_contrast_color()),
+                ),
+                showlegend=(
+                    True if legend_key not in plotly_figure.legend_groups else False
+                ),
+            )
+        )
+
+        if legend_key not in plotly_figure.legend_groups:
+            plotly_figure.legend_groups.add(legend_key)
+        return plotly_figure

trendify/plotting/trace.py

@@ -0,0 +1,129 @@
+"""
+`Trace2D`: an xy line built from flat `x`/`y` arrays, styled with a `Pen`, and optionally
+marked at intervals with a single shared `Marker` (mirroring matplotlib's native
+`markevery`).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import plotly.graph_objects as go
+from pydantic import ConfigDict
+
+from trendify.base.pen import Pen
+from trendify.formats.format2d import XYData
+from trendify.plotting.figure import PlotlyFigure
+from trendify.styling.marker import Marker
+from trendify.typing import VecN
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+__all__ = ["Trace2D"]
+
+logger = logging.getLogger(__name__)
+
+
+class Trace2D(XYData):
+    """An xy line, optionally marked at intervals."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    x: VecN
+    """x values"""
+
+    y: VecN
+    """y values"""
+
+    pen: Pen = Pen()
+    """Style and label information for drawing to matplotlib axes. Only the label information
+    is used in Grafana. Eventually style information will be used in Grafana."""
+
+    marker: Marker | None = None
+    """Shared marker style drawn along the line (e.g. one marker every `markevery` points).
+    `None` draws a plain line with no markers."""
+
+    markevery: int | None = None
+    """Draw a marker every Nth point when `marker` is set (passed straight through to
+    matplotlib's `Axes.plot(markevery=...)`); `None` marks every point."""
+
+    def plot_to_ax(self, ax: Axes) -> None:
+        """
+        Plots xy data from trace to a matplotlib axes object.
+
+        Args:
+            ax (Axes): axes to which xy data should be plotted
+
+        """
+        kwargs = self.pen.as_scatter_plot_kwargs()
+        if self.marker is not None:
+            kwargs["marker"] = self.marker.symbol
+            kwargs["markersize"] = self.marker.size
+            kwargs["markerfacecolor"] = self.marker.color
+            kwargs["markeredgecolor"] = self.marker.color
+            kwargs["markevery"] = self.markevery if self.markevery is not None else 1
+        ax.plot(self.x, self.y, **kwargs)
+
+    def add_to_plotly(self, plotly_figure: PlotlyFigure) -> PlotlyFigure:
+        legend_key = (
+            f"{self.pen.label}_{self.pen.color}_{self.pen._convert_linestyle_to_plotly()}"
+            if self.pen
+            else None
+        )
+        # Prepare metadata for the tooltip
+        metadata_html = (
+            "<br>".join([f"{key}: {value}" for key, value in self.metadata.items()])
+            if self.metadata
+            else ""
+        )
+
+        # Define hovertemplate for the tooltip
+        hovertemplate = (
+            f"<b>{self.pen.label if self.pen else ''}</b><br>"
+            "x: %{x}<br>"
+            "y: %{y}<br>"
+            f"{metadata_html}<extra></extra>"
+        )
+
+        # `markevery` (subsampling markers along the line) has no direct Plotly equivalent
+        # for a single trace, so Plotly renders a marker at every point when `marker` is set.
+        mode_parts = []
+        if self.pen.linestyle is not None:
+            mode_parts.append("lines")
+        if self.marker is not None:
+            mode_parts.append("markers")
+
+        plotly_figure.fig.add_trace(
+            go.Scatter(
+                x=self.x,
+                y=self.y,
+                name=self.pen.label if self.pen else None,
+                mode="+".join(mode_parts) if mode_parts else "lines",
+                line=dict(
+                    color=self.pen.rgba if self.pen else None,
+                    width=self.pen.size if self.pen else None,
+                    dash=self.pen._convert_linestyle_to_plotly() if self.pen else None,
+                ),
+                marker=dict(
+                    color=self.marker.rgba if self.marker else self.pen.rgba,
+                    size=self.marker.size if self.marker else None,
+                    symbol=self.marker.plotly_symbol if self.marker else None,
+                ),
+                zorder=int(self.pen.zorder),
+                hovertemplate=hovertemplate,
+                hoverlabel=dict(
+                    bgcolor=(self.pen.rgba if self.pen else None),
+                    font=dict(color=self.pen.get_contrast_color()),
+                ),
+                legendgroup=legend_key,
+                showlegend=(
+                    True if legend_key not in plotly_figure.legend_groups else False
+                ),
+            )
+        )
+
+        if legend_key and legend_key not in plotly_figure.legend_groups:
+            plotly_figure.legend_groups.add(legend_key)
+        return plotly_figure

trendify/progress.py

@@ -0,0 +1,43 @@
+"""
+Progress reporting for the generate/render pipeline: a lightweight event type plus a callback
+type alias, so a caller embedding trendify (e.g. running it inside a container and feeding
+status back to their own UI/API) can observe progress without needing logging configured or
+parsing log lines.
+
+`on_progress` is always invoked from the main process, never a worker: `generate_records`
+reports after each `write_run` (the parent process is the only one that ever writes) and
+`render_assets` reports after each tag's `future.result()` (or, sequentially, after each
+`_render_tag_assets` call) -- so the callback itself never needs to be picklable/sent across a
+process boundary, unlike `record_generator` itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = ["ProgressCallback", "ProgressEvent"]
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    """One unit of work finishing during `generate` or `render`."""
+
+    stage: Literal["generate", "render"]
+    """Which pipeline stage this event is from."""
+
+    completed: int
+    """Number of units finished so far this stage, including this one."""
+
+    total: int
+    """Total number of units this stage will process."""
+
+    detail: str
+    """Human-readable identifier for the unit that just finished: a run directory's path for
+    `generate`, a tag's display string for `render`."""
+
+
+ProgressCallback = Callable[[ProgressEvent], None]
+"""A callback invoked once per completed unit of work. Left to raise: a callback that fails is
+almost certainly a bug in the caller's own integration, not something to silently swallow."""

trendify/store/__init__.py

@@ -0,0 +1,30 @@
+"""SQLite-backed storage and querying of records."""
+
+from trendify.store import db
+from trendify.store import record_store
+from trendify.store import tags
+
+from trendify.store.db import (
+    SCHEMA_VERSION,
+    connect,
+)
+from trendify.store.record_store import (
+    RecordStore,
+)
+from trendify.store.tags import (
+    decode_tag,
+    encode_tag,
+    tag_to_path_parts,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "RecordStore",
+    "connect",
+    "db",
+    "decode_tag",
+    "encode_tag",
+    "record_store",
+    "tag_to_path_parts",
+    "tags",
+]

trendify/store/db.py

@@ -0,0 +1,119 @@
+"""
+SQLite connection factory, pragmas, and schema management for the trendify store.
+
+- One `.db` file per trendify output directory, opened by every worker process independently.
+- WAL mode gives concurrent readers plus one writer without the readers blocking on the
+  writer; `busy_timeout` handles the writer-vs-writer case without any external file locking.
+- Schema versioning via `PRAGMA user_version`, checked/applied on every `connect()` call so
+  opening a fresh `.db` file bootstraps it and opening an existing one verifies compatibility.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+__all__ = ["SCHEMA_VERSION", "connect"]
+
+logger = logging.getLogger(__name__)
+
+SCHEMA_VERSION = 1
+
+_SCHEMA_DDL = """
+CREATE TABLE IF NOT EXISTS runs (
+    id INTEGER PRIMARY KEY,
+    path TEXT NOT NULL UNIQUE,
+    generated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS records (
+    id INTEGER PRIMARY KEY,
+    run_id INTEGER NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    record_type TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_records_run ON records(run_id);
+
+CREATE TABLE IF NOT EXISTS record_tags (
+    record_id INTEGER NOT NULL REFERENCES records(id) ON DELETE CASCADE,
+    tag_key TEXT NOT NULL,
+    record_type TEXT NOT NULL,
+    PRIMARY KEY (record_id, tag_key)
+);
+CREATE INDEX IF NOT EXISTS idx_record_tags_lookup ON record_tags(tag_key, record_type);
+
+CREATE TABLE IF NOT EXISTS table_entries (
+    id INTEGER PRIMARY KEY,
+    record_id INTEGER NOT NULL REFERENCES records(id) ON DELETE CASCADE,
+    tag_key TEXT NOT NULL,
+    row_key TEXT NOT NULL,
+    col_key TEXT NOT NULL,
+    value_num REAL,
+    value_text TEXT,
+    value_bool INTEGER,
+    unit TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_table_entries_tag ON table_entries(tag_key);
+CREATE INDEX IF NOT EXISTS idx_table_entries_record ON table_entries(record_id);
+"""
+
+
+def connect(db_path: Path, *, readonly: bool = False) -> sqlite3.Connection:
+    """
+    Opens a WAL-mode SQLite connection to `db_path`, bootstrapping the schema on first use.
+
+    Args:
+        db_path (Path): path to the trendify output directory's `.db` file
+        readonly (bool): open in read-only mode (`mode=ro` URI), for render workers that only
+            ever query and never write, so they can safely run concurrently with an
+            in-progress writer under WAL.
+
+    Returns:
+        (sqlite3.Connection): a configured connection, with row access by column name.
+
+    """
+    logger.debug(f"Connecting to {db_path = } ({readonly = })")
+    if readonly:
+        uri = f"file:{db_path}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+    else:
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(db_path)
+
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA busy_timeout=30000")
+    conn.execute("PRAGMA foreign_keys=ON")
+
+    if not readonly:
+        _ensure_schema(conn)
+
+    return conn
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    """
+    Bootstraps the schema on a fresh database, or verifies the on-disk schema version matches
+    `SCHEMA_VERSION` on an existing one. There is deliberately no migration logic yet, since
+    there has only ever been one schema version; this is the hook future migrations attach to.
+    """
+    (version,) = conn.execute("PRAGMA user_version").fetchone()
+    if version == 0:
+        logger.info(f"Bootstrapping fresh schema (version {SCHEMA_VERSION})")
+        conn.executescript(_SCHEMA_DDL)
+        conn.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
+        conn.commit()
+    elif version != SCHEMA_VERSION:
+        logger.error(
+            f"Database schema version {version} does not match expected "
+            f"{SCHEMA_VERSION}, and no migration path exists yet."
+        )
+        raise RuntimeError(
+            f"Database schema version {version} does not match expected "
+            f"{SCHEMA_VERSION}, and no migration path exists yet."
+        )
+    else:
+        logger.debug(f"Schema version {version} verified")