margin 0.2.1__py3-none-any.whl

margin/outline.py

@@ -0,0 +1,282 @@
+"""A small client for Outline's RPC-style API (POST /api/<method>, JSON in and out).
+
+Only what margin needs: collections, documents, comments and webhook subscriptions. Standard library
+only. Errors raise OutlineError with the HTTP status and Outline's own error code, so a caller can
+tell "the text to patch was not found" (404) from "not allowed" (403) from "the server is down".
+"""
+from __future__ import annotations
+
+import json
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class OutlineError(Exception):
+    def __init__(self, method: str, status: int, code: str, message: str):
+        super().__init__(f"{method}: {status} {code} {message}")
+        self.method, self.status, self.code, self.message = method, status, code, message
+
+
+def pin_host(host: str, ip: str) -> None:
+    """Resolve `host` to `ip` for this process. TLS still checks the certificate against `host`.
+
+    Needed on a machine that serves Outline over Tailscale but cannot resolve its own MagicDNS name.
+    """
+    real = socket.getaddrinfo
+
+    def gai(h, *a, **k):
+        return real(ip if h == host else h, *a, **k)
+
+    socket.getaddrinfo = gai
+
+
+#: what a proxy answers while Outline itself is down or restarting: worth waiting for, not a fault
+GATEWAY = (502, 503, 504)
+
+
+class Outline:
+    def __init__(self, url: str, api_key: str, timeout: float = 30.0):
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._me: dict | None = None
+
+    def call(self, method: str, body: dict | None = None, retries: int = 3,
+             headers: dict | None = None) -> dict:
+        data = json.dumps(body or {}).encode()
+        req = urllib.request.Request(
+            f"{self.url}/api/{method}", data,
+            {"Content-Type": "application/json", "Authorization": f"Bearer {self.api_key}",
+             **(headers or {})})
+        for attempt in range(retries + 1):
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    return json.loads(r.read())
+            except urllib.error.HTTPError as e:
+                raw = e.read().decode(errors="replace")
+                try:
+                    j = json.loads(raw)
+                except ValueError:
+                    j = {}
+                if e.code == 429 and attempt < retries:
+                    time.sleep(float(e.headers.get("Retry-After") or 2 ** attempt))
+                    continue
+                if e.code in GATEWAY and attempt < retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise OutlineError(method, e.code, j.get("error", ""), j.get("message", raw[:200]))
+            except urllib.error.URLError:
+                if attempt < retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise
+        raise AssertionError("unreachable")
+
+    def data(self, method: str, body: dict | None = None):
+        return self.call(method, body).get("data")
+
+    def structure(self, doc_id: str) -> dict | None:
+        """A document as Outline's editor holds it (ProseMirror JSON), comment marks included.
+        API version 3 returns it in place of the markdown; the markdown has no comment marks."""
+        got = self.call("documents.info", {"id": doc_id}, headers={"x-api-version": "3"})
+        doc = (got.get("data") or {})
+        return (doc.get("document") or doc).get("data")
+
+    def paged(self, method: str, body: dict | None = None, limit: int = 100):
+        """Every row of a paginated list method."""
+        offset = 0
+        while True:
+            page = self.data(method, {**(body or {}), "limit": limit, "offset": offset}) or []
+            yield from page
+            if len(page) < limit:
+                return
+            offset += limit
+
+    def wait_ready(self, timeout: float = 600.0, every: float = 10.0, log=None) -> dict:
+        """Who the key belongs to, once Outline answers: a server that is down or restarting (a
+        gateway error, or no connection) is waited for until `timeout` seconds, then raised. Any
+        other error (a bad key, say) is raised at once."""
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                return self.me()
+            except (OutlineError, urllib.error.URLError) as e:
+                if isinstance(e, OutlineError) and e.status not in GATEWAY:
+                    raise
+                if time.monotonic() >= deadline:
+                    raise
+                if log:
+                    log(f"waiting for Outline: {e}")
+                time.sleep(every)
+
+    # ---- who am I
+    def me(self) -> dict:
+        if self._me is None:
+            self._me = self.data("auth.info")["user"]
+        return self._me
+
+    # ---- collections
+    def collection_by_name(self, name: str) -> dict | None:
+        for c in self.paged("collections.list"):
+            if c["name"] == name:
+                return c
+        return None
+
+    def ensure_collection(self, name: str, description: str = "") -> dict:
+        return self.collection_by_name(name) or self.data(
+            "collections.create", {"name": name, "description": description,
+                                   "permission": "read_write", "sharing": False})
+
+    # ---- documents
+    def create_document(self, collection_id: str, title: str, text: str,
+                        parent_id: str | None = None) -> dict:
+        body = {"collectionId": collection_id, "title": title, "text": text, "publish": True}
+        if parent_id:
+            body["parentDocumentId"] = parent_id
+        return self.data("documents.create", body)
+
+    def document(self, doc_id: str) -> dict:
+        return self.data("documents.info", {"id": doc_id})
+
+    def patch(self, doc_id: str, find: str, text: str) -> dict:
+        """Replace the first occurrence of `find` (markdown) with `text`. Keeps comments elsewhere."""
+        return self.data("documents.update",
+                         {"id": doc_id, "editMode": "patch", "findText": find, "text": text})
+
+    def append(self, doc_id: str, text: str) -> dict:
+        """Add `text` after the last block. Touches no existing block, so every comment stays."""
+        return self.data("documents.update", {"id": doc_id, "editMode": "append", "text": text})
+
+    def replace(self, doc_id: str, text: str) -> dict:
+        """Replace the whole body. Removes every comment anchor, so only for docs margin owns
+        outright (the scratch document), never for a document someone may have commented on."""
+        return self.data("documents.update", {"id": doc_id, "editMode": "replace", "text": text})
+
+    def revisions(self, doc_id: str) -> list[dict]:
+        """Every saved revision of a document, each with `createdBy`."""
+        return list(self.paged("revisions.list", {"documentId": doc_id}))
+
+    def set_title(self, doc_id: str, title: str) -> dict:
+        return self.data("documents.update", {"id": doc_id, "title": title})
+
+    # ---- attachments
+    def upload(self, name: str, content_type: str, data: bytes, document_id: str) -> str:
+        """Upload a file as an attachment of `document_id` and return the address a document uses
+        for it (`/api/attachments.redirect?id=...`).
+
+        Outline answers attachments.create with where to send the bytes: its own files.create when
+        it stores files itself, or a storage service's pre-signed address. The API key goes only to
+        Outline's own address, never to a storage service."""
+        import uuid
+        d = self.data("attachments.create", {"name": name, "contentType": content_type,
+                                             "size": len(data), "documentId": document_id,
+                                             "preset": "documentAttachment"})
+        up = d["uploadUrl"]
+        own = up.startswith("/") or up.startswith(self.url + "/")
+        if up.startswith("/"):
+            up = self.url + up
+        b = "----margin" + uuid.uuid4().hex
+        parts = [f'--{b}\r\nContent-Disposition: form-data; name="{k}"\r\n\r\n{v}\r\n'.encode()
+                 for k, v in (d.get("form") or {}).items()]
+        parts.append(f'--{b}\r\nContent-Disposition: form-data; name="file"; filename="{name}"\r\n'
+                     f"Content-Type: {content_type}\r\n\r\n".encode() + data + b"\r\n")
+        parts.append(f"--{b}--\r\n".encode())
+        headers = {"Content-Type": f"multipart/form-data; boundary={b}"}
+        if own:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(up, b"".join(parts), headers)
+        try:
+            with urllib.request.urlopen(req, timeout=max(self.timeout, 120)) as r:
+                r.read()
+        except urllib.error.HTTPError as e:
+            raise OutlineError("upload", e.code, "", e.read().decode(errors="replace")[:200])
+        return d["attachment"]["url"]
+
+    # ---- comments
+    def comments(self, collection_id: str | None = None, document_id: str | None = None):
+        body: dict = {"includeAnchorText": True, "sort": "createdAt", "direction": "DESC"}
+        if collection_id:
+            body["collectionId"] = collection_id
+        if document_id:
+            body["documentId"] = document_id
+        return self.paged("comments.list", body)
+
+    def comment(self, comment_id: str) -> dict:
+        return self.data("comments.info", {"id": comment_id, "includeAnchorText": True})
+
+    def reply(self, document_id: str, parent_id: str | None, text: str,
+              anchor: str | None = None) -> dict:
+        body: dict = {"documentId": document_id, "text": text}
+        if parent_id:
+            body["parentCommentId"] = parent_id
+        if anchor:
+            body["anchorText"] = anchor
+        return self.data("comments.create", body)
+
+    def resolve(self, comment_id: str) -> dict:
+        return self.data("comments.resolve", {"id": comment_id})
+
+    # ---- webhooks
+    def webhooks(self) -> list[dict]:
+        return list(self.paged("webhookSubscriptions.list"))
+
+    def ensure_webhook(self, name: str, url: str, secret: str, events: list[str]) -> dict:
+        """Create the subscription, or repair it. Outline switches a subscription off after
+        repeated failed deliveries, and an update switches it back on."""
+        for w in self.webhooks():
+            if w.get("url") == url:
+                if w.get("enabled") is False or sorted(w.get("events") or []) != sorted(events):
+                    w = self.data("webhookSubscriptions.update",
+                                  {"id": w["id"], "name": name, "url": url, "secret": secret,
+                                   "events": events})
+                return w
+        return self.data("webhookSubscriptions.create",
+                         {"name": name, "url": url, "secret": secret, "events": events})
+
+
+def doc_url(base: str, doc: dict) -> str:
+    return f"{base.rstrip('/')}{doc.get('url') or '/doc/' + doc['id']}"
+
+
+def comment_text(data: dict | None) -> str:
+    """Plain text of a ProseMirror comment body. Mentions render as @Label."""
+    out: list[str] = []
+
+    def walk(node: dict) -> None:
+        t = node.get("type")
+        if t == "text":
+            out.append(node.get("text", ""))
+        elif t == "mention":
+            out.append("@" + (node.get("attrs", {}).get("label") or ""))
+        elif t == "hard_break":
+            out.append("\n")
+        for child in node.get("content", []) or []:
+            walk(child)
+        if t in ("paragraph", "heading", "list_item", "blockquote"):
+            out.append("\n")
+
+    walk(data or {})
+    return "".join(out).strip()
+
+
+def mentions(data: dict | None) -> set[str]:
+    """User ids mentioned in a ProseMirror comment body."""
+    found: set[str] = set()
+
+    def walk(node: dict) -> None:
+        if node.get("type") == "mention":
+            a = node.get("attrs", {})
+            if a.get("type", "user") == "user" and a.get("modelId"):
+                found.add(a["modelId"])
+        for child in node.get("content", []) or []:
+            walk(child)
+
+    walk(data or {})
+    return found
+
+
+def quote(s: str) -> str:
+    return urllib.parse.quote(s, safe="")

margin/patches.py

@@ -0,0 +1,243 @@
+"""Turn "the document is X, it should be Y" into the smallest patches Outline can apply.
+
+Outline's patch edit replaces the FIRST occurrence of a piece of markdown and keeps every comment
+anchored outside it. A comment anchored inside the replaced span loses its anchor (the thread stays,
+pointing at nothing). So the patches must be as small as possible, and each one must be unique in
+the document at the moment it is applied, or it lands on the wrong occurrence.
+
+The planner works on lines. Hunks are applied bottom-up, so everything below a hunk already
+matches the target and can always serve as context.
+
+⭐ A CHANGED LINE IS PATCHED WORD BY WORD (2026-10-13). A paragraph is one line, so a line-sized
+patch replaced a whole paragraph, and a comment anchored on words the edit had kept lost its
+highlight (the anchor "Between 23:00 and 08:00" went when only a bracket after it was removed).
+Outline patches a match inside one paragraph in place and keeps every mark outside the match, so
+a line that changed into one other line is patched as the runs of words that changed, each with
+just enough words around it to be unique. Only when that cannot be done does the whole line go. Context above a hunk is taken only from the
+unchanged run directly above it. `apply` replays a plan locally, and `plan` checks its own result
+with it before returning, so a plan that would not produce the target is never returned.
+"""
+from __future__ import annotations
+
+import re
+from difflib import SequenceMatcher
+
+Patch = tuple[str, str]   # (find, replace)
+
+
+class CannotPatch(Exception):
+    """No sequence of unique patches reaches the target. The caller must not fall back to a full
+    replace on a document that may carry comments; it reports the document instead."""
+
+
+#: a run of asterisks that starts with an escaped one: Outline writes two literal asterisks as `\**`
+#: when it saves a whole body and as `\*\*` when it saves a patch
+_ESCAPED_RUN = re.compile(r"\\\*(?:\\?\*)*")
+
+
+#: a run of spaces after text and before an inline picture
+_BEFORE_PICTURE = re.compile(r"(?<=\S) +(?=!\[)")
+
+
+def spelled(line: str) -> str:
+    r"""A line with the spellings Outline itself varies made one: an escaped run of asterisks
+    (`\**` and `\*\*`), a hard line break (a backslash at the end of the line), which a patch
+    writes where a whole-body save wrote a plain newline, and the spaces before an inline picture. Nothing else: `\*a\*` and `*a*` stay apart,
+    because they mean different things."""
+    line = _ESCAPED_RUN.sub(lambda m: "\\" + "*" * m.group(0).count("*"), line)
+    # spaces between text and an inline picture: a patch writes one more (`[  ![`, three between two
+    # pictures), and markdown shows a run of spaces as one; indentation at a line's start is kept
+    line = _BEFORE_PICTURE.sub(" ", line)
+    return line[:-1] if line.endswith("\\") and not line.endswith("\\\\") else line
+
+
+def spelled_alike(a: str, b: str) -> bool:
+    """Whether two texts differ only in the spellings `spelled` makes one."""
+    return a == b or [spelled(x) for x in a.split("\n")] == [spelled(x) for x in b.split("\n")]
+
+
+def adopt(current: str, target: str) -> str:
+    """The target with every line that is spelled alike in `current` written as `current` writes
+    it, so a plan changes only what really differs and never chases Outline's own spelling."""
+    a, b = current.split("\n"), target.split("\n")
+    out = b[:]
+    ops = SequenceMatcher(None, [spelled(x) for x in a], [spelled(x) for x in b], autojunk=False).get_opcodes()
+    for tag, i1, i2, j1, j2 in ops:
+        if tag == "equal":
+            out[j1:j2] = a[i1:i2]
+    return "\n".join(out)
+
+
+def apply(text: str, patches: list[Patch]) -> str:
+    for find, repl in patches:
+        if find not in text:
+            raise CannotPatch(f"find text not present: {find[:60]!r}")
+        text = text.replace(find, repl, 1)
+    return text
+
+
+def _only_at(lines: list[str], lo: int, find: str) -> bool:
+    """`find` occurs exactly once in the joined lines, starting at line `lo`. Overlapping matches
+    count, because Outline replaces the first occurrence wherever it starts."""
+    joined = "\n".join(lines)
+    at = sum(len(x) + 1 for x in lines[:lo])
+    return joined.find(find) == at and joined.find(find, at + 1) == -1
+
+
+_TOKEN = re.compile(r"\s+|\w+|[^\w\s]")
+
+
+def _offsets(tokens: list[str]) -> list[int]:
+    out = [0]
+    for t in tokens:
+        out.append(out[-1] + len(t))
+    return out
+
+
+#: the markers that come in pairs: bold, bold, strike-through and a code span
+_PAIRED = re.compile(r"(?<!\\)(\*\*|__|~~|`)")
+
+
+def _cuts_markup(piece: str) -> bool:
+    r"""Whether a piece of a line holds one half of a paired marker. ⛔ Outline parses a patch's text
+    on its own, so a lone `**` comes back escaped: a patch that changed the words after `**Sweep`
+    left `\**Sweep ...:\**` in the document, the bold gone (2026-10-16, fifteen documents at
+    cannot-patch). Such a change is patched as its whole line."""
+    counts: dict[str, int] = {}
+    for m in _PAIRED.finditer(piece):
+        counts[m.group(1)] = counts.get(m.group(1), 0) + 1
+    return any(n % 2 for n in counts.values())
+
+
+def _is_row(line: str) -> bool:
+    """A line of a markdown table."""
+    return line.lstrip().startswith("|")
+
+
+def _words(lines: list[str], i: int, new: str) -> list[Patch] | None:
+    """Patches that turn line `i` of `lines` into `new`, touching only the words that changed. Each
+    is unique in the whole document when it is applied, and they go right to left so the rest of
+    the line still reads as it did. None when a change cannot be made unique inside its line.
+    `lines` is updated as the patches are planned."""
+    if _is_row(lines[i]) or _is_row(new):
+        return None               # a table is patched whole (plan)
+    old_t, new_t = _TOKEN.findall(lines[i]), _TOKEN.findall(new)
+    if not old_t or not new_t or "".join(old_t) != lines[i]:
+        return None
+    out: list[Patch] = []
+    ops: list[list] = []
+    for op in SequenceMatcher(None, old_t, new_t, autojunk=False).get_opcodes():
+        # two changes with only spaces between them are one change ("an hour" to "a day")
+        if (len(ops) >= 2 and op[0] != "equal" and ops[-1][0] == "equal" and ops[-2][0] != "equal"
+                and not "".join(old_t[ops[-1][1]:ops[-1][2]]).strip()):
+            ops.pop()
+            ops[-1] = ["replace", ops[-1][1], op[2], ops[-1][3], op[4]]
+        else:
+            ops.append(list(op))
+    for tag, s1, s2, t1, t2 in reversed(ops):
+        if tag == "equal":
+            continue
+        at = _offsets(old_t)
+        left, right = s1, s2              # the span of old tokens the patch covers
+        while True:
+            find = lines[i][at[left]:at[right]]
+            if find.strip() and _only_at_col(lines, i, at[left], find):
+                break
+            # one more word of context, on the side with more room, never past the line
+            if left > 0 and (right >= len(old_t) or s1 - left <= right - s2):
+                left -= 1
+            elif right < len(old_t):
+                right += 1
+            else:
+                return None
+        repl = "".join(old_t[left:s1]) + "".join(new_t[t1:t2]) + "".join(old_t[s2:right])
+        if _cuts_markup(find) or _cuts_markup(repl):
+            return None           # the whole line, so Outline reads both halves of every marker
+        lines[i] = lines[i][:at[left]] + repl + lines[i][at[right]:]
+        out.append((find, repl))
+        old_t = old_t[:s1] + new_t[t1:t2] + old_t[s2:]   # right of here now reads as the target
+    return out if lines[i] == new else None
+
+
+def _only_at_col(lines: list[str], i: int, col: int, find: str) -> bool:
+    """`find` occurs exactly once in the joined lines, starting at column `col` of line `i`."""
+    joined = "\n".join(lines)
+    at = sum(len(x) + 1 for x in lines[:i]) + col
+    return joined.find(find) == at and joined.find(find, at + 1) == -1
+
+
+def plan(current: str, target: str, widen: int = 0) -> list[Patch]:
+    """Patches from `current` to `target`. `widen` > 0 makes every patch also cross that many
+    blank lines (block boundaries). Outline patches a match inside ONE top-level block by
+    re-parsing just that block, and drops anything the replacement adds outside it; a match that
+    spans two blocks takes its region path instead, which keeps everything. The syncer widens
+    only after it sees a patch come back different from what it expected."""
+    if current == target:
+        return []
+    a, b = current.split("\n"), target.split("\n")
+    ops = SequenceMatcher(None, a, b, autojunk=False).get_opcodes()
+    work = a[:]
+    patches: list[Patch] = []
+    k = len(ops) - 1
+    while k >= 0:
+        tag, i1, i2, j1, j2 = ops[k]
+        if tag == "equal":
+            k -= 1
+            continue
+        if widen == 0 and tag == "replace" and i2 - i1 == j2 - j1:
+            trial, fine = work[:], []
+            for li in range(i2 - 1, i1 - 1, -1):        # bottom-up, as the hunks are
+                if trial[li] == b[j1 + li - i1]:
+                    continue
+                got = _words(trial, li, b[j1 + li - i1])
+                if got is None:
+                    fine = None
+                    break
+                fine += got
+            if fine is not None:
+                work = trial
+                patches += fine
+                k -= 1
+                continue
+        lo, hi, blo, bhi = i1, i2, j1, j2
+        # ⛔ A TABLE IS PATCHED WHOLE (2026-10-16). Outline took no patch that began inside a table:
+        # rows added at its end came back as a paragraph after it, the second row lost, and every
+        # later pass failed on the same table. A hunk that touches a table line, or sits right
+        # against one, covers the whole table and the blank line on each side, so it crosses blocks
+        # and Outline takes the path that keeps everything.
+        up_limit = ops[k - 1][1] if k > 0 and ops[k - 1][0] == "equal" else lo
+        near = work[lo:hi] + b[blo:bhi] + work[max(lo - 1, 0):lo] + work[hi:hi + 1]
+        if any(_is_row(x) for x in near):
+            # lines above the hunk, down to the run left unchanged, are the current's and the
+            # target's alike; lines below it already read as the target (the hunks go bottom-up)
+            while lo > up_limit and _is_row(work[lo - 1]):
+                lo, blo = lo - 1, blo - 1
+            if lo > up_limit and not work[lo - 1].strip():
+                lo, blo = lo - 1, blo - 1
+            while hi < len(work) and _is_row(work[hi]):
+                hi, bhi = hi + 1, bhi + 1
+            if hi < len(work) and not work[hi].strip():
+                hi, bhi = hi + 1, bhi + 1
+        while True:
+            # how far up we may borrow context: the unchanged run directly above the hunk
+            up_limit = ops[k - 1][1] if k > 0 and ops[k - 1][0] == "equal" else lo
+            find = "\n".join(work[lo:hi])
+            repl = "\n".join(b[blo:bhi])
+            if (find.strip() and (repl or bhi > blo) and _only_at(work, lo, find)
+                    and sum(1 for x in work[lo:hi] if not x.strip()) >= widen):
+                break
+            if hi < len(work):            # below the hunk already matches the target
+                hi, bhi = hi + 1, bhi + 1
+            elif lo > up_limit:
+                lo, blo = lo - 1, blo - 1
+            elif k >= 2:                  # swallow the run above and the hunk above it
+                k -= 2
+                lo, blo = ops[k][1], ops[k][3]
+            else:
+                raise CannotPatch("no unique context around a change")
+        work[lo:hi] = b[blo:bhi]
+        patches.append((find, repl))
+        k -= 1
+    if apply(current, patches) != target:
+        raise CannotPatch("plan does not reproduce the target")
+    return patches