Metadata-Version: 2.4
Name: athena-python-xlsx
Version: 0.1.0
Summary: Drop-in replacement for openpyxl that connects to XLSX Studio for real-time collaboration
Project-URL: Homepage, https://github.com/xlsx-studio/python-sdk
Project-URL: Documentation, https://docs.xlsx-studio.com/sdk/python
Project-URL: Repository, https://github.com/xlsx-studio/python-sdk
Project-URL: Issues, https://github.com/xlsx-studio/python-sdk/issues
Author: XLSX Studio Team
License-Expression: MIT
Keywords: api,excel,openpyxl,sdk,spreadsheet,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: e2e
Requires-Dist: openpyxl>=3.1.0; extra == 'e2e'
Requires-Dist: pytest>=7.0; extra == 'e2e'
Description-Content-Type: text/markdown

# athena-python-xlsx

Drop-in replacement for [openpyxl](https://openpyxl.readthedocs.io/) that connects to XLSX Studio for real-time collaboration.

## Installation

```bash
pip install athena-python-xlsx
```

## Quick Start

```python
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:

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

Or pass them directly:

```python
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:

```python
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

| Feature | Status |
|---------|--------|
| Cell values (str, int, float, bool) | ✅ |
| Formulas | ✅ |
| Cell styles (Font, Fill, Border, Alignment) | ✅ |
| Number formats | ✅ |
| Column widths / Row heights | ✅ |
| Merged cells | ✅ |
| Insert/Delete rows/columns | ✅ |
| Freeze panes | ✅ |
| Auto-filter | ✅ |
| Sheet operations (add, remove, rename, copy) | ✅ |
| Workbook properties | ✅ |
| Charts | 🚧 Planned |
| Images | 🚧 Planned |
| Conditional formatting | 🚧 Planned |
| Data validation | 🚧 Planned |
| Pivot tables | 🚧 Planned |

## Batch Operations

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

```python
# 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}")
```
