Metadata-Version: 2.4
Name: a4office
Version: 2026.4.3
Summary: Книги Excel, документы Word и презентации PowerPoint из Python: ядра F1, A4 и P2
Author: A4 Office
License-Expression: LicenseRef-Proprietary
Project-URL: Documentation, https://tech.plantype.ru/python.html
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

# a4office для Python

Открывайте, правьте, пересчитывайте и сохраняйте книги Excel, читайте документы
Word и добавляйте слайды в презентации PowerPoint прямо из Python. Внутри колеса —
нативные ядра F1 (таблицы), A4 (документы) и P2 (презентации): при установке
ничего не компилируется, не нужны ни Microsoft Office, ни LibreOffice. Файлы не
покидают ваш компьютер. Показать документы людям и дать их править в браузере —
Сервер A4.

```sh
pip install a4office --find-links https://dl.plantype.ru/a4office/release/<версия-ядра>/ --no-index
```

`a4office.core_version()` возвращает точную версию ядра внутри пакета.

Пакет раздаётся с сервера загрузок dl.plantype.ru, а не из общего каталога PyPI.
`pip` сам выберет колесо своей платформы; зависимостей у пакета нет, поэтому
`--no-index` безопасен.

Колёса есть для macOS (Apple silicon и Intel), Linux x86-64 и aarch64 (glibc 2.28
и новее) и Windows x64, для Python 3.10 и новее.

## Первый результат за пять строк

```python
import a4office

wb = a4office.open("отчёт.xlsm")
wb["Движение денег"]["B7"] = 42
wb.save("отчёт-правка.xlsm")
```

Проект VBA, части Power Query и картинки остаются в сохранённом файле байт в
байт: пакет не переписывает то, чего вы не меняли.

## Три примера

### 1. Изменить ячейку в книге с макросами и сохранить макросы

```python
import a4office

wb = a4office.open("бюджет.xlsm")
print(wb.sheet_names)                 # ('Движение денег', 'Итоги')
wb["Движение денег"]["B7"] = 42       # число, текст, None или формула "=B5*2"
wb.save("бюджет-правка.xlsm")         # vbaProject.bin остаётся прежним
```

### 2. Пересчитать и прочитать результат

```python
import a4office

wb = a4office.open("модель.xlsx")
лист = wb["Итоги"]
лист["A1"] = 1200
лист["A2"] = "=A1*1.2"
wb.recalc()
print(лист["A2"])                     # 1440
print(лист.formula("A2"))             # '=A1*1.2'
print(лист.read("A1:B3"))             # [[1200, None], [1440, None], [None, None]]
wb.save("модель-правка.xlsx")

снова = a4office.open("модель-правка.xlsx")
assert снова["Итоги"]["A2"] == 1440
```

### 3. Прочитать текст документа Word; добавить слайд в презентацию

```python
import a4office

print(a4office.text("договор.docx"))

deck = a4office.open("презентация.pptx")
deck.add_slide()
print(deck.slide_count)
deck.save("презентация-правка.pptx")
```

## Показать на своём сервере

В библиотеке нет просмотрщика. Без `A4OFFICE_SERVER_URL` вызов
`a4office.view(path)` возвращает настоящую команду получения Сервера A4. Если
задать этот адрес и `A4OFFICE_SERVER_TOKEN`, библиотека передаст локальный
файл в `POST /sdk/v1/documents` и вернёт подписанный `editor_url` сервера.

```python
редактор = a4office.view("отчёт-правка.xlsx")
print(редактор.editor_url)
```

## Из Claude Desktop, Cursor и других клиентов MCP

В пакете есть местный сервер MCP. Он работает только с файлами на вашем
компьютере и ничего никуда не отправляет.

```json
{
  "mcpServers": {
    "a4office": { "command": "/полный/путь/к/venv/bin/a4office-mcp" }
  }
}
```

Настольные программы не читают `PATH` вашей оболочки, поэтому нужен полный
путь: выполните `which a4office-mcp` (в Windows — `where a4office-mcp`) в том
окружении, куда поставили пакет. В Claude Desktop это файл
`claude_desktop_config.json` (Settings → Developer → Edit Config); после
сохранения перезапустите программу.

Инструменты: `open_workbook`, `read_range`, `write_cells`, `recalc`, `save_copy`,
`document_text`. По умолчанию сервер читает файлы в домашнем каталоге; другие
папки разрешает переменная `A4OFFICE_MCP_ROOTS` (пути через разделитель путей
системы). `save_copy` никогда не перезаписывает исходный файл.

## Что бесплатно

| | Без ключа | С ключом разработчика |
|---|---|---|
| Документов в сутки | 30 | 10 000 |
| Срок | без срока | 90 дней с выдачи |
| Когда квота кончилась | сразу `LicenseQuotaError` со ссылкой на страницу ключа; без ожидания и без замедления | так же |

Документ считается один раз за открытие, сколько бы ячеек вы ни меняли. Ключ
разработчика: <https://tech.plantype.ru/python.html#klyuch>. Ключ положите в
переменную `A4OFFICE_LICENSE` или путь к файлу ключа — в `A4OFFICE_LICENSE_FILE`.

Шрифты, которых нет в системе, ядро берёт со склада свободных шрифтов
<https://dl.plantype.ru/fonts/release/v1/>. Свой склад — переменная
`FASTDOC_FONT_WAREHOUSE`; заданное вами пакет не перетирает.

Сейчас документы считает ядро документов A4. Ядра таблиц и презентаций пока
не считают документы, поэтому работа с ними сейчас не ограничена.

## Чего пакет не умеет

- Не исполняет макросы VBA — только сохраняет их.
- Преобразования в PDF и картинок страниц в этом колесе ещё нет:
  `a4office.convert()` и `a4office.preview()` поднимают
  `CapabilityUnavailableError` и не создают файла.
- Документы Word в коротком API только читаются (`a4office.text`); правка —
  через низкоуровневый `Session`.
- Ядро документов берёт системные шрифты. На сервере без шрифтов задайте
  `FASTDOC_FONT_DIR` — папку со шрифтами документа, чтобы вёрстка не плыла.
- Колесо работает только на системе и процессоре из его имени.

## Низкий уровень

`a4office.Session` открывает документ в одном ядре и принимает собственные
команды ядра в JSON. Движки называются `"sheet"`, `"doc"` и `"slide"` (работают и
имена `"f1"`, `"a4"`, `"p2"`). `session.handshake()` показывает, какие операции
ядро умеет.

## Документация

- Документация: <https://tech.plantype.ru/python.html>
- Условия — `LICENSE.txt` в пакете.
