athena-python-xlsx

Drop-in replacement for openpyxl that connects to XLSX Studio for real-time collaboration.

Installation

pip install athena-python-xlsx

Quick Start

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

# Create a new workbook
wb = Workbook.create(name="Sales Report")
ws = wb.active

# Headers
headers = ["Product", "Q1", "Q2", "Q3", "Q4", "Total"]
for col, header in enumerate(headers, 1):
    cell = ws.cell(row=1, column=col, value=header)
    cell.font = Font(bold=True, size=12)
    cell.fill = PatternFill(fgColor="4472C4")
    cell.alignment = Alignment(horizontal="center")

# Data
data = [
    ["Widget A", 150, 200, 180, 220],
    ["Widget B", 300, 280, 350, 400],
    ["Widget C", 100, 120, 90, 110],
]

for row_idx, row_data in enumerate(data, 2):
    for col_idx, value in enumerate(row_data, 1):
        ws.cell(row=row_idx, column=col_idx, value=value)
    # Total formula
    ws.cell(row=row_idx, column=6, value=f"=SUM(B{row_idx}:E{row_idx})")

# Column widths
ws.column_dimensions['A'].width = 15

# Save
wb.save("sales_report.xlsx")

Configuration

Set these environment variables:

export ATHENA_XLSX_BASE_URL=https://api.xlsx-studio.com
export ATHENA_XLSX_API_KEY=your-api-key  # optional

Or pass them directly:

wb = Workbook(workbook_id="wb_123", base_url="https://api.xlsx-studio.com")

Athena Assets

To connect to an existing Athena spreadsheet asset, pass the org_id parameter:

wb = Workbook(
    workbook_id="asset_5a9fbe63-a63f-4ba3-8d3d-11231bbb67dc",
    base_url="https://api.xlsx-studio.com",
    org_id="workspace_5fd97d12-eda1-4191-82e5-b6fe5cb61dcc",
)
ws = wb.active
ws['A1'] = "Hello from Python!"
wb.close()  # Flushes changes

How It Works

This SDK implements the openpyxl API surface as a proxy layer over the XLSX Studio API:

• Read path: GET /workbooks/{id}/snapshot → JSON → Python proxy objects (Workbook, Worksheet, Cell)
• Write path: Property setter → Command dataclass → CommandBuffer → POST /workbooks/{id}/commands → server applies to Yjs Y.Doc
• Export path: POST /workbooks/{id}/export → server rebuilds XLSX from Y.Doc → download

Changes are applied in real-time via Yjs, so other users see edits instantly in the browser.

API Compatibility

Batch Operations

By default, commands are auto-batched with a 2-second debounce timer. For explicit control:

# Explicit batch - all commands sent in one request
with wb.batch():
    for row in range(1, 1001):
        ws.cell(row=row, column=1, value=f"Row {row}")