Metadata-Version: 2.4
Name: sumoffice
Version: 0.2.0
Summary: Edit Excel, Word and PowerPoint files from Python with the SumSheet, SumDoc and SumSlide cores
Author-email: SumOffice <hello@sumoffice.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Documentation, https://sumoffice.com/python
Keywords: excel,xlsx,xlsm,docx,pptx,spreadsheet,office,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: license-file

# sumoffice for Python

Open, edit, recalculate and save Excel workbooks, read Word documents and add
slides to PowerPoint decks from Python. The package ships the native SumSheet,
SumDoc and SumSlide cores inside the wheel: nothing is compiled on install, and
you need neither Microsoft Office, LibreOffice nor a document server.

```sh
pip install sumoffice
```

Wheels exist for macOS (Apple silicon and Intel), Linux x86-64 and aarch64
(glibc 2.28 or newer) and Windows x64, for Python 3.10 and newer.

## First result in five lines

```python
import sumoffice

wb = sumoffice.open("report.xlsm")
wb["Cash flow"]["B7"] = 42
wb.save("report-edited.xlsm")
```

The VBA project, Power Query parts and images stay in the saved file byte for
byte; `sumoffice` never rewrites parts it did not change.

## Three examples

### 1. Change a cell in a macro workbook and keep the macros

```python
import sumoffice

wb = sumoffice.open("budget.xlsm")
print(wb.sheet_names)                 # ('Cash flow', 'Summary')
wb["Cash flow"]["B7"] = 42            # number, text, None, or a formula "=B5*2"
wb.save("budget-edited.xlsm")         # vbaProject.bin is kept as it was
```

### 2. Recalculate and read the results back

```python
import sumoffice

wb = sumoffice.open("model.xlsx")
sheet = wb["Summary"]
sheet["A1"] = 1200
sheet["A2"] = "=A1*1.2"
wb.recalc()
print(sheet["A2"])                    # 1440
print(sheet.formula("A2"))            # '=A1*1.2'
print(sheet.read("A1:B3"))            # [[1200, None], [1440, None], [None, None]]
wb.save("model-edited.xlsx")

again = sumoffice.open("model-edited.xlsx")
assert again["Summary"]["A2"] == 1440
```

### 3. Read the text of a Word document; add a slide to a deck

```python
import sumoffice

print(sumoffice.text("contract.docx"))

deck = sumoffice.open("deck.pptx")
deck.add_slide()
print(deck.slide_count)
deck.save("deck-edited.pptx")
```

## Use it from Claude Desktop, Cursor or another MCP client

The package includes a local MCP server that works only with files on your
computer. Nothing is sent anywhere.

```json
{
  "mcpServers": {
    "sumoffice": { "command": "/full/path/to/venv/bin/sumoffice-mcp" }
  }
}
```

Desktop apps do not read your shell's `PATH`, so give the full path: run
`which sumoffice-mcp` (Windows: `where sumoffice-mcp`) in the environment where
you installed the package. In Claude Desktop the file is
`claude_desktop_config.json` (Settings → Developer → Edit Config); restart the
app after saving.

Tools: `open_workbook`, `read_range`, `write_cells`, `recalc`, `save_copy`,
`document_text`. By default the server reads files under your home directory;
set `SUMOFFICE_MCP_ROOTS` (paths separated by the OS path separator) to allow
other folders. `save_copy` never overwrites the source file.

## What is free

| | Without a key | With a developer key |
|---|---|---|
| Documents per day | 200 | 10,000 |
| Term | no expiry | 90 days from issue |
| When the quota is used up | `LicenseQuotaError` right away, with a link to the key page; no waiting, no slowdown | the same |

A document counts once per opening, however many cells you change. Request a
developer key at <https://sumoffice.com/python#developer-key>. Put the key in
`SUMOFFICE_LICENSE`, or the path to the key file in `SUMOFFICE_LICENSE_FILE`.

The daily quota is enforced by the Word core today. The spreadsheet and
presentation cores do not count documents yet, so their use is currently not
limited.

## What it does not do

- It does not run VBA macros; it keeps them.
- XLSX to PDF conversion and page previews are not in this wheel yet:
  `sumoffice.convert()` and `sumoffice.preview()` raise
  `CapabilityUnavailableError` and create no file.
- Word support is read-only in the high-level API (`sumoffice.text`); editing
  goes through the low-level `Session`.
- The Word core uses system fonts. On a server without fonts set
  `FASTDOC_FONT_DIR` to a folder with the document's fonts for stable layout.
- A wheel works only on the operating system and CPU named in its file name.
- Error messages are in Russian in this release.

## Low level

`sumoffice.Session` opens a document in one core and accepts the core's own
JSON commands. Engines are called `"sheet"`, `"doc"` and `"slide"` (the names
`"sumsheet"`, `"sumdoc"` and `"sumslide"` also work). Call
`session.handshake()` to see the operations a core supports.

## Documentation and support

- Documentation: <https://sumoffice.com/python>
- Support: hello@sumoffice.com
- Terms: see `LICENSE.txt` in the package.
