pushmetrics-cli 0.1.0__py3-none-any.whl

pm/client/runs.py

@@ -0,0 +1,134 @@
+"""Noteflow run endpoints — fetching run metadata and per-task results."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pm.client.base import CrudClient, _unwrap_result, raise_for_status
+from pm.models.runs import Run, RunLog, RunTaskResult
+
+
+def _rison_value(s: str) -> str:
+    """Encode a string for inclusion as a Rison value.
+
+    Bare identifiers pass through unquoted; anything else gets
+    single-quote-wrapped with ``!`` / ``'`` escaped per the Rison spec.
+    Mirrors the helper in ``commands/integrations.py`` (the client layer must
+    not import from the commands layer).
+
+    A bare Rison id must NOT start with a digit (or ``-``/``.``): the
+    parser then commits to a number and fails on the first non-numeric
+    char. Uids/UUIDs routinely start with a digit — ``pm run logs
+    12490fe3-…`` was rejected with "Not a valid rison/json argument"
+    (E2E verification 2026-07-16), and any ``pm run list
+    --report=<uid>`` with a digit-leading uid hit the same. Quote
+    unless the first char is a letter or underscore.
+    """
+    if (
+        s
+        and (s[0].isalpha() or s[0] == "_")
+        and all(c.isalnum() or c in "_-." for c in s)
+    ):
+        return s
+    return "'" + s.replace("!", "!!").replace("'", "!'") + "'"
+
+
+class RunsClient(CrudClient[Run]):
+    base_path = "/api/v1/noteflow_run"
+    log_path = "/api/v1/noteflow_run_log"
+    model = Run
+
+    def list(
+        self,
+        limit: Optional[int] = None,
+        *,
+        report_uid: Optional[str] = None,
+        last_days: Optional[int] = None,
+        status: Optional[str] = None,
+    ) -> List[Run]:
+        """List recent noteflow runs in the current workspace.
+
+        Backend's `base_order` is `(id, desc)` so the list is already sorted
+        most-recent-first. Pass `limit` to override FAB's default page size
+        (~25) up to `max_page_size` of 5000.
+
+        Optional server-side filters (mirror the backend ``search_filters``):
+          - ``report_uid`` — only runs of one report (``FilterReport``).
+          - ``last_days`` — only runs created within the last N days
+            (``FilterLessThanDaysAgo``; N=1 ≈ since yesterday midnight).
+          - ``status`` — exact status match (e.g. ``failed`` / ``success``).
+        """
+        filters = []
+        if report_uid is not None:
+            filters.append(f"(col:report,opr:rel_r_nf,value:{_rison_value(report_uid)})")
+        if last_days is not None:
+            filters.append(f"(col:created_on,opr:ltd,value:{int(last_days)})")
+        if status is not None:
+            filters.append(f"(col:status,opr:eq,value:{_rison_value(status)})")
+
+        bits = []
+        if filters:
+            bits.append(f"filters:!({','.join(filters)})")
+        if limit is not None:
+            bits.append("page:0")
+            bits.append(f"page_size:{int(limit)}")
+        params = {"q": f"({','.join(bits)})"} if bits else None
+        return super().list(params=params)
+
+    def results(self, run_uid: str) -> List[RunTaskResult]:
+        """Fetch per-task (per-block) results for a run."""
+        resp = self.session.get(f"{self.base_path}/{run_uid}/get_task_results")
+        raise_for_status(resp)
+        body = resp.json()
+        if isinstance(body, dict):
+            raw = body.get("result", []) if "result" in body else [body]
+        else:
+            raw = body
+        return [RunTaskResult.model_validate(item) for item in raw]
+
+    def logs(
+        self,
+        *,
+        flow_run_id: Optional[str] = None,
+        noteflow_run_id: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> List[RunLog]:
+        """Fetch execution log lines for a run.
+
+        Filter by ``noteflow_run_id`` or ``flow_run_id``:
+          - ``noteflow_run_id`` is the stable per-run key — it does not
+            change across retries, so it returns ALL attempts' logs. Prefer
+            it for "every log line for this run".
+          - ``flow_run_id`` is the per-attempt key — a run's flow_run_id can
+            change between retry attempts, so filtering on it returns only
+            the matching attempt's logs.
+
+        Logs come back oldest-first (backend ``base_order`` is ``(id, asc)``).
+        At least one filter is required.
+        """
+        if flow_run_id is None and noteflow_run_id is None:
+            raise ValueError(
+                "RunsClient.logs requires flow_run_id or noteflow_run_id"
+            )
+
+        filters = []
+        if flow_run_id is not None:
+            filters.append(
+                f"(col:flow_run_id,opr:frid_eq,value:{_rison_value(flow_run_id)})"
+            )
+        if noteflow_run_id is not None:
+            filters.append(
+                f"(col:noteflow_run_id,opr:frid_eq,value:{int(noteflow_run_id)})"
+            )
+        bits = []
+        if filters:
+            bits.append(f"filters:!({','.join(filters)})")
+        if limit is not None:
+            bits.append(f"page_size:{int(limit)}")
+        params = {"q": f"({','.join(bits)})"} if bits else None
+
+        resp = self.session.get(f"{self.log_path}/", params=params)
+        raise_for_status(resp)
+        raw = _unwrap_result(resp.json(), default=[])
+        if not isinstance(raw, list):
+            raw = [raw]
+        return [RunLog.model_validate(item) for item in raw]

pm/client/saved_blocks.py

@@ -0,0 +1,13 @@
+"""Saved block (template) endpoints.
+
+Backend supports full CRUD but only `parameters_schema` is editable.
+"""
+from __future__ import annotations
+
+from pm.client.base import CrudClient
+from pm.models.saved_blocks import SavedBlock
+
+
+class SavedBlocksClient(CrudClient[SavedBlock]):
+    base_path = "/api/v1/saved_block"
+    model = SavedBlock

pm/client/tableau.py

@@ -0,0 +1,108 @@
+"""Tableau integration endpoints — view/workbook discovery + view details.
+
+Scoped to a Tableau integration in the current workspace (the
+``integration_uid`` identifies which Tableau instance to talk to). The
+backend mounts these under ``/api/v1/integration/tableau/<integration_uid>/...``
+— a separate resource from the generic ``/api/v1/integration`` CRUD, with
+its own auth-token-refresh and Tableau-specific concerns.
+
+Used by ``pm tableau search`` (list views/workbooks) and ``pm tableau view``
+(get one view's details). These are direct-API ops — they don't create
+blocks. The block-lifecycle path is ``pm tableau create`` + ``pm tableau
+run`` on a block whose content_json points at a specific view_id.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pm.client.base import _unwrap_result, raise_for_status
+
+
+class TableauClient:
+    """HTTP wrapper for the workspace's Tableau integration API.
+
+    Every method takes ``integration_uid`` — the Tableau integration to
+    talk to. Workspaces with multiple Tableau integrations need an explicit
+    pick (no implicit-default behaviour today; we can layer that on later
+    if it proves common).
+    """
+
+    base_path = "/api/v1/integration/tableau"
+
+    def __init__(self, session):
+        self.session = session
+
+    def list_views(
+        self,
+        integration_uid: str,
+        *,
+        keyword: Optional[str] = None,
+        workbook_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """List Tableau views available through this integration.
+
+        ``keyword`` is a server-side substring filter on view name (the
+        backend passes it to the Tableau REST API). ``workbook_id``
+        narrows the result set to views inside a single workbook. Returns
+        a list of dicts — exact shape mirrors what the Tableau REST API
+        returns through the backend's ``get_views`` helper.
+        """
+        params: Dict[str, str] = {}
+        if keyword:
+            params["keyword"] = keyword
+        if workbook_id:
+            params["workbook_id"] = workbook_id
+        resp = self.session.get(
+            f"{self.base_path}/{integration_uid}/view",
+            params=params or None,
+        )
+        raise_for_status(resp)
+        body = resp.json() if resp.text else {}
+        results = body.get("results") if isinstance(body, dict) else None
+        if results is None:
+            results = _unwrap_result(body, default=[]) or []
+        return results if isinstance(results, list) else [results]
+
+    def list_workbooks(
+        self,
+        integration_uid: str,
+        *,
+        keyword: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """List Tableau workbooks available through this integration.
+
+        Same shape as ``list_views`` minus the workbook_id filter — a
+        workbook is the parent of views, so it doesn't have one of its own.
+        """
+        params: Dict[str, str] = {}
+        if keyword:
+            params["keyword"] = keyword
+        resp = self.session.get(
+            f"{self.base_path}/{integration_uid}/workbook",
+            params=params or None,
+        )
+        raise_for_status(resp)
+        body = resp.json() if resp.text else {}
+        results = body.get("results") if isinstance(body, dict) else None
+        if results is None:
+            results = _unwrap_result(body, default=[]) or []
+        return results if isinstance(results, list) else [results]
+
+    def get_view(
+        self,
+        integration_uid: str,
+        view_id: str,
+    ) -> Dict[str, Any]:
+        """Fetch one Tableau view's metadata.
+
+        Returns whatever the backend's ``get_view(integration, view_id)``
+        produces — typically a dict with id, name, workbook_id, content_url,
+        etc. Useful for drilling into a search result before creating a
+        Tableau block that points at it.
+        """
+        resp = self.session.get(
+            f"{self.base_path}/{integration_uid}/view/{view_id}",
+        )
+        raise_for_status(resp)
+        body = resp.json() if resp.text else {}
+        return _unwrap_result(body, default={}) or {}

pm/client/users.py

@@ -0,0 +1,71 @@
+"""User endpoints."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pm.client.base import CrudClient, _unwrap_result, raise_for_status
+from pm.models.users import User
+
+
+class UsersClient(CrudClient[User]):
+    base_path = "/api/v1/user"
+    model = User
+
+    def current(self) -> User:
+        """The authenticated user (custom endpoint, not part of CRUD)."""
+        resp = self.session.get("/api/v1/user/current")
+        raise_for_status(resp)
+        return User.model_validate(resp.json())
+
+    def create(
+        self,
+        data: Dict[str, Any],
+        *,
+        skip_welcome_email: bool = False,
+    ) -> tuple:
+        """Create (invite) a user, or attach an existing one to the workspace.
+
+        ``skip_welcome_email=True`` adds ``?skip_welcome_email=true`` so
+        the backend's ``post_add`` hook does not call
+        ``send_welcome_to_workspace_email``. Use for smoke tests and
+        scripted onboarding to avoid sending mail to test addresses.
+
+        Returns ``(user, action)`` where ``action`` is one of:
+
+          - ``"created"`` — brand-new user record was inserted
+          - ``"added_to_workspace"`` — existing user attached to current workspace
+          - ``"no_op"`` — user already in this workspace, no state change
+        """
+        params: Optional[Dict[str, str]] = None
+        if skip_welcome_email:
+            params = {"skip_welcome_email": "true"}
+        resp = self.session.post(f"{self.base_path}/", json=data, params=params)
+        raise_for_status(resp)
+        body = resp.json() if resp.text else {}
+        action = body.get("action") if isinstance(body, dict) else None
+        user = self.model.model_validate(_unwrap_result(body))
+        return user, action
+
+    def remove_from_workspace(
+        self,
+        user_uid: str,
+        workspace_uid: Optional[str] = None,
+    ) -> None:
+        """Remove a user from a workspace.
+
+        Hits ``DELETE /api/v1/user/<user_uid>/remove_from_workspace/`` —
+        or ``/remove_from_workspace/<workspace_uid>`` when a specific
+        target is given. Without ``workspace_uid``, the backend removes
+        from the active session's workspace.
+
+        Side effects (mirroring the backend ``remove_from_workspace``
+        handler): the user's workspace roles for the target workspace
+        are stripped. If this was their last workspace they are also
+        deactivated, removed from the organization, anonymised, and
+        deleted from Auth0.
+        """
+        path = f"{self.base_path}/{user_uid}/remove_from_workspace/"
+        if workspace_uid:
+            path = f"{path}{workspace_uid}"
+        resp = self.session.delete(path)
+        raise_for_status(resp)

pm/client/webhooks.py

@@ -0,0 +1,43 @@
+"""Webhook endpoints (full CRUD).
+
+Note: backend `add_columns` / `edit_columns` JSON-stringify `recipients`/
+`details`/`slack_recipients` on input. The CLI accepts dict/list and
+serializes to JSON before sending.
+
+**Backend gap (filed as a follow-up):** `WebhookRestApi` (`superset/
+pushmetrics/views/webhook/api.py`) does not define `list_columns`, so
+FAB's `/webhook/` list endpoint returns only the model's primary key (`id`)
+per row. All other fields come back null in the response. There's no
+client-side workaround — FAB filters any requested `columns:!(...)` against
+the server-declared `list_columns`. To fix: add `list_columns = show_columns`
+to `WebhookRestApi`. Until then, use `pm webhooks get <uid>` (the single-item
+endpoint uses `show_columns` and returns the full record).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+from pm.client.base import CrudClient
+from pm.models.webhooks import Webhook
+
+
+def _serialize_payload(data: Dict[str, Any]) -> Dict[str, Any]:
+    """JSON-stringify the dict/list fields the backend expects as strings."""
+    out = dict(data)
+    for key in ("details", "recipients", "slack_recipients"):
+        value = out.get(key)
+        if value is not None and not isinstance(value, str):
+            out[key] = json.dumps(value)
+    return out
+
+
+class WebhooksClient(CrudClient[Webhook]):
+    base_path = "/api/v1/webhook"
+    model = Webhook
+
+    def create(self, data: Dict[str, Any]) -> Webhook:
+        return super().create(_serialize_payload(data))
+
+    def update(self, uid: str, data: Dict[str, Any]) -> Webhook:
+        return super().update(uid, _serialize_payload(data))

pm/client/workspaces.py

@@ -0,0 +1,34 @@
+"""Workspace endpoints.
+
+Workspace selection is **server-side state** in the Flask session. Switching
+issues GET /api/v1/workspace/<pk>/switch which mutates the session, so all
+subsequent calls run against the new workspace (RLS enforced).
+"""
+from __future__ import annotations
+
+from pm.client.base import CrudClient, PMApiError, raise_for_status
+from pm.models.workspaces import Workspace
+
+
+class WorkspacesClient(CrudClient[Workspace]):
+    base_path = "/api/v1/workspace"
+    model = Workspace
+
+    def current(self) -> Workspace:
+        resp = self.session.get("/api/v1/workspace/current")
+        raise_for_status(resp)
+        return Workspace.model_validate(resp.json())
+
+    def switch(self, uid: str) -> Workspace:
+        """Switch the active workspace by UID. Resolves UID -> integer PK via list."""
+        for ws in self.list():
+            if ws.uid == uid:
+                pk = ws.id
+                if pk is None:
+                    raise PMApiError(500, f"Workspace {uid} has no id field")
+                resp = self.session.get(f"/api/v1/workspace/{pk}/switch")
+                raise_for_status(resp)
+                self.session.creds.last_workspace_uid = uid
+                self.session.persist()
+                return ws
+        raise PMApiError(404, f"Workspace with uid {uid!r} not found in your accessible list.")