pixie-lab 0.1.0__py3-none-any.whl

pixie/web/_table_state.py

@@ -0,0 +1,261 @@
+"""URL-state helpers for paginated + filterable HTML tables.
+
+Every table page pixie shows (Catalog, Machines, Events) reads a
+freeform search string + a page number off the query string, filters
+the row set, and slices it before rendering. State lives in the URL
+so a page is bookmarkable and survives a plain form re-submit.
+
+Three helpers cover the surface:
+
+- :func:`parse_pagination` reads ``?page=<N>&per_page=<N>``, clamps
+  ``per_page`` to the dropdown values, computes the offset + limit,
+  and returns a :class:`PageState` the template uses to render the
+  page-number footer + "Showing X-Y of Z" line.
+- :func:`filter_rows` applies a case-insensitive substring match to
+  a caller-supplied set of attribute paths. Missing attributes /
+  ``None`` values just fall through so a row with a blank field is
+  never matched by a non-empty ``q``.
+- :func:`build_query_string` merges + strips empties + emits a
+  URL-encoded query for header / pagination links so an active
+  ``?q=`` survives the click through to page 2.
+
+No FastAPI / Starlette dependency: tests pass a plain dict.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+# Page-size choices surfaced as the per-page dropdown. The first
+# entry is the default. Kept small so the table fits a laptop
+# without a 200-row page forcing manual scrolling.
+PER_PAGE_CHOICES: tuple[int, ...] = (10, 25, 50, 100)
+DEFAULT_PER_PAGE = PER_PAGE_CHOICES[1]  # 25
+
+# Number of page buttons shown around the current page in the
+# footer. ``window=2`` gives ``... 3 4 [5] 6 7 ...`` (the standard
+# Bootstrap pagination shape).
+_NUMBERED_WINDOW = 2
+
+
+@dataclass(frozen=True)
+class SortState:
+    """Parsed ``?sort=<col>&dir=asc|desc``.
+
+    ``column`` is one of the caller-supplied allowlist keys (the
+    URL-visible name, not necessarily the SQL identifier).
+    ``direction`` is ``"asc"`` or ``"desc"``. ``key_expr`` is
+    whatever the allowlist mapped the column to -- typically an
+    attribute name for in-memory sort, or a SQL fragment for the
+    events-table SQL path. Kept schema-agnostic so pixie's
+    in-memory sort and a later SQL-side sort share the parser.
+    """
+
+    column: str
+    direction: str  # "asc" | "desc"
+    key_expr: str
+
+    def is_active(self, column: str) -> bool:
+        return self.column == column
+
+    def next_direction(self, column: str) -> str:
+        """For a header link on ``column``: the direction the click
+        should send. Clicking the currently-active column flips
+        direction; clicking any other column starts at ``asc``.
+        """
+        return "desc" if self.is_active(column) and self.direction == "asc" else "asc"
+
+
+@dataclass(frozen=True)
+class PageState:
+    """Parsed ``?page=<N>&per_page=<N>`` + computed totals."""
+
+    page: int  # 1-indexed; clamped to [1, last_page]
+    per_page: int  # one of PER_PAGE_CHOICES
+    total: int  # rows matching the (post-filter) input
+    offset: int  # index of the first row on this page
+    limit: int  # equals per_page
+
+    @property
+    def last_page(self) -> int:
+        # An empty table still has page 1 so ``page X of 1`` reads
+        # sensibly rather than ``X of 0``.
+        if self.total <= 0:
+            return 1
+        return (self.total + self.per_page - 1) // self.per_page
+
+    @property
+    def first_row(self) -> int:
+        """1-indexed row number of the first row on this page (0 if
+        the table is empty)."""
+        if self.total <= 0:
+            return 0
+        return self.offset + 1
+
+    @property
+    def last_row(self) -> int:
+        """1-indexed row number of the last row on this page."""
+        if self.total <= 0:
+            return 0
+        return min(self.offset + self.per_page, self.total)
+
+    @property
+    def has_prev(self) -> bool:
+        return self.page > 1
+
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.last_page
+
+    def numbered_pages(self) -> list[int]:
+        """The page-number buttons to render in the footer.
+
+        Up to ``2 * _NUMBERED_WINDOW + 1`` centred on the current
+        page and clamped to ``[1, last_page]``. The template adds
+        explicit Prev / Next / First / Last outside this window so
+        very large tables don't grow a 50-button footer.
+        """
+        lo = max(1, self.page - _NUMBERED_WINDOW)
+        hi = min(self.last_page, self.page + _NUMBERED_WINDOW)
+        return list(range(lo, hi + 1))
+
+
+def parse_pagination(
+    params: Mapping[str, str],
+    *,
+    total: int,
+    default_per_page: int = DEFAULT_PER_PAGE,
+) -> PageState:
+    """Parse ``?page=<N>&per_page=<N>``, clamp to sane values, return
+    a :class:`PageState`. ``total`` is the post-filter row count."""
+    raw_per = params.get("per_page") or ""
+    try:
+        per_candidate = int(raw_per)
+    except ValueError:
+        per_candidate = default_per_page
+    per_page = per_candidate if per_candidate in PER_PAGE_CHOICES else default_per_page
+
+    if total < 0:
+        total = 0
+    last_page = max(1, (total + per_page - 1) // per_page) if total > 0 else 1
+
+    raw_page = params.get("page") or ""
+    try:
+        page_candidate = int(raw_page)
+    except ValueError:
+        page_candidate = 1
+    page = max(1, min(last_page, page_candidate))
+
+    offset = (page - 1) * per_page
+    return PageState(page=page, per_page=per_page, total=total, offset=offset, limit=per_page)
+
+
+def parse_sort(
+    params: Mapping[str, str],
+    *,
+    allowed: Mapping[str, str],
+    default_column: str,
+    default_direction: str = "asc",
+) -> SortState:
+    """Parse ``?sort=...&dir=...`` against a per-page column allowlist.
+
+    ``allowed`` maps the column-key the operator sees in the URL to
+    whatever the caller wants to sort on -- an attribute path for
+    in-memory sort, or a SQL fragment for SQL-side sort. Anything
+    not in ``allowed`` falls back to ``default_column``. The
+    allowlist is the safety guard: no operator-controlled string
+    ever flows into an eval / SQL context.
+    """
+    if default_column not in allowed:
+        raise ValueError(
+            f"default_column {default_column!r} must be in the allowlist {sorted(allowed)!r}"
+        )
+    raw_col = params.get("sort") or ""
+    column = raw_col if raw_col in allowed else default_column
+    raw_dir = (params.get("dir") or "").lower()
+    direction = raw_dir if raw_dir in ("asc", "desc") else default_direction
+    return SortState(column=column, direction=direction, key_expr=allowed[column])
+
+
+def sort_rows(rows: Iterable[Any], sort: SortState) -> list[Any]:
+    """In-memory sort helper: pull the value at ``sort.key_expr`` (a
+    dotted attribute path via :func:`_resolve`) off each row and
+    order by it. Missing / None values sort as an empty string so a
+    row with a blank field lands consistently rather than raising."""
+
+    def _key(row: Any) -> tuple[int, str]:
+        val = _resolve(row, sort.key_expr)
+        if val is None:
+            return (1, "")  # missing values sort after present ones on asc
+        return (0, str(val).lower())
+
+    return sorted(rows, key=_key, reverse=(sort.direction == "desc"))
+
+
+def _resolve(row: Any, path: str) -> Any:
+    """Best-effort attribute / mapping-key lookup along a dotted
+    path. Returns ``None`` on any missing hop so callers can treat
+    ``None`` uniformly.
+    """
+    cur: Any = row
+    for part in path.split("."):
+        if cur is None:
+            return None
+        cur = cur.get(part) if isinstance(cur, Mapping) else getattr(cur, part, None)
+    return cur
+
+
+def filter_rows(rows: Iterable[Any], q: str, *, fields: Iterable[str]) -> list[Any]:
+    """Case-insensitive substring search across ``fields`` on each
+    row. An empty ``q`` returns the input unchanged. ``fields`` is a
+    tuple of dotted paths that :func:`_resolve` walks -- attributes
+    on dataclasses, keys on dicts, mix-and-match.
+
+    A row matches when the query appears (as a substring, lowercase)
+    in ANY of the resolved field values. Numeric / non-string values
+    are coerced with ``str()`` so a search on ``12345`` hits a
+    ``size_bytes`` int.
+    """
+    q_clean = (q or "").strip().lower()
+    if not q_clean:
+        return list(rows)
+    field_list = tuple(fields)
+    kept: list[Any] = []
+    for row in rows:
+        for path in field_list:
+            val = _resolve(row, path)
+            if val is None:
+                continue
+            if q_clean in str(val).lower():
+                kept.append(row)
+                break
+    return kept
+
+
+def build_query_string(
+    base: Mapping[str, str | None],
+    overrides: Mapping[str, str | None] | None = None,
+) -> str:
+    """Merge ``base`` + ``overrides``, drop empty / None values, and
+    return a URL-encoded query string suitable for pagination links.
+    Caller wraps with ``"?"`` when the returned string is non-empty.
+
+    ``None`` in ``overrides`` REMOVES the key (handy for "clear this
+    filter" links). Empty-string values are dropped so links don't
+    accumulate ``?q=&page=`` noise. Stable key order so two callers
+    producing the same URL emit byte-identical strings.
+    """
+    merged: dict[str, str] = {}
+    for k, v in base.items():
+        if v:
+            merged[k] = str(v)
+    if overrides:
+        for k, v in overrides.items():
+            if v is None or v == "":
+                merged.pop(k, None)
+            else:
+                merged[k] = str(v)
+    return urllib.parse.urlencode(sorted(merged.items()))

pixie/web/_templates/_partials/page_description.html

@@ -0,0 +1,22 @@
+{# Per-page description strip.
+
+   Every operator page opens with a one-paragraph orientation of
+   "what you are looking at, how it changes, what you can do." The
+   goal is that a new operator hitting pixie for the first time can
+   read a page's description and know its purpose without having to
+   click around, and that a returning operator can skip it entirely.
+
+   Called with:
+     icon        Bootstrap Icons name (no ``bi-`` prefix)
+     text        One or two-sentence orientation paragraph
+
+   Ported from bty-web's ``page_description`` block. The visual shape
+   (left accent border + light-tinted background) is chosen so the
+   strip reads as a distinct "meta" element, not just another card. #}
+
+{% macro page_description(icon, text) %}
+<div class="page-description mb-3" role="doc-subtitle">
+    <i class="bi bi-{{ icon }} text-primary me-2" aria-hidden="true"></i>
+    <span class="text-body-secondary">{{ text }}</span>
+</div>
+{% endmacro %}

pixie/web/_templates/_partials/recent_events.html

@@ -0,0 +1,47 @@
+{# Small events card used on every list page (catalog / machines) and
+   on machine-detail. Renders up to N events (the caller picks how
+   many) with a link to /ui/events for the full log. Called with:
+
+     events         (list of Event rows)
+     scope          ("catalog" | "machine" | ...)  -- shown in the
+                    header + "all events" link's ?filter
+     empty_message  optional custom prompt when events is empty
+#}
+{% macro recent_events_card(events, scope, empty_message="") %}
+<div class="card shadow-sm mb-4">
+    <div class="card-header bg-light d-flex align-items-center">
+        <h2 class="h6 mb-0">
+            <i class="bi bi-clock-history me-2"></i>Recent {{ scope }} events
+        </h2>
+        <a href="/ui/events" class="ms-auto small">All events</a>
+    </div>
+    {% if events %}
+    <div class="table-responsive">
+        <table class="table table-sm table-hover align-middle mb-0">
+            <thead>
+                <tr>
+                    <th scope="col" class="small text-muted" style="width: 12rem;">When</th>
+                    <th scope="col" class="small text-muted" style="width: 16rem;">Kind</th>
+                    <th scope="col" class="small text-muted">Summary</th>
+                </tr>
+            </thead>
+            <tbody>
+                {% for e in events %}
+                <tr>
+                    <td class="small text-muted text-nowrap">{{ e.ts | fmt_ts }}</td>
+                    <td class="small"><code>{{ e.kind }}</code></td>
+                    <td class="small">{{ e.summary or "" }}</td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+    </div>
+    {% else %}
+    <div class="card-body">
+        <p class="text-muted small mb-0">
+            {{ empty_message or "No " ~ scope ~ " events recorded yet." }}
+        </p>
+    </div>
+    {% endif %}
+</div>
+{% endmacro %}

pixie/web/_templates/_partials/table_helpers.html

@@ -0,0 +1,189 @@
+{# Table helpers -- ported from bty's ``_table_macros.html`` shape so
+   an operator moving between the two consoles reads the same
+   toolbar layout.
+
+   Callers pass a :class:`SortState`, a :class:`PageState`, and a
+   ``preserved`` dict of query params to carry across every link
+   (filter survives sort clicks; sort survives pagination clicks;
+   per_page survives everything). The macros are shape-agnostic:
+   they don't care whether the underlying rows come from an
+   in-memory list or a SQL LIMIT/OFFSET query.
+
+   Layout intent:
+
+   * The filter form + the pagination live TOGETHER on the card
+     header row -- NOT in a separate subnav or a card footer. That
+     way the operator's eye lands on "who am I looking at" (the
+     title label), "what am I looking for" (the filter), and "how
+     many are there" (the pagination) in one horizontal sweep.
+   * Column headers are clickable ``<a>``s inside ``<th>``: click
+     to sort, click again to reverse. Active column shows a solid
+     up/down triangle; inactive columns show a faded up-down glyph
+     to hint they are sortable.
+
+   Macros:
+
+   * ``search_input(name_or_url, q, preserved, placeholder)`` --
+     inline search-and-clear form; sits on the LEFT of the card
+     header row.
+   * ``sort_header(label, column, sort, preserved, th_attrs)`` --
+     a ``<th>`` cell whose contents click to sort.
+   * ``pagination_inline(page, preserved, label)`` -- the totals
+     line + numbered nav + per-page selector; sits on the RIGHT
+     of the card header row via ``ms-auto``. #}
+
+
+{% macro search_input(action, q, preserved, placeholder='freeform filter') -%}
+{# Inline search + Search + Clear. Uses ``type="search"`` so
+   browsers render the built-in clear-X inside the box; the ``m-0``
+   + ``flex-grow-1`` shape survives a narrow viewport by wrapping
+   below the pagination.
+
+   ``preserved`` is a dict of {name: value} query params to preserve
+   as hidden inputs. ``page`` is intentionally NOT preserved -- a
+   fresh query resets to page 1. #}
+<form method="get" action="{{ action }}"
+      class="d-flex align-items-center gap-2 m-0 flex-grow-1"
+      style="min-width: 16rem;">
+    {% for k, v in preserved.items() %}
+        {% if v and k not in ('q', 'page') %}
+        <input type="hidden" name="{{ k }}" value="{{ v }}">
+        {% endif %}
+    {% endfor %}
+    <label for="filter-q" class="text-nowrap text-muted small mb-0">
+        <i class="bi bi-funnel"></i> Filter:
+    </label>
+    <input type="search" name="q" id="filter-q" value="{{ q or '' }}"
+           class="form-control form-control-sm flex-grow-1"
+           placeholder="{{ placeholder }}"
+           aria-label="Filter this table">
+    <button type="submit" class="btn btn-sm btn-outline-secondary"
+            title="Search" aria-label="Apply filter">
+        <i class="bi bi-search" aria-hidden="true"></i>
+    </button>
+    {% if q %}
+    <a href="?{{ _qs(preserved, {'q': None, 'page': None}) }}"
+       class="btn btn-sm btn-link text-nowrap"
+       title="Clear filter">Clear</a>
+    {% endif %}
+</form>
+{%- endmacro %}
+
+
+{% macro sort_header(label, column, sort, preserved, th_attrs='') -%}
+{# Sortable column header. Clicking flips direction on the active
+   column or starts a fresh asc on any other column.
+
+   Arrow indicator convention (matches bty):
+
+   * Active + asc  -> filled ▲ in accent colour
+   * Active + desc -> filled ▼ in accent colour
+   * Inactive       -> faded ↕ so the header still telegraphs
+     "this is sortable" without competing with the active one. #}
+{% set qs = _qs(preserved, {'sort': column, 'dir': sort.next_direction(column), 'page': None}) %}
+<th{% if th_attrs %} {{ th_attrs|safe }}{% endif %}>
+    <a href="?{{ qs }}" class="text-decoration-none text-reset"
+       aria-label="Sort by {{ label }}">
+        {{ label }}
+        {% if sort.is_active(column) %}
+        <span class="text-primary" aria-hidden="true">{% if sort.direction == 'asc' %}&#9650;{% else %}&#9660;{% endif %}</span>
+        {% else %}
+        <span class="text-muted" aria-hidden="true">&#8645;</span>
+        {% endif %}
+    </a>
+</th>
+{%- endmacro %}
+
+
+{% macro pagination_inline(page, preserved, label='rows') -%}
+{# Compact pagination that fits on one card-header row alongside a
+   filter form. Renders the "1-25 of 200 events" line as inline
+   muted text, then the Bootstrap ``pagination pagination-sm`` list
+   (« « ‹ 1 2 [3] 4 5 › » »), then the per-page selector.
+
+   The pagination list follows bty's shape: first/prev/window/next/
+   last with ``…`` ellipses when the window doesn't touch the ends.
+   Numbered ``.page-link`` inside ``<li class="page-item">`` is the
+   Bootstrap-native shape (not a btn-group). #}
+<div class="d-flex flex-wrap align-items-center gap-2 ms-auto">
+    <small class="text-muted">
+        {% if page.total == 0 %}
+        No {{ label }}.
+        {% else %}
+        <strong>{{ page.first_row }}</strong>&ndash;<strong>{{ page.last_row }}</strong>
+        of <strong>{{ page.total }}</strong> {{ label }}
+        {% endif %}
+    </small>
+
+    {% if page.last_page > 1 %}
+    <ul class="pagination pagination-sm mb-0">
+        <li class="page-item{% if not page.has_prev %} disabled{% endif %}">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': 1}) }}"
+               aria-label="First page">&laquo;&laquo;</a>
+        </li>
+        <li class="page-item{% if not page.has_prev %} disabled{% endif %}">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': page.page - 1}) }}"
+               aria-label="Previous page">&laquo;</a>
+        </li>
+        {% set nums = page.numbered_pages() %}
+        {% if nums[0] > 1 %}
+        <li class="page-item">
+            <a class="page-link" href="?{{ _qs(preserved, {'page': 1}) }}">1</a>
+        </li>
+        {% if nums[0] > 2 %}
+        <li class="page-item disabled"><span class="page-link">&hellip;</span></li>
+        {% endif %}
+        {% endif %}
+        {% for n in nums %}
+        <li class="page-item{% if n == page.page %} active{% endif %}">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': n}) }}"
+               {% if n == page.page %}aria-current="page"{% endif %}>{{ n }}</a>
+        </li>
+        {% endfor %}
+        {% if nums[-1] < page.last_page %}
+        {% if nums[-1] < page.last_page - 1 %}
+        <li class="page-item disabled"><span class="page-link">&hellip;</span></li>
+        {% endif %}
+        <li class="page-item">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': page.last_page}) }}">{{ page.last_page }}</a>
+        </li>
+        {% endif %}
+        <li class="page-item{% if not page.has_next %} disabled{% endif %}">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': page.page + 1}) }}"
+               aria-label="Next page">&raquo;</a>
+        </li>
+        <li class="page-item{% if not page.has_next %} disabled{% endif %}">
+            <a class="page-link"
+               href="?{{ _qs(preserved, {'page': page.last_page}) }}"
+               aria-label="Last page">&raquo;&raquo;</a>
+        </li>
+    </ul>
+    {% endif %}
+
+    {# Per-page selector as a GET-form: submits with all preserved
+       params as hidden inputs but drops ``page`` so the choice
+       always lands on page 1. #}
+    <form method="get" class="d-flex align-items-center gap-1 mb-0">
+        {% for k, v in preserved.items() %}
+            {% if v and k not in ('per_page', 'page') %}
+            <input type="hidden" name="{{ k }}" value="{{ v }}">
+            {% endif %}
+        {% endfor %}
+        <select name="per_page"
+                class="form-select form-select-sm"
+                style="width: auto;"
+                onchange="this.form.submit()"
+                aria-label="Rows per page">
+            {% for choice in (10, 25, 50, 100) %}
+            <option value="{{ choice }}"
+                    {% if choice == page.per_page %}selected{% endif %}>{{ choice }}</option>
+            {% endfor %}
+        </select>
+    </form>
+</div>
+{%- endmacro %}