athena-openpyxl

openpyxl-shaped Python SDK that talks to xlsx-studio's HTTP API. Writes go through POST /workbooks/:id/commands; the Fastify service applies them to a server-side pycrdt Doc and pushes Y.Doc updates to Keryx so Olympus's @rowsncolumns/y-spreadsheet renderer sees the change live. The SDK process never opens its own y-websocket — there is no pycrdt dependency on the SDK side.

Status: v0.2.0 — Tier-A surface complete (full openpyxl public API up to formatting + dates), Tier-B surfaces (tables / data validation / conditional formatting / defined names / comments / images / hyperlinks) wired through the Keryx Y.Doc.

Quick start

from openpyxl import Workbook

with Workbook("asset_abc123") as wb:   # opens Keryx session, runs initial sync
    ws = wb.active
    ws["A1"] = "Hello"
    ws["A2"] = 42
    ws["A3"] = "=SUM(A2)"
    wb.save()                          # flushes pending updates to Keryx

Branch + agent attribution:

from openpyxl import Workbook

with Workbook(
    "asset_abc",
    branch="suggest-run-7",
    custom_attributions=[
        {"k": "agent_id", "v": "spreadsheet-author"},
        {"k": "user_message_tracking_id", "v": "msg_xyz"},
    ],
) as wb:
    wb.active["A1"] = "agent edit"
    wb.save()

Bulk writes via batch context (one logical activity-log entry):

from openpyxl import Workbook

with Workbook("asset_abc") as wb:
    ws = wb.active
    with wb.batch():
        for row_idx in range(1, 1001):
            ws.cell(row_idx, 1, f"row {row_idx}")
        wb.save()

Environment

The SDK reads these env vars (Daytona-managed in production):

Install (development)

cd xlsx-studio/python-sdk
uv venv && uv pip install -e ".[dev]"
uv run pytest tests/

Public surface (v0.2.0)

Tier A — Core (fully implemented):

Tier B — Common (wired through Keryx Y.Doc):

Tier C — Advanced (raises UnsupportedFeatureError):

• Charts and chartsheets (waiting on the cross-studio chart engine extraction from pptx-studio — see pptx-studio/docs/CHARTING_REFACTOR_PLAN_2026-04-21.md).
• Pivot tables.
• Sheet/workbook protection write side.
• Page setup write side.
• Macros / VBA passthrough.

See docs/API_PARITY_EXCEPTIONS.md for the canonical list of intentional deviations.

Common gotchas

• Vertical alignment defaults to bottom, not center. Both Excel and openpyxl default Alignment.vertical to "bottom", so a brand-new KPI tile, banner row, or centered headline cell will draw text glued to the bottom edge until you set vertical="center" explicitly. Set it on the cell that anchors the visual:

  from openpyxl.styles import Alignment
  
  cell.alignment = Alignment(horizontal="center", vertical="center")
  

  The same applies to merged ranges — set the alignment on the anchor cell (top-left of the merge) before or after ws.merge_cells(...); the renderer reads the anchor cell's style. The ws.merge_and_style(...) helper does this correctly out of the box.

Architecture

Agent code (openpyxl idiom)
    ↓
Workbook / Worksheet / Cell           (sync facade)
    ↓  CommandBuffer.append(<cmd>)
batching.CommandBuffer                (groups + flushes)
    ↓  Client.post_commands(...)
HTTP POST /workbooks/:id/commands     (Bearer auth + ownership middleware)
    ↓
xlsx-studio apps/api (Fastify)        (validates schema, runs applier.ts)
    ↓  pycrdt Doc transactions
Keryx  ←→  Olympus (@rowsncolumns/y-spreadsheet renderer)
  (Y.Doc lives server-side; room = "{workspace}/{asset_id}")

• client.py — requests-backed HTTP client: auth, retries (urllib3 Retry), 401/409/4xx error mapping (AuthenticationError/ConflictError/RemoteError), and the workbook / commands / snapshot / export endpoints.
• batching.py — CommandBuffer queues SDK calls into a single POST /commands payload (so one cell or one bulk write becomes one HTTP round-trip, not N) and flush_all() for end-of-script drain.
• commands.py — typed dataclasses (SetCellValue, SetCellStyle, SetIterativeCalculation, …) with .validate() and .to_dict(). Each one round-trips against apps/api/src/commands/types.ts Zod schemas.
• cell/, worksheet/, workbook/, styles/, comments/, formatting/, drawing/, pivot/, tables.py — openpyxl-shaped surface; reads materialize from snapshot (Client.get_snapshot), writes append commands to the buffer.

Publishing

bash ../scripts/publish-python-sdk.sh 0.2.0

Development workflow

# Install editable + dev tools.
uv venv && uv pip install -e ".[dev]"

# Run the unit suite (no Keryx required).
uv run pytest tests/ -x

# Lint.
uv run ruff check openpyxl tests

Tests

The SDK ships ~190 unit tests covering: utility helpers, all five style descriptors (Font / Fill / Alignment / Border / Protection / NamedStyle), Workbook lifecycle / registry / flush_all, single-cell I/O, range access, iter_rows / iter_cols, append, max_row / max_column, dimensions, structural mutations, merges, freeze panes, auto filter, cell formatting, dates, comments, hyperlinks, and the UnsupportedFeatureError boundary.

Tests stub the HTTP transport (Client._request) and assert on the captured command payloads — no network access required.

The integration / parity / fidelity lanes live separately (see the roadmap doc at xlsx-studio/docs/ATHENA_OPENPYXL_ROADMAP_2026-04-29.md).