mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/console.py

@@ -0,0 +1,178 @@
+"""`mobster run` on a terminal: one readable line per step instead of JSON."""
+
+import sys
+import threading
+import time
+
+from .narrate import Launch, Narrator, Note, Outcome, Step, facts, seconds, status_glyph
+from .style import SPINNER, Palette, color_enabled
+
+
+class ConsoleRenderer:
+    """``emit(event)`` for ``Agent``: prints each step once it has an outcome."""
+
+    TONE_ROLES = {"success": "green", "error": "red", "warning": "amber", "review": "accent", "neutral": "muted"}
+
+    def __init__(self, stream=None, *, color=None, live=None, preview=False):
+        self.stream = stream or sys.stdout
+        self.paint = Palette(color_enabled(self.stream) if color is None else color)
+        self.live = self.stream.isatty() if live is None else live
+        self.preview = preview
+        self.narrator = Narrator()
+        self.printed = set()
+        self.lock = threading.Lock()
+        self.transient = False
+        self.frame = 0
+        self.stopped = threading.Event()
+        self.ticker = None
+        self.started = time.monotonic()
+        self.result = None
+        self.paused = False
+
+    def _clear(self):
+        if self.transient:
+            self.stream.write("\r\033[2K")
+            self.transient = False
+
+    def line(self, text=""):
+        with self.lock:
+            self._clear()
+            self.stream.write(text + "\n")
+            self.stream.flush()
+
+    def start(self, goal, where=""):
+        p = self.paint
+        head = p("❯ ", "accent", "bold") + p(goal, "bold")
+        if where:
+            head += "  " + p(where, "faint")
+        self.line(head)
+        if self.live:
+            self.ticker = threading.Thread(target=self._tick, name="mobster-console", daemon=True)
+            self.ticker.start()
+
+    def close(self):
+        self.stopped.set()
+        if self.ticker is not None:
+            self.ticker.join(1)
+        with self.lock:
+            self._clear()
+            self.stream.flush()
+
+    def _tick(self):
+        while not self.stopped.wait(.08):
+            if self.paused:
+                continue
+            with self.lock:
+                self.frame += 1
+                step = self.narrator.step
+                doing = "Starting"
+                if step is not None and step.key not in self.printed:
+                    doing = {"acting": f"{step.title}…", "thinking": "Deciding…" if step.elements is not None
+                             else "Reading the screen…"}.get(step.state, "Reading the screen…")
+                elapsed = seconds((time.monotonic() - self.started) * 1000)
+                text = (self.paint(SPINNER[self.frame % len(SPINNER)], "accent") + " "
+                        + self.paint(doing, "muted") + self.paint(f"  {elapsed}   ctrl+c to stop", "faint"))
+                self.stream.write("\r\033[2K" + text)
+                self.stream.flush()
+                self.transient = True
+
+    def __call__(self, event):
+        if not isinstance(event, dict):
+            return
+        event = {**event, "timestamp": time.time() * 1000}
+        kind = event.get("event")
+        if kind == "result":
+            self.result = event
+            self._flush_steps()
+            self._outcome(Outcome("outcome", event.get("status") or "error", event))
+            return
+        for item in self.narrator.feed(event):
+            if isinstance(item, Step):
+                if kind in {"observation_after_action", "action_not_dispatched", "completion_check"} or (
+                        kind == "decision" and item.operation in {"WAIT", "BLOCKED"}):
+                    self._flush_steps(upto=item)
+            elif isinstance(item, Launch) and item.done:
+                self.line("  " + self.paint("● ", "green") + self.paint(f"Opened {item.app}", "bold"))
+            elif isinstance(item, Note):
+                role = {"warning": "amber", "error": "red"}.get(item.tone, "muted")
+                self.line("  " + self.paint(f"! {item.text}" if item.tone != "neutral" else f"– {item.text}", role))
+        if kind == "observation":
+            # A new step began: the previous one is as finished as it will get.
+            steps = [item for item in self.narrator.items if isinstance(item, Step)]
+            for step in steps[:-1]:
+                self._print_step(step)
+
+    def _flush_steps(self, upto=None):
+        for item in self.narrator.items:
+            if isinstance(item, Step):
+                self._print_step(item)
+            if item is upto:
+                break
+
+    def _print_step(self, step):
+        if step.key in self.printed or step.operation is None:
+            return
+        self.printed.add(step.key)
+        p = self.paint
+        state = step.state
+        glyph = (("✗", "red") if state == "failed" else ("○", "faint") if state == "skipped" and not self.preview
+                 else ("✓", "green") if step.operation == "DONE"
+                 else ("○", "muted") if state == "stalled"
+                 else ("●", "amber") if state == "unchanged"
+                 else ("◌", "accent") if self.preview and step.act is None
+                 else ("●", "green"))
+        self.line(f"  {p(glyph[0], glyph[1])} {p(step.title, 'bold')}")
+        where = step.app or ""
+        if step.elements is not None:
+            where = f"{where}, {step.elements} elements" if where else f"{step.elements} elements"
+        outcome = ""
+        if step.act == "acknowledged":
+            outcome = {True: "screen changed", False: "no visible change", None: "sent"}[step.changed]
+        elif step.act == "not_dispatched":
+            outcome = "not sent: the screen changed first"
+        elif self.preview and step.operation not in {"DONE", "WAIT", "BLOCKED"}:
+            outcome = "preview: not sent"
+        elif step.note:
+            outcome = step.note
+        elif step.completion:
+            outcome = "goal met" if step.completion == "confirmed" else "not finished yet"
+        parts = [x for x in (where, outcome) if x]
+        if parts:
+            self.line("    " + p("⎿ " + " → ".join(parts), "faint"))
+
+    def _outcome(self, item):
+        """The result: the head, the facts, the answer, then the proof or why it ended."""
+        p = self.paint
+        head, tone = item.head, item.head_tone
+        role = self.TONE_ROLES.get(tone, "muted")
+        glyph = status_glyph(tone)
+        if item.status == "preview":
+            head = "Preview"
+        elapsed = item.summary.get("elapsed_ms") or (time.monotonic() - self.started) * 1000
+        line = facts(self.narrator.actions, elapsed, self.narrator.cost_nanodollars, bool(self.narrator.priced_calls),
+                     plan=bool(self.narrator.plan_calls))
+        self.line(p(f"{glyph} {head}", role, "bold") + "  " + p(line, "faint"))
+        hero = item.hero
+        if hero:
+            self.line("  " + hero)
+        detail = item.proof or item.detail
+        if item.status == "preview":
+            detail = "Nothing was sent to the phone. Add --execute to act."
+        if detail:
+            self.line("  " + p(detail, "faint" if item.proof else "muted"))
+        data = item.summary.get("data")
+        if data is not None and not (isinstance(data, str) and data.strip() == hero):
+            import json
+            body = data if isinstance(data, str) else json.dumps(data, indent=2, ensure_ascii=False)
+            self.line("")
+            self.line(body)
+
+    def pause(self):
+        """Stop the spinner line and clear it, so a question can be asked below the steps."""
+        self.paused = True
+        with self.lock:
+            self._clear()
+            self.stream.flush()
+
+    def resume(self):
+        self.paused = False

mobile_agent/content_queue/__init__.py

@@ -0,0 +1 @@
+"""The content queue: posts lined up for a profile and a time, posted on its phone, never without approval."""

mobile_agent/content_queue/client.py

@@ -0,0 +1,263 @@
+"""Client approval links: your client approves a queued post from a link, on any device, with no account."""
+
+import base64
+import datetime
+import hashlib
+import io
+import logging
+import re
+import secrets
+import subprocess
+import tempfile
+import threading
+from collections import OrderedDict
+from pathlib import Path
+
+from ..api_errors import APIError
+from .store import EDITABLE, QueueError, fingerprint, now_ms, store_for
+
+log = logging.getLogger("mobster.queue")
+
+LINK_DAYS = 7
+DAY_MS = 86400 * 1000
+NOTE_CHARS = 1000
+MAX_LINKS = 500                  # the relay's LIMITS.approvalsPerMac
+PAGE_BYTES = 700_000             # the photos on one page, under the relay's 1 MB message once in base64
+HASH = re.compile(r"[0-9a-f]{64}")
+APPS = {"com.burbn.instagram": "instagram", "com.zhiliaoapp.musically": "tiktok"}
+REMOTE_OFF = ("Turn on Mobster Remote first, in Settings › Remote. A client approval link is Remote's address for "
+              "this Mac.")
+
+
+def state_of(item, stamp=None):
+    """The client's say on the post as it is now"""
+    link = item.get("clientApproval")
+    if not link:
+        return None
+    if link["revokedAt"] is not None:
+        return "revoked"
+    decision = link["decision"]
+    if decision is not None and decision["fingerprint"] == fingerprint(item):
+        return decision["state"]
+    return "expired" if (stamp or now_ms()) >= link["expiresAt"] else "waiting"
+
+
+def holds(item):
+    """True while the post waits for its client: it was sent for approval and isn't approved as it is now."""
+    return state_of(item) not in (None, "approved")
+
+
+def public(item):
+    """What the Mac app shows of the item's link (never its token)."""
+    link = item.get("clientApproval")
+    if not link:
+        return None
+    decision = link["decision"]
+    return {"state": state_of(item), "createdAt": link["createdAt"], "expiresAt": link["expiresAt"],
+            "decision": None if decision is None else {k: decision[k] for k in ("state", "note", "at")},
+            "changed": decision is not None and decision["fingerprint"] != fingerprint(item)}
+
+
+def _live(link, stamp):
+    return link is not None and link["revokedAt"] is None and stamp < link["expiresAt"]
+
+
+def _remote(runtime):
+    try:
+        from ..remote import service as remote_service
+    except ImportError:
+        return None
+    return remote_service.service_for(runtime)
+
+
+def _tell_remote(runtime):
+    remote = _remote(runtime)
+    if remote is not None:
+        try:
+            remote.approvals_changed(live(runtime))
+        except Exception:  # noqa: BLE001 -- the next hello carries the list
+            log.warning("client links: couldn't tell Remote about a change")
+
+
+def live(runtime):
+    """[{h, exp}]: the links that work now, newest first, for the relay."""
+    stamp = now_ms()
+    links = [item["clientApproval"] for queue in store_for(runtime).all() for item in queue["items"]
+             if _live(item.get("clientApproval"), stamp)]
+    links.sort(key=lambda link: link["createdAt"], reverse=True)
+    return [{"h": link["hash"], "exp": link["expiresAt"]} for link in links[:MAX_LINKS]]
+
+
+def send(runtime, queue_id, item_id, profiles):
+    """(item, link): the post's working link, or a new one when it has none (never sent, expired or revoked)."""
+    remote = _remote(runtime)
+    base = remote.address("approve") if remote is not None else None
+    if not base:
+        raise APIError(REMOTE_OFF, 409, "remote_off")
+    stamp = now_ms()
+    token = secrets.token_urlsafe(32)
+
+    def change(item):
+        if item["profile"] not in {profile["id"] for profile in profiles}:
+            raise QueueError("Choose a profile for this post first.", "no_profile", 409)
+        if item["state"] not in EDITABLE:
+            raise QueueError("This post is going out, went out, or may have.", "locked", 409)
+        if _live(item.get("clientApproval"), stamp):
+            return None
+        item["clientApproval"] = {"token": token, "hash": hashlib.sha256(token.encode()).hexdigest(),
+                                  "createdAt": stamp, "expiresAt": stamp + LINK_DAYS * DAY_MS, "revokedAt": None,
+                                  "decision": None}
+        return "client_link"
+
+    item = store_for(runtime).change_item(queue_id, item_id, change)
+    if item["clientApproval"]["token"] == token:
+        _tell_remote(runtime)
+    return item, f"{base}/{item['clientApproval']['token']}"
+
+
+def revoke(runtime, queue_id, item_id):
+    """The link stops working now. The post waits for a new link's OK."""
+    def change(item):
+        link = item.get("clientApproval")
+        if link is None or link["revokedAt"] is not None:
+            raise QueueError("This post has no approval link.", "no_link", 404)
+        link["revokedAt"] = now_ms()
+        return "client_revoked"
+
+    item = store_for(runtime).change_item(queue_id, item_id, change)
+    _tell_remote(runtime)
+    return item
+
+
+def answer(runtime, link_hash, decide=None):
+    """One view of the page (``decide`` None) or one answer from it, as the relay passed it on"""
+    if not isinstance(link_hash, str) or not HASH.fullmatch(link_hash):
+        return {"status": 404, "error": "not_found"}
+    store = store_for(runtime)
+    found = next(((queue["id"], item) for queue in store.all() for item in queue["items"]
+                  if (item.get("clientApproval") or {}).get("hash") == link_hash), None)
+    if found is None or found[1]["clientApproval"]["revokedAt"] is not None:
+        return {"status": 404, "error": "not_found"}
+    queue_id, item = found
+    if now_ms() >= item["clientApproval"]["expiresAt"]:
+        return {"status": 410, "error": "expired"}
+    from ..accounts.store import store_for as profiles_for
+    profile = next((p for p in profiles_for(runtime).all() if p["id"] == item["profile"]), None)
+    if profile is None:
+        return {"status": 409, "error": "no_profile"}
+    if decide is not None:
+        try:
+            item = store.change_item(queue_id, item["id"], _decision(decide))
+        except QueueError as error:
+            out = {"status": error.status, "error": error.code}
+            return out | {"view": view(item, profile)} if error.code == "changed" else out
+    return {"status": 200, "view": view(item, profile)}
+
+
+def _decision(decide):
+    """The change one answer makes, checked against the post as it is when the answer lands."""
+    choice = decide.get("decision") if isinstance(decide, dict) else None
+    if choice not in ("approve", "changes"):
+        raise QueueError("Approve the post, or ask for changes.", "invalid", 422)
+    state = "approved" if choice == "approve" else "changes"
+    note, version = decide.get("note", ""), decide.get("v")
+    if not isinstance(note, str) or len(note) > NOTE_CHARS:
+        raise QueueError(f"A note is at most {NOTE_CHARS:,} characters.", "invalid", 422)
+    note = note.strip()
+    if state == "changes" and not note:
+        raise QueueError("Say what should change.", "invalid", 422)
+
+    def change(item):
+        if item["state"] not in EDITABLE:
+            raise QueueError("This post is already going out, so it can't change here.", "locked", 409)
+        current = fingerprint(item)
+        if version != current[:16]:
+            raise QueueError("This post changed since you opened it. Look at it again.", "changed", 409)
+        item["clientApproval"]["decision"] = {"state": state, "note": note if state == "changes" else "",
+                                              "at": now_ms(), "fingerprint": current}
+        return "client_" + state
+    return change
+
+
+def view(item, profile):
+    """Only what the client's page shows"""
+    link = item["clientApproval"]
+    state = state_of(item)
+    decision = link["decision"]
+    return {"app": APPS.get(profile["app"]["bundleId"], "other"), "appName": profile["app"]["name"],
+            "handle": profile["handle"], "when": _when(item["scheduledAt"]), "day": _day(item["scheduledAt"]),
+            "caption": item["caption"], "hashtags": item["hashtags"], "sound": item["sound"],
+            "format": item["format"], "media": stills(item), "v": fingerprint(item)[:16],
+            "expires": _day(link["expiresAt"]),
+            "status": "open" if item["state"] in EDITABLE else "posted" if item["state"] == "posted" else "going",
+            "decision": {"state": state, "note": decision["note"], "at": _when(decision["at"])}
+            if state in ("approved", "changes") else None,
+            "changed": state == "waiting" and decision is not None}
+
+
+def _local(ms):
+    return datetime.datetime.fromtimestamp(ms / 1000).astimezone()
+
+
+def _when(ms):
+    return None if ms is None else _local(ms).strftime("%a, %b %-d at %-I:%M %p %Z")
+
+
+def _day(ms):
+    return _local(ms if ms is not None else now_ms()).strftime("%B %-d")
+
+
+_stills = OrderedDict()           # (sha256, width) → (JPEG bytes, width / height): a second view reads no file
+_stills_lock = threading.Lock()
+STILLS_KEPT = 64
+
+
+def stills(item):
+    """[{kind, src, ratio}]: each photo or video's first frame as a JPEG data: URI, src None when it can't fit."""
+    out, used = [], 0
+    count = len(item["media"])
+    for index, media in enumerate(item["media"]):
+        got = _still(media, 1080 if index == 0 else 720 if count <= 4 else 480)
+        src = None
+        if got is not None and used + len(got[0]) <= PAGE_BYTES:
+            used += len(got[0])
+            src = "data:image/jpeg;base64," + base64.b64encode(got[0]).decode()
+        out.append({"kind": media["kind"], "src": src, "ratio": round(got[1], 4) if got else None})
+    return out
+
+
+def _still(media, width):
+    key = (media["sha256"], width)
+    with _stills_lock:
+        if key in _stills:
+            _stills.move_to_end(key)
+            return _stills[key]
+    from PIL import Image, ImageOps
+    path = Path(media["path"])
+    try:
+        with tempfile.TemporaryDirectory() as folder:
+            source = path
+            if media["kind"] == "video" or path.suffix.lower() in (".heic", ".heif"):
+                source = _quick_look(path, width, Path(folder))
+            if source is None:
+                return None
+            with Image.open(source) as opened:
+                image = ImageOps.exif_transpose(opened)
+                image.thumbnail((width, width * 2))
+                out = io.BytesIO()
+                image.convert("RGB").save(out, "JPEG", quality=78, optimize=True)
+                got = (out.getvalue(), image.width / image.height)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    with _stills_lock:
+        _stills[key] = got
+        while len(_stills) > STILLS_KEPT:
+            _stills.popitem(last=False)
+    return got
+
+
+def _quick_look(path, width, folder):
+    """macOS Quick Look's still of a video's first frame or a HEIC photo (Pillow reads neither), as a PNG."""
+    subprocess.run(["qlmanage", "-t", "-s", str(width), "-o", str(folder), str(path)], capture_output=True,
+                   timeout=20, check=False)
+    return next(folder.glob("*.png"), None)

mobile_agent/content_queue/importing.py

@@ -0,0 +1,153 @@
+"""Bulk queues in and posting reports out."""
+
+import csv
+import datetime
+import io
+import json
+from pathlib import Path
+
+from .store import CAPTION_CHARS, MAX_ITEMS, QueueError, caption_text
+
+COLUMNS = ("media", "caption", "hashtags", "sound", "profile", "schedule", "format")
+MEDIA_SUFFIXES = (".jpg", ".jpeg", ".heic", ".heif", ".png", ".gif", ".webp", ".mov", ".mp4", ".m4v")
+REPORT_COLUMNS = ("post", "profile", "app", "phone", "scheduled", "state", "posted_at", "link", "media", "checked",
+                  "route", "caption", "note", "run")
+
+
+def _profile_id(value, profiles):
+    from ..accounts.store import AccountNotFound, AmbiguousAccount, resolve
+    if not value:
+        return None
+    try:
+        return resolve(profiles, value.strip())["id"]
+    except (AccountNotFound, AmbiguousAccount) as error:
+        raise QueueError(str(error), "profile_not_found") from None
+
+
+def _when(value, zone=None):
+    if not value or not value.strip():
+        return None
+    try:
+        stamp = datetime.datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        raise QueueError(f"{value!r} isn't a time: write it like 2026-10-20T09:30.") from None
+    if stamp.tzinfo is None:
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+        try:
+            stamp = stamp.replace(tzinfo=ZoneInfo(zone)) if zone else stamp.astimezone()
+        except (ZoneInfoNotFoundError, ValueError):
+            stamp = stamp.astimezone()
+    return round(stamp.timestamp() * 1000)
+
+
+def from_csv(text, base, profiles, zone_of=lambda profile: None):
+    """Item bodies (store.clean_item's input) from CSV ``text``; relative media paths are under ``base``."""
+    reader = csv.DictReader(io.StringIO(text.lstrip("")))
+    if not reader.fieldnames or "media" not in {name.strip().casefold() for name in reader.fieldnames}:
+        raise QueueError("The CSV needs a header with a media column (and caption, hashtags, sound, profile, schedule, "
+                         "format if you like).")
+    bodies = []
+    for number, row in enumerate(reader, start=2):
+        row = {(k or "").strip().casefold(): (v or "").strip() for k, v in row.items() if k}
+        if not any(row.values()):
+            continue
+        if len(bodies) >= MAX_ITEMS:
+            raise QueueError(f"A queue holds at most {MAX_ITEMS} posts.", "too_many")
+        paths = [p.strip() for p in row.get("media", "").replace(";", "|").split("|") if p.strip()]
+        if not paths:
+            raise QueueError(f"Row {number} names no photo or video.")
+        media = [str((Path(base) / p).expanduser()) if not Path(p).expanduser().is_absolute()
+                 else str(Path(p).expanduser()) for p in paths]
+        try:
+            profile = _profile_id(row.get("profile"), profiles)
+            body = {"media": media, "caption": row.get("caption", ""), "hashtags": row.get("hashtags", ""),
+                    "sound": row.get("sound", ""), "profile": profile,
+                    "scheduledAt": _when(row.get("schedule"), zone_of(profile) if profile else None)}
+        except QueueError as error:
+            raise QueueError(f"Row {number}: {error}", error.code) from None
+        if row.get("format"):
+            body["format"] = row["format"].casefold()
+        bodies.append(body)
+    if not bodies:
+        raise QueueError("The CSV has no posts in it.")
+    return bodies
+
+
+def from_folder(folder, profile=None):
+    """Item bodies, one per photo or video in ``folder`` (not its subfolders), in name order."""
+    folder = Path(folder).expanduser()
+    if not folder.is_dir():
+        raise QueueError(f"There is no folder at {folder}.")
+    files = sorted((p for p in folder.iterdir() if p.is_file() and p.suffix.lower() in MEDIA_SUFFIXES
+                    and not p.name.startswith(".")), key=lambda p: p.name.casefold())
+    if not files:
+        raise QueueError(f"{folder.name} has no photos or videos.")
+    if len(files) > MAX_ITEMS:
+        raise QueueError(f"A queue holds at most {MAX_ITEMS} posts; {folder.name} has {len(files)}.", "too_many")
+    return [body_for(file, profile) for file in files]
+
+
+def body_for(file, profile=None):
+    """One post for a media file: the caption is the .txt beside it, if there is one."""
+    caption = ""
+    sidecar = file.with_suffix(".txt")
+    if sidecar.is_file():
+        try:
+            caption = sidecar.read_text(encoding="utf-8").strip()[:CAPTION_CHARS]
+        except (OSError, UnicodeDecodeError):
+            caption = ""
+    body = {"media": [str(file)], "caption": caption}
+    if profile:
+        body["profile"] = profile
+    return body
+
+
+def report_rows(queue, profiles):
+    by_id = {p["id"]: p for p in profiles}
+    rows = []
+    for number, item in enumerate(queue["items"], start=1):
+        profile = by_id.get(item.get("profile")) or {}
+        result = item.get("result") or {}
+        transfer = item.get("transfer") or {}
+        checked = transfer.get("items") or ()
+        rows.append({
+            "post": number,
+            "profile": f"@{profile['handle']}" if profile else "",
+            "app": (profile.get("app") or {}).get("name", ""),
+            "phone": profile.get("deviceName") or "",
+            "scheduled": _iso(item.get("scheduledAt")),
+            "state": item["state"],
+            "posted_at": _iso(result.get("postedAt") or result.get("markedAt")),
+            "link": result.get("link") or "",
+            "media": " | ".join(m["name"] for m in item["media"]),
+            "checked": " | ".join(c.get("state", "") for c in checked),
+            "route": transfer.get("route") or "",
+            "caption": caption_text(item),
+            "note": item.get("note") or "",
+            "run": item.get("runId") or "",
+        })
+    return rows
+
+
+def _iso(ms):
+    if not ms:
+        return ""
+    return datetime.datetime.fromtimestamp(ms / 1000).astimezone().isoformat(timespec="minutes")
+
+
+def report(queue, profiles, fmt="csv"):
+    """(bytes, content type, file name) of the posting report."""
+    rows = report_rows(queue, profiles)
+    safe = "".join(c if c.isalnum() or c in " -_" else "-" for c in queue["name"]).strip() or "queue"
+    if fmt == "json":
+        body = json.dumps({"queue": queue["name"], "posts": rows}, ensure_ascii=False, indent=1).encode()
+        return body, "application/json", f"{safe} report.json"
+    if fmt != "csv":
+        raise QueueError("The report is csv or json.")
+    out = io.StringIO()
+    writer = csv.DictWriter(out, fieldnames=REPORT_COLUMNS)
+    writer.writeheader()
+    for row in rows:
+        # A cell a spreadsheet would run as a formula is written as text.
+        writer.writerow({k: ("'" + v if isinstance(v, str) and v[:1] in "=+-@" else v) for k, v in row.items()})
+    return out.getvalue().encode("utf-8"), "text/csv", f"{safe} report.csv"