officecli-sdk 0.1.0__tar.gz

officecli_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: officecli-sdk
+Version: 0.1.0
+Summary: Thin Python SDK for the officecli resident pipe — forwards officecli commands to a running resident, no per-command process spawn.
+License-Expression: Apache-2.0
+Keywords: officecli,office,docx,xlsx,pptx,ooxml
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# officecli — Python SDK
+
+A **thin** Python SDK for the [officecli](../../) **resident pipe**. It does one
+thing: forward an officecli command to a running resident over its named pipe and
+hand back the response — no per-command process spawn, so a loop of edits is
+~hundreds of times faster than shelling out to the CLI per command.
+
+"Thin" is the point: there is **no second vocabulary** to learn. A command is the
+same dict you'd put in an officecli `batch` list; the SDK just carries it over the
+pipe. Anything a `doc.set_cell(...)` / `doc.add_paragraph(...)` method would do is
+**fully supported** — you just spell it `doc.send({"command": "set", ...})`, with
+the exact same effect. One uniform verb instead of dozens of per-element named
+methods: same power, nothing extra to memorize, and new officecli features work
+the day they ship without an SDK update.
+
+## Requirement: the officecli CLI must be installed
+
+`pip install officecli-sdk` installs **only this SDK** (the Python library). It
+shells out to the `officecli` binary, which must be installed separately and on
+your `PATH` (Homebrew, etc.). If `officecli --version` works in your shell, you're
+set.
+
+## Install
+
+```bash
+pip install officecli-sdk            # once published — note: import name is `officecli`
+# or, from a checkout of this repo:
+pip install ./sdk/python
+```
+
+The pip/distribution name is `officecli-sdk`, but you `import officecli`
+(distribution name ≠ import name, like `pip install pillow` → `import PIL`).
+
+Zero third-party dependencies (standard library only).
+
+## Quickstart
+
+```python
+import officecli
+
+# create() makes a new file and returns a live session handle;
+# open() does the same for an existing file. Both return a Document.
+with officecli.create("report.xlsx", "--force") as doc:
+    doc.send({"command": "set", "path": "/Sheet1/A1",
+              "props": {"text": "Region", "bold": "true"}})
+    doc.send({"command": "set", "path": "/Sheet1/B1", "props": {"formula": "=SUM(B2:B9)"}})
+
+    # read one back (returns the parsed JSON envelope)
+    node = doc.send({"command": "get", "path": "/Sheet1/A1"})
+    print(node["data"]["results"][0]["text"])     # -> Region
+
+    # many edits in ONE pipe round-trip
+    doc.batch([
+        {"command": "set", "path": "/Sheet1/A2", "props": {"text": "North"}},
+        {"command": "set", "path": "/Sheet1/A3", "props": {"text": "South"}},
+    ])
+
+    doc.send({"command": "save"})
+# leaving `with` closes the resident (which flushes to disk)
+
+# borrow an already-running resident without owning it: skip `with`/close()
+d = officecli.open("report.xlsx")
+print(d.send({"command": "view", "mode": "stats"}, as_json=False))
+```
+
+See `demo.py` for a fuller example.
+
+## The command dict
+
+`send(item)` and `batch([item, ...])` take the officecli **batch-item** shape:
+
+```jsonc
+{ "command": "set",            // or "op"; picks the officecli command
+  "path": "/Sheet1/A1",        // every key except command/op/props is forwarded
+  "props": { "text": "hi" } }  // verbatim as a command argument
+```
+
+Keys are officecli's own batch fields (`command`/`op`, `path`, `parent`, `type`,
+`index`, `after`, `before`, `to`, `selector`, `mode`, `depth`, `part`, `xpath`,
+`action`, `xml`) plus a nested `props`. The client maintains no field list of its
+own — run `officecli help` (or see the batch docs) for the full reference.
+
+`send(..., as_json=False)` requests plain-text output (e.g. `view` / `raw` /
+`dump`), mirroring the CLI's `--json` toggle.
+
+## Errors & resilience
+
+- Transport/process failures raise `officecli.OfficeCliError` (`.code` carries the
+  exit code). Business outcomes (e.g. `validate` failing, a bad path) are **not**
+  exceptions — they live in the returned envelope's `success` field, same as the
+  CLI's exit code.
+- If the resident has gone (crash, idle-timeout, missing pipe), `send`/`batch`
+  transparently restart it and retry once. If it's alive but the pipe is
+  unresponsive (busy), they raise rather than risk racing the live resident.
+
+## Versioning
+
+This client derives the resident's pipe address from the document path the same
+way officecli does. That derivation is the one piece coupled to officecli
+internals, so keep the client version compatible with your installed officecli.

officecli_sdk-0.1.0/README.md

@@ -0,0 +1,100 @@
+# officecli — Python SDK
+
+A **thin** Python SDK for the [officecli](../../) **resident pipe**. It does one
+thing: forward an officecli command to a running resident over its named pipe and
+hand back the response — no per-command process spawn, so a loop of edits is
+~hundreds of times faster than shelling out to the CLI per command.
+
+"Thin" is the point: there is **no second vocabulary** to learn. A command is the
+same dict you'd put in an officecli `batch` list; the SDK just carries it over the
+pipe. Anything a `doc.set_cell(...)` / `doc.add_paragraph(...)` method would do is
+**fully supported** — you just spell it `doc.send({"command": "set", ...})`, with
+the exact same effect. One uniform verb instead of dozens of per-element named
+methods: same power, nothing extra to memorize, and new officecli features work
+the day they ship without an SDK update.
+
+## Requirement: the officecli CLI must be installed
+
+`pip install officecli-sdk` installs **only this SDK** (the Python library). It
+shells out to the `officecli` binary, which must be installed separately and on
+your `PATH` (Homebrew, etc.). If `officecli --version` works in your shell, you're
+set.
+
+## Install
+
+```bash
+pip install officecli-sdk            # once published — note: import name is `officecli`
+# or, from a checkout of this repo:
+pip install ./sdk/python
+```
+
+The pip/distribution name is `officecli-sdk`, but you `import officecli`
+(distribution name ≠ import name, like `pip install pillow` → `import PIL`).
+
+Zero third-party dependencies (standard library only).
+
+## Quickstart
+
+```python
+import officecli
+
+# create() makes a new file and returns a live session handle;
+# open() does the same for an existing file. Both return a Document.
+with officecli.create("report.xlsx", "--force") as doc:
+    doc.send({"command": "set", "path": "/Sheet1/A1",
+              "props": {"text": "Region", "bold": "true"}})
+    doc.send({"command": "set", "path": "/Sheet1/B1", "props": {"formula": "=SUM(B2:B9)"}})
+
+    # read one back (returns the parsed JSON envelope)
+    node = doc.send({"command": "get", "path": "/Sheet1/A1"})
+    print(node["data"]["results"][0]["text"])     # -> Region
+
+    # many edits in ONE pipe round-trip
+    doc.batch([
+        {"command": "set", "path": "/Sheet1/A2", "props": {"text": "North"}},
+        {"command": "set", "path": "/Sheet1/A3", "props": {"text": "South"}},
+    ])
+
+    doc.send({"command": "save"})
+# leaving `with` closes the resident (which flushes to disk)
+
+# borrow an already-running resident without owning it: skip `with`/close()
+d = officecli.open("report.xlsx")
+print(d.send({"command": "view", "mode": "stats"}, as_json=False))
+```
+
+See `demo.py` for a fuller example.
+
+## The command dict
+
+`send(item)` and `batch([item, ...])` take the officecli **batch-item** shape:
+
+```jsonc
+{ "command": "set",            // or "op"; picks the officecli command
+  "path": "/Sheet1/A1",        // every key except command/op/props is forwarded
+  "props": { "text": "hi" } }  // verbatim as a command argument
+```
+
+Keys are officecli's own batch fields (`command`/`op`, `path`, `parent`, `type`,
+`index`, `after`, `before`, `to`, `selector`, `mode`, `depth`, `part`, `xpath`,
+`action`, `xml`) plus a nested `props`. The client maintains no field list of its
+own — run `officecli help` (or see the batch docs) for the full reference.
+
+`send(..., as_json=False)` requests plain-text output (e.g. `view` / `raw` /
+`dump`), mirroring the CLI's `--json` toggle.
+
+## Errors & resilience
+
+- Transport/process failures raise `officecli.OfficeCliError` (`.code` carries the
+  exit code). Business outcomes (e.g. `validate` failing, a bad path) are **not**
+  exceptions — they live in the returned envelope's `success` field, same as the
+  CLI's exit code.
+- If the resident has gone (crash, idle-timeout, missing pipe), `send`/`batch`
+  transparently restart it and retry once. If it's alive but the pipe is
+  unresponsive (busy), they raise rather than risk racing the live resident.
+
+## Versioning
+
+This client derives the resident's pipe address from the document path the same
+way officecli does. That derivation is the one piece coupled to officecli
+internals, so keep the client version compatible with your installed officecli.

officecli_sdk-0.1.0/officecli.py

@@ -0,0 +1,407 @@
+r"""
+officecli — a thin Python shell over officecli's resident pipe.
+
+It does ONE thing: forward a command to the running resident over its named
+pipe and hand back the response. There is NO second vocabulary to learn: a
+command is the same dict you'd put in an officecli `batch` list — e.g.
+{"command":"set","path":"/Sheet1/A1","props":{"text":"Hello"}}. `send` forwards
+one; `batch` forwards many in a single round-trip.
+
+Two surfaces, by design:
+  - bootstrap (infrequent): `create` / `open` spawn ONE CLI process — a file that
+    isn't open yet (or doesn't exist yet) has no resident to talk to.
+  - everything else (the hot path): `send` / `batch` are pure pipe round-trips,
+    no per-command process spawn.
+
+    import officecli
+    with officecli.create("report.xlsx", "--force") as doc:   # make file + get handle
+        doc.send({"command": "set", "path": "/Sheet1/A1",
+                  "props": {"text": "Hello"}})
+        print(doc.send({"command": "get", "path": "/Sheet1/A1"}))
+        doc.send({"command": "save"})
+    # ...or officecli.open("existing.xlsx") for a file that already exists.
+
+The item keys are officecli's batch fields (command/op, path, parent, type,
+index, after, before, to, selector, text, mode, depth, part, xpath, action,
+xml) plus a nested `props` dict. Everything except command/op/props is
+forwarded verbatim as a command argument; the resident dispatches it exactly
+like the matching CLI command. See `officecli help` / the batch docs for the
+field-and-prop reference — this shell adds none of its own.
+
+Protocol (matches ResidentServer.cs / ResidentClient.cs):
+  - pipe name : officecli-<SHA256(fullpath)[:16] uppercase>;
+                fullpath upper-cased on macOS/Windows, left as-is on Linux.
+  - unix path : $TMPDIR/CoreFxPipe_<name>  (+ "-ping");  $TMPDIR else /tmp
+  - win path  : \\.\pipe\<name>            (+ "-ping")
+  - framing   : one request line + one response line, UTF-8, '\n' terminated;
+                one connection == one command.
+  - request   : PascalCase {"Command","Args","Props","Json"}
+  - response  : {"ExitCode","Stdout","Stderr"}
+"""
+
+import os
+import sys
+import json
+import time
+import socket
+import hashlib
+import threading
+import subprocess
+
+# Mirror officecli's TryResident busy-delivery policy (CommandBuilder.cs): a
+# generous connect timeout + a few retries with backoff, applied identically to
+# every command. The reply read itself blocks (no timeout) — like officecli's
+# PipeReadLine — trusting the resident to answer once our turn comes up in its
+# serialized queue. Because retries only re-attempt the CONNECT (before the
+# command executes), re-sending is safe even for mutations; there is no
+# "read timed out, resend" path that could double-apply.
+_BUSY_CONNECT_TIMEOUT = 30.0   # = ResidentBusyConnectTimeoutMs (30000)
+_BUSY_MAX_RETRIES = 3          # = ResidentBusyMaxRetries
+
+_IS_WIN = sys.platform.startswith("win")
+_IS_MAC = sys.platform == "darwin"
+_builtin_open = open   # preserved; this module defines its own open() below
+
+
+class OfficeCliError(Exception):
+    """Raised on transport/process failure (could not reach the resident).
+    Business outcomes are NOT exceptions — they live in the returned envelope's
+    'success' field, same as the CLI's exit code."""
+    def __init__(self, code, msg):
+        super().__init__(f"[exit {code}] {msg}")
+        self.code = code
+
+
+# ---------------------------------------------------------------- pipe address
+def _dotnet_tempdir():
+    # Mirror .NET Path.GetTempPath() on Unix exactly: $TMPDIR else /tmp.
+    return os.environ.get("TMPDIR") or "/tmp"
+
+
+def pipe_paths(file_path):
+    """(main, ping) pipe addresses for a document path. Exposed for debugging."""
+    full = os.path.abspath(file_path)
+    if _IS_MAC or _IS_WIN:
+        full = full.upper()                       # Linux: case-sensitive, no upper
+    h = hashlib.sha256(full.encode("utf-8")).hexdigest().upper()[:16]
+    name = f"officecli-{h}"
+    if _IS_WIN:
+        return rf"\\.\pipe\{name}", rf"\\.\pipe\{name}-ping"
+    base = os.path.join(_dotnet_tempdir(), f"CoreFxPipe_{name}")
+    return base, base + "-ping"
+
+
+# ---------------------------------------------------------------- transport
+# One attempt: bound the CONNECT, then block on the reply (no read timeout) —
+# exactly like officecli's TrySend (Connect(timeout) + blocking PipeReadLine).
+def _send_unix(sock_path, line, connect_timeout):
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        s.settimeout(connect_timeout)
+        s.connect(sock_path)
+        s.settimeout(None)                 # block on the reply; resident answers in turn
+        s.sendall(line)
+        buf = b""
+        while not buf.endswith(b"\n"):
+            chunk = s.recv(65536)
+            if not chunk:
+                break
+            buf += chunk
+        return buf
+    finally:
+        s.close()
+
+
+def _send_win(pipe_path, line, connect_timeout):
+    deadline = time.time() + connect_timeout
+    while True:                            # bound the "open" (connect) phase
+        try:
+            f = _builtin_open(pipe_path, "r+b", buffering=0)   # not the module open()
+            break
+        except OSError:
+            if time.time() > deadline:
+                raise
+            time.sleep(0.02)
+    try:
+        f.write(line)
+        buf = b""
+        while not buf.endswith(b"\n"):     # blocking read, like PipeReadLine
+            chunk = f.read(65536)
+            if not chunk:
+                break
+            buf += chunk
+        return buf
+    finally:
+        f.close()
+
+
+def _rpc(sock_path, req, connect_timeout=_BUSY_CONNECT_TIMEOUT, max_retries=_BUSY_MAX_RETRIES):
+    """Forward one request, mirroring officecli's TrySend: bounded connect + a few
+    retries with backoff, then a blocking read. A retry only re-attempts the
+    connect (before the command runs), so it never double-applies a mutation. If
+    the command still can't be delivered, raise a busy/unresponsive error — never
+    fall back to touching the file directly (that would race the resident).
+
+    `max_retries` overrides the busy-retry count. Liveness probes (_serves) pass 0
+    so a missing/stale pipe fails FAST instead of sleeping through ~0.3s of backoff
+    — retrying a probe the resident isn't answering can't make it answer; the
+    busy-retry policy is for delivering a real command to a slow-but-live pipe."""
+    line = (json.dumps(req, ensure_ascii=False) + "\n").encode("utf-8")
+    send = _send_win if _IS_WIN else _send_unix
+    for attempt in range(max_retries + 1):
+        try:
+            raw = send(sock_path, line, connect_timeout)
+            break
+        except OSError as e:
+            if attempt >= max_retries:
+                raise OfficeCliError(-1,
+                    f"resident is running but the command could not be delivered "
+                    f"(pipe busy or unresponsive); retry, or close and reopen [{e}]")
+            time.sleep(0.05 * (attempt + 1))    # = TrySend's 50*(n+1)ms backoff
+    # utf-8-sig: the resident's StreamWriter (Encoding.UTF8) prepends a BOM the
+    # C# StreamReader strips; we must too, or json.loads chokes on the leading .
+    text = raw.decode("utf-8-sig")
+    if not text.strip():
+        # Empty/closed reply: the resident accepted the connection but closed
+        # without a complete response (e.g. crashed mid-serve). We DELIBERATELY
+        # DIVERGE from officecli's TrySend here: TrySend re-sends on an empty reply
+        # (ResidentClient.cs `if (responseLine == null) continue;`) and returns null
+        # only after exhausting its retries — i.e. it would re-execute a command the
+        # resident may have already applied before dying. We refuse that
+        # double-apply risk and raise instead. _cmd's recovery then restarts a dead
+        # resident and retries once (a fresh connect, before re-send), and
+        # _serves()/alive() (which swallow OfficeCliError) read an empty reply as
+        # "not alive".
+        raise OfficeCliError(-1,
+            "resident closed the connection without a response "
+            "(it may have crashed mid-command); retry, or close and reopen")
+    return json.loads(text)
+
+
+def _parse(resp):
+    """Return the useful payload: the parsed JSON envelope (dict/list) if Stdout is
+    a JSON object/array, otherwise the raw Stdout text ("" when empty). We accept
+    ONLY dict/list from json.loads — a text-mode reply that happens to BE a bare
+    JSON scalar ("42", "true", "null", a quoted string) must stay text, or the
+    caller can't tell literal text "42" from the number 42 (and None from a missing
+    key). Faithful to the response — no synthesizing a dict for view/raw text."""
+    out = resp.get("Stdout", "")
+    try:
+        v = json.loads(out)
+    except ValueError:
+        return out
+    return v if isinstance(v, (dict, list)) else out
+
+
+def _strv(d):
+    # Drop None-valued props (omit), matching how _cmd() drops None args — a prop
+    # set to None means "don't send it", not "send empty string". Pass "" for
+    # an explicit empty value.
+    return {k: str(v) for k, v in d.items() if v is not None}
+
+
+def _serves(ping_path, full_path, timeout=1.0):
+    """Is a resident alive on `ping_path` AND serving `full_path`? Probes the
+    always-responsive `-ping` pipe (officecli's TryConnect equivalent): it answers
+    even while the MAIN pipe is busy. The path-match guards against a stale socket
+    serving a different/renamed file. `full_path` must already be absolute.
+    Single-shot (max_retries=0): a probe should fail fast, not sit through the
+    busy-retry backoff that a real command delivery uses."""
+    try:
+        resp = _rpc(ping_path, {"Command": "__ping__"}, timeout, max_retries=0)
+    except OfficeCliError:
+        return False
+    served = resp.get("Stdout", "").strip()   # ping echoes the served file path
+    if not served:
+        return False
+    a = os.path.abspath(served)
+    return a == full_path or ((_IS_MAC or _IS_WIN) and a.lower() == full_path.lower())
+
+
+# ---------------------------------------------------------------- the shell
+class Document:
+    def __init__(self, path, binary="officecli", timeout=30.0):
+        self.path = os.path.abspath(path)
+        self.bin = binary
+        self.timeout = timeout          # connect timeout (s); the reply read blocks
+        self._main, self._ping = pipe_paths(self.path)
+        self._restart_lock = threading.Lock()   # serialize dead-resident restarts
+        self._start()
+
+    def _start(self):
+        # If a resident is ALREADY serving this file, reuse it — no process spawn.
+        # Mirrors officecli, where a command after `create` reuses the resident
+        # `create` auto-started instead of re-running `open`. _serves() is a real
+        # liveness probe (ping the -ping pipe + verify the served path), not a
+        # socket-file-exists check, so a stale/dead socket fails the probe and
+        # falls through to `officecli open`, which replaces it via TryConnect.
+        # (A plain os.path.exists() here would wrongly skip on a stale socket.)
+        if _serves(self._ping, self.path):
+            return
+        # Otherwise spawn `officecli open` (one process). It's idempotent and uses
+        # the same TryConnect to start a fresh resident or replace a stale socket.
+        r = subprocess.run([self.bin, "open", self.path], capture_output=True, text=True)
+        if r.returncode != 0:
+            raise OfficeCliError(r.returncode, r.stderr or r.stdout)
+
+    # -- transport primitive: build {Command,Args,Props,Json}, forward, parse --
+    def _cmd(self, command, args=None, props=None, as_json=True, timeout=None):
+        # `as_json`, not `json`, so we don't shadow the imported json module.
+        # timeout=None uses this Document's default (self.timeout). It bounds the
+        # CONNECT/delivery (with retries); the reply read blocks, so a legitimately
+        # slow command isn't cut off — it waits for the resident, like officecli.
+        req = {"Command": command, "Json": as_json}
+        if args:
+            req["Args"] = {k: str(v) for k, v in args.items() if v is not None}
+        if props is not None:
+            req["Props"] = _strv(props)
+        t = self.timeout if timeout is None else timeout
+        try:
+            return _rpc(self._main, req, t)
+        except OfficeCliError:
+            # Delivery failed after _rpc's own connect retries. Use the -ping pipe
+            # to tell DEAD from BUSY — officecli's own distinction (alive()):
+            #   • ALIVE but main pipe unresponsive → do NOT bypass it. officecli
+            #     deliberately dropped the direct-file fallback: a second writer
+            #     racing the live resident loses data on its eventual save. Re-raise
+            #     the busy error so the caller can retry or close+reopen.
+            #   • DEAD (crashed / stale socket) → restart with one `officecli open`
+            #     and retry ONCE. Safe across reads and mutations: mutations live in
+            #     memory until save/close, so a crash loses them and disk holds the
+            #     last save — replaying against the restarted (disk-state) resident
+            #     reproduces the lost op once, with nothing live to double-apply.
+            if self.alive():
+                raise
+            # Serialize the restart across threads sharing this Document. Without
+            # the lock, N concurrent callers each see alive()==False and each spawn
+            # `officecli open`, leaving N-1 orphaned residents on the same file
+            # (which can then race each other's save). Re-check alive() inside the
+            # lock so only the first thread restarts; the rest find it back up.
+            with self._restart_lock:
+                if not self.alive():
+                    self._start()
+            return _rpc(self._main, req, t)
+
+    # -- the surface: send ONE batch-shaped command, or a LIST of them ---------
+    def send(self, item, as_json=True, timeout=None):
+        """Forward ONE command in officecli's batch-item shape and return its
+        parsed result (the JSON envelope, or raw text for content commands).
+
+        `item` is exactly a dict you'd put in a `batch` list, e.g.
+            {"command": "set", "path": "/Sheet1/A1", "props": {"text": "hi"}}
+            {"command": "get", "path": "/Sheet1/A1"}
+        Keys are officecli's batch fields; `command` (or `op`) picks the command,
+        `props` becomes the property map, and every other key is forwarded
+        verbatim as a command argument — no field list maintained here, so new
+        officecli fields work without touching this shell.
+
+        `as_json=False` requests plain-text output (view/raw/dump), mirroring the
+        CLI's --json toggle."""
+        command = item.get("command") or item.get("op")
+        if not command:
+            raise OfficeCliError(-1, "send(item): item needs a 'command' (or 'op') key")
+        args = {k: v for k, v in item.items() if k not in ("command", "op", "props")}
+        return _parse(self._cmd(command, args, item.get("props"),
+                                as_json=as_json, timeout=timeout))
+
+    def batch(self, items, force=True, stop_on_error=False, timeout=None):
+        """Forward officecli's `batch` command: apply a LIST of the same item
+        dicts as `send` in ONE round-trip — the fast path for many writes. Same
+        contract as `send`, just plural."""
+        args = {"batchJson": json.dumps(items, ensure_ascii=False),
+                "force": force, "stopOnError": stop_on_error}
+        return _parse(self._cmd("batch", args, timeout=timeout))
+
+    def alive(self, timeout=1.0):
+        """Return True iff a resident is alive AND serving this file. Probes the
+        always-responsive `-ping` pipe (officecli's TryConnect), which answers even
+        while the MAIN pipe is busy — so it distinguishes "alive but busy" from
+        "gone". This is the discriminator `_cmd` uses on a delivery failure (busy →
+        raise, gone → restart+retry); send/batch already auto-recover from a gone
+        resident, so call this only when you want to check liveness yourself."""
+        return _serves(self._ping, self.path, timeout)
+
+    # -- lifecycle ------------------------------------------------------------
+    def close(self):
+        # = `officecli close`: stop the resident. It flushes the in-memory doc to
+        # disk as it shuts down (handler.Dispose), so no separate save is needed —
+        # verified: a set followed by __close__ alone lands on disk.
+        #
+        # The resident acks AFTER shutting down, so a missing/empty ack (lost to a
+        # crash or the 5s write-timeout) still means "closed". A real shutdown
+        # data-loss is a NON-empty error response, so it surfaces through _parse.
+        try:
+            return _parse(_rpc(self._ping, {"Command": "__close__"}, self.timeout))
+        except OfficeCliError:
+            # Only swallow if the resident is actually gone. If it's still alive
+            # (ping pipe was momentarily unreachable/busy), the close did NOT take
+            # effect — re-raise, or the caller wrongly believes the file is released
+            # and may race a re-open/overwrite.
+            if self.alive():
+                raise
+            return ""   # resident gone / ack lost — end state is "closed"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        # `with` means "I manage this session" → close on exit. To only borrow a
+        # resident another program owns, DON'T use `with` and DON'T call close():
+        #     d = officecli.open(f); d.send(...)              # left running
+        self.close()
+
+
+def create(path, *args, binary="officecli", timeout=30.0):
+    """Create a blank Office document and return a live `Document` handle for it.
+
+    Parallel to `open`: both return the session handle you actually work with —
+    they differ only in the file's expected state. `open` requires an existing
+    file; `create` makes a new one (like file mode "x" vs "r"). Extra CLI flags
+    pass through verbatim, so there's no option list maintained here:
+        with officecli.create("report.xlsx", "--force") as doc:
+            doc.send({"command": "set", "path": "/Sheet1/A1", "props": {"text": "hi"}})
+        officecli.create("doc", "--type", "docx")
+
+    One CLI spawn (`officecli create`), which also auto-starts a resident for the
+    new file; the returned Document binds to THAT resident (no second spawn).
+    Raises OfficeCliError on failure, inheriting officecli's exact semantics:
+      • file held by a LIVE resident → file_locked (close it first). We do NOT
+        silently close+overwrite it — in a shared workspace that resident may be
+        another owner's active session.
+      • file exists without --force → file_exists (pass "--force" to overwrite)."""
+    full = os.path.abspath(path)
+    r = subprocess.run([binary, "create", full, *args], capture_output=True, text=True)
+    if r.returncode != 0:
+        raise OfficeCliError(r.returncode, r.stderr or r.stdout)
+    # create auto-started a resident for the new file; bind a handle to it
+    # (Document.__init__ -> _start -> _serves finds it alive, so no extra spawn).
+    return Document(full, binary=binary, timeout=timeout)
+
+
+def open(path, binary="officecli", timeout=30.0):
+    """Open an EXISTING document and return a live `Document` handle (parallel to
+    `create`, which makes a new file). `officecli open` is idempotent: it reuses a
+    resident already serving this file or starts one — and if a live resident is
+    already up, no process is spawned at all.
+
+    Lifecycle:
+      Owner  — `with officecli.open(f) as d: ...`   (exit closes the resident)
+      Borrow — `d = officecli.open(f); d.send(...)` (no `with`/close → left running)
+
+    Failure model (applies to every send/batch on the handle):
+      • resident DEAD/gone (crash, idle-timeout, missing pipe) → transparently
+        restarted and the command retried once; the caller sees no error.
+      • resident ALIVE but the pipe is unresponsive (busy) → raises OfficeCliError
+        — never a deadlock, and never bypassing the live resident (that would race
+        its save and lose data). Retry, or close() and reopen.
+
+    `timeout` bounds command DELIVERY (connect + retries) in seconds, mirroring
+    officecli's TrySend; the reply read itself blocks (a busy resident answers in
+    turn). Override per call via send(..., timeout=...) / batch(..., timeout=...);
+    use alive() to probe liveness."""
+    return Document(path, binary=binary, timeout=timeout)
+
+
+# Advertised surface = the command shell + its error. pipe_paths stays importable
+# (officecli.pipe_paths) as a debug helper but isn't part of the command API.
+__all__ = ["open", "create", "Document", "OfficeCliError"]

officecli_sdk-0.1.0/officecli_sdk.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: officecli-sdk
+Version: 0.1.0
+Summary: Thin Python SDK for the officecli resident pipe — forwards officecli commands to a running resident, no per-command process spawn.
+License-Expression: Apache-2.0
+Keywords: officecli,office,docx,xlsx,pptx,ooxml
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# officecli — Python SDK
+
+A **thin** Python SDK for the [officecli](../../) **resident pipe**. It does one
+thing: forward an officecli command to a running resident over its named pipe and
+hand back the response — no per-command process spawn, so a loop of edits is
+~hundreds of times faster than shelling out to the CLI per command.
+
+"Thin" is the point: there is **no second vocabulary** to learn. A command is the
+same dict you'd put in an officecli `batch` list; the SDK just carries it over the
+pipe. Anything a `doc.set_cell(...)` / `doc.add_paragraph(...)` method would do is
+**fully supported** — you just spell it `doc.send({"command": "set", ...})`, with
+the exact same effect. One uniform verb instead of dozens of per-element named
+methods: same power, nothing extra to memorize, and new officecli features work
+the day they ship without an SDK update.
+
+## Requirement: the officecli CLI must be installed
+
+`pip install officecli-sdk` installs **only this SDK** (the Python library). It
+shells out to the `officecli` binary, which must be installed separately and on
+your `PATH` (Homebrew, etc.). If `officecli --version` works in your shell, you're
+set.
+
+## Install
+
+```bash
+pip install officecli-sdk            # once published — note: import name is `officecli`
+# or, from a checkout of this repo:
+pip install ./sdk/python
+```
+
+The pip/distribution name is `officecli-sdk`, but you `import officecli`
+(distribution name ≠ import name, like `pip install pillow` → `import PIL`).
+
+Zero third-party dependencies (standard library only).
+
+## Quickstart
+
+```python
+import officecli
+
+# create() makes a new file and returns a live session handle;
+# open() does the same for an existing file. Both return a Document.
+with officecli.create("report.xlsx", "--force") as doc:
+    doc.send({"command": "set", "path": "/Sheet1/A1",
+              "props": {"text": "Region", "bold": "true"}})
+    doc.send({"command": "set", "path": "/Sheet1/B1", "props": {"formula": "=SUM(B2:B9)"}})
+
+    # read one back (returns the parsed JSON envelope)
+    node = doc.send({"command": "get", "path": "/Sheet1/A1"})
+    print(node["data"]["results"][0]["text"])     # -> Region
+
+    # many edits in ONE pipe round-trip
+    doc.batch([
+        {"command": "set", "path": "/Sheet1/A2", "props": {"text": "North"}},
+        {"command": "set", "path": "/Sheet1/A3", "props": {"text": "South"}},
+    ])
+
+    doc.send({"command": "save"})
+# leaving `with` closes the resident (which flushes to disk)
+
+# borrow an already-running resident without owning it: skip `with`/close()
+d = officecli.open("report.xlsx")
+print(d.send({"command": "view", "mode": "stats"}, as_json=False))
+```
+
+See `demo.py` for a fuller example.
+
+## The command dict
+
+`send(item)` and `batch([item, ...])` take the officecli **batch-item** shape:
+
+```jsonc
+{ "command": "set",            // or "op"; picks the officecli command
+  "path": "/Sheet1/A1",        // every key except command/op/props is forwarded
+  "props": { "text": "hi" } }  // verbatim as a command argument
+```
+
+Keys are officecli's own batch fields (`command`/`op`, `path`, `parent`, `type`,
+`index`, `after`, `before`, `to`, `selector`, `mode`, `depth`, `part`, `xpath`,
+`action`, `xml`) plus a nested `props`. The client maintains no field list of its
+own — run `officecli help` (or see the batch docs) for the full reference.
+
+`send(..., as_json=False)` requests plain-text output (e.g. `view` / `raw` /
+`dump`), mirroring the CLI's `--json` toggle.
+
+## Errors & resilience
+
+- Transport/process failures raise `officecli.OfficeCliError` (`.code` carries the
+  exit code). Business outcomes (e.g. `validate` failing, a bad path) are **not**
+  exceptions — they live in the returned envelope's `success` field, same as the
+  CLI's exit code.
+- If the resident has gone (crash, idle-timeout, missing pipe), `send`/`batch`
+  transparently restart it and retry once. If it's alive but the pipe is
+  unresponsive (busy), they raise rather than risk racing the live resident.
+
+## Versioning
+
+This client derives the resident's pipe address from the document path the same
+way officecli does. That derivation is the one piece coupled to officecli
+internals, so keep the client version compatible with your installed officecli.

officecli_sdk-0.1.0/officecli_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+officecli.py
+pyproject.toml
+officecli_sdk.egg-info/PKG-INFO
+officecli_sdk.egg-info/SOURCES.txt
+officecli_sdk.egg-info/dependency_links.txt
+officecli_sdk.egg-info/top_level.txt

officecli_sdk-0.1.0/officecli_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

officecli_sdk-0.1.0/officecli_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+officecli

officecli_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]   # >=77 for the PEP 639 SPDX `license` string
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution (pip) name. NOT the import name — the module stays `officecli`
+# (`import officecli`), like `pip install pillow` → `import PIL`. PyPI rejects
+# the bare name "officecli" as too similar to the unrelated "office-cli" project.
+name = "officecli-sdk"
+version = "0.1.0"
+description = "Thin Python SDK for the officecli resident pipe — forwards officecli commands to a running resident, no per-command process spawn."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "Apache-2.0"   # PEP 639 SPDX expression (do NOT also add a License:: classifier — PyPI rejects the combo)
+keywords = ["officecli", "office", "docx", "xlsx", "pptx", "ooxml"]
+dependencies = []  # standard library only
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+]
+# TODO(maintainer): fill in before publishing —
+#   authors = [{ name = "...", email = "..." }]
+#   [project.urls]
+#   Homepage   = "..."
+#   Repository = "..."
+
+# IMPORTANT: this package is only the client. It shells out to the `officecli`
+# CLI binary, which must be installed separately and on PATH (Homebrew, etc.).
+# pip cannot install that binary for you — see README.
+
+[tool.setuptools]
+py-modules = ["officecli"]  # single-file module: officecli.py

officecli_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+