iofficeai--officecli/sdk/python/README.md

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.

The officecli CLI (auto-installed if missing)

pip install officecli-sdk installs only this SDK (the Python library); the real work is done by the officecli binary. You don't have to install it yourself — if officecli isn't found on your PATH (or in the default install location), the SDK provisions it on first use: it runs officecli's official installer (install.sh on macOS/Linux, install.ps1 on Windows), fetching from the d.officecli.ai mirror with GitHub as a fallback. A one-line notice is printed before it installs — it never does so silently. Pass auto_install=False to open()/create() to disable this and require a pre-installed CLI instead.

To install the CLI ahead of time (or to control where it lands):

python -m officecli install      # runs officecli's official installer
# …or directly:
curl -fsSL https://d.officecli.ai/install.sh | bash
# Windows (PowerShell):
irm https://d.officecli.ai/install.ps1 | iex

officecli.install() does the same from Python. If the CLI can't be found or installed, the SDK raises a clear error pointing here (never a cryptic FileNotFoundError).

Install

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

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:

{ "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.