Skip to content
Office Oxide

Python-бібліотека для Office — швидкий старт

office_oxide — найшвидша Python-бібліотека для документів Office. Ядро на чистому Rust, ідіоматичний Python API, жодних рантайм-залежностей. Читання DOCX, XLSX, PPTX (а також застарілих DOC, XLS, PPT) триває менше мілісекунди — у 8–100 разів швидше за python-docx, openpyxl, python-pptx.

Встановлення

pip install office-oxide

Wheel-пакети опубліковано для CPython 3.8–3.14 на Linux, macOS і Windows. На PyPI пакет — office-oxide (з дефісом), у коді імпортуйте office_oxide (з підкресленням).

Прочитати документ

from office_oxide import Document

with Document.open("report.docx") as doc:
    print(doc.plain_text())

Або коротша форма:

import office_oxide
print(office_oxide.extract_text("report.docx"))

Базовий API

Document.open визначає формат за розширенням (і перевіряє magic-байтами). Приймає str, bytes або будь-який os.PathLike. Використовуйте як контекстний менеджер, щоб нативна пам’ять звільнялася детерміновано.

from pathlib import Path
from office_oxide import Document

with Document.open(Path("data/deck.pptx")) as doc:
    print(doc.format)           # "pptx"
    print(doc.plain_text())     # str
    print(doc.to_markdown())    # str — GitHub-flavored Markdown
    print(doc.to_html())        # str — семантичний HTML
    ir = doc.to_ir()            # вкладений dict (DocumentIR)

    doc.save_as("deck.docx")    # підтримується також конвертація старих PPT у PPTX

Якщо файлу немає на диску — відкривайте з байтів:

data = open("report.xlsx", "rb").read()
with Document.from_bytes(data, "xlsx") as doc:
    print(doc.plain_text())

Скорочення на рівні модуля:

import office_oxide
office_oxide.extract_text("file.docx")   # → str
office_oxide.to_markdown("file.pptx")    # → str
office_oxide.to_html("file.xlsx")        # → str
office_oxide.version()                   # → "0.1.0"

Редагування

EditableDocument зберігає дослівно всі незмінені OPC-частини (зображення, діаграми, стилі, зв’язки). Підтримуються лише DOCX, XLSX і PPTX.

from office_oxide import EditableDocument

with EditableDocument.open("template.docx") as ed:
    n = ed.replace_text("{{name}}", "Alice")
    print(f"{n} замін")
    ed.save("out.docx")

Заміна тексту в DOCX / PPTX

from office_oxide import EditableDocument

with EditableDocument.open("slides.pptx") as ed:
    ed.replace_text("Q3", "Q4")
    ed.replace_text("2024", "2025")
    ed.save("slides_q4.pptx")

replace_text обходить елементи <w:t> у DOCX та <a:t> на кожному слайді PPTX і повертає кількість замін.

Запис клітинок XLSX

from office_oxide import EditableDocument

with EditableDocument.open("budget.xlsx") as ed:
    ed.set_cell(0, "A1", "Total")     # рядок
    ed.set_cell(0, "B1", 42.5)        # число (int теж)
    ed.set_cell(0, "C1", True)        # булеве
    ed.set_cell(0, "D1", None)        # порожнє
    ed.save("budget.xlsx")

sheet_index нумерується з нуля; cell_ref — стандартна нотація (A1, AA12).

Формат-незалежний IR

doc.to_ir() повертає вкладений dict, що відображає Rust-структуру DocumentIR: секції з заголовків, абзаців, таблиць, списків і зображень. Зручно для пайплайнів і подачі структурованого контексту в LLM.

ir = doc.to_ir()
for section in ir["sections"]:
    print(section.get("title"))
    for el in section["elements"]:
        kind = el["kind"]   # "Heading" | "Paragraph" | "Table" | "List" | ...

Робота з байтами

from_bytes рятує від тимчасових файлів у serverless та стрімінгових сценаріях:

import requests
from office_oxide import Document

data = requests.get("https://example.com/doc.docx").content
with Document.from_bytes(data, "docx") as doc:
    print(doc.to_markdown())

Legacy-формати

DOC, XLS та PPT працюють через той самий API. За розширенням автоматично обирається legacy CFB-парсер; save_as прозоро записує сучасний OOXML:

with Document.open("legacy.doc") as doc:
    print(doc.plain_text())
    doc.save_as("legacy.docx")     # DOC → DOCX одним рядком

Помилки

Помилки парсингу та IO кидають OfficeOxideError. IO-помилки save_as обгортаються в IOError.

from office_oxide import Document, OfficeOxideError

try:
    with Document.open("weird.file") as doc:
        print(doc.plain_text())
except OfficeOxideError as e:
    print(f"office_oxide збій: {e}")
except FileNotFoundError:
    print("файл не знайдено")

Діагностика

Симптом Причина
OfficeOxideError: unsupported format: "" У шляху немає розширення — використайте Document.from_bytes(data, "docx").
RuntimeError: Document is closed Ви вийшли з with, але все ще тримаєте посилання. Відкрийте нову.
ImportError: _native Wheel не підходить платформі. pip install --force-reinstall office-oxide.
Legacy DOC видає кашу Файл може бути зашифрованим (Word 97 RC4). office_oxide не розшифровує — розшифруйте спочатку через LibreOffice.
Проблеми з Unicode на Windows Використовуйте pathlib.Path замість байтових шляхів; Document.open сам розбереться з кодуванням.

Дивіться також