Skip to content
Office Oxide

Biblioteca Office para Python — Início Rápido

office_oxide é a biblioteca Python mais rápida para documentos do Office. Núcleo em Rust puro, API idiomática em Python, zero dependências em runtime. Lê DOCX, XLSX, PPTX (e os legados DOC, XLS, PPT) em menos de um milissegundo — 8 a 100× mais rápido que python-docx, openpyxl e python-pptx.

Instalação

pip install office-oxide

Wheels publicadas para CPython 3.8–3.14 em Linux, macOS e Windows. O nome no PyPI é office-oxide (com hífen); o import é office_oxide (com underscore).

Ler um documento

from office_oxide import Document

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

Ou o helper de uma só chamada:

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

API principal

Document.open detecta o formato pela extensão (e confirma com magic bytes). Aceita str, bytes ou qualquer os.PathLike. Use como context manager para liberar a memória nativa de forma determinística.

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 — Markdown estilo GitHub
    print(doc.to_html())        # str — HTML semântico
    ir = doc.to_ir()            # dict aninhado (DocumentIR)

    doc.save_as("deck.docx")    # legado PPT → PPTX também funciona

Para arquivos fora do disco, abra a partir de bytes:

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

Funções auxiliares do módulo:

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"

Edição

EditableDocument preserva todas as partes OPC inalteradas (imagens, gráficos, estilos, relações) ao salvar. Apenas DOCX, XLSX e PPTX.

from office_oxide import EditableDocument

with EditableDocument.open("template.docx") as ed:
    n = ed.replace_text("{{name}}", "Alice")
    print(f"{n} substituições")
    ed.save("out.docx")

Substituir texto em 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 percorre elementos <w:t> no DOCX e <a:t> em cada slide do PPTX. Devolve a quantidade de substituições.

Escrever células XLSX

from office_oxide import EditableDocument

with EditableDocument.open("budget.xlsx") as ed:
    ed.set_cell(0, "A1", "Total")     # string
    ed.set_cell(0, "B1", 42.5)        # número (int também aceito)
    ed.set_cell(0, "C1", True)        # booleano
    ed.set_cell(0, "D1", None)        # vazio
    ed.save("budget.xlsx")

sheet_index é zero-indexado; cell_ref segue a notação padrão (A1, AA12).

IR independente do formato

doc.to_ir() devolve um dict aninhado que espelha o DocumentIR do Rust: seções de títulos, parágrafos, tabelas, listas e imagens. Útil para pipelines e para alimentar contexto estruturado a LLMs.

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" | ...

Pipelines em bytes

from_bytes evita arquivos temporários em fluxos serverless e de streaming:

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())

Formatos legados

DOC, XLS e PPT usam a mesma API. A extensão escolhe o parser CFB legado automaticamente; save_as produz um OOXML moderno de forma transparente:

with Document.open("legacy.doc") as doc:
    print(doc.plain_text())
    doc.save_as("legacy.docx")     # DOC → DOCX em uma linha

Erros

Falhas de parse e IO disparam OfficeOxideError. Falhas de IO em save_as são embrulhadas em 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 falhou: {e}")
except FileNotFoundError:
    print("arquivo não encontrado")

Solução de problemas

Sintoma Causa provável
OfficeOxideError: unsupported format: "" O caminho não tem extensão — use Document.from_bytes(data, "docx").
RuntimeError: Document is closed Você saiu do with mas ainda mantém uma referência. Abra um handle novo.
ImportError: _native A wheel não bate com sua plataforma. pip install --force-reinstall office-oxide.
DOC legado mostra texto embaralhado O arquivo pode estar criptografado (Word 97 RC4). office_oxide não descriptografa — descriptografe primeiro com LibreOffice.
Problemas de Unicode no Windows Use pathlib.Path em vez de caminhos em bytes; Document.open cuida da codificação da plataforma.

Veja também