Skip to content
Office Oxide

Migrar do python-docx

Office Oxide é uma substituição direta para os usos mais comuns do python-docx — extração de texto, iteração de parágrafos, leitura de tabelas, find-and-replace — com 14× a velocidade e taxa de sucesso 3,8 pontos percentuais maior em um corpus de 2.538 DOCX. Bônus: você para de vendorizar bibliotecas diferentes para .xlsx (openpyxl), .pptx (python-pptx) e DOC legado (catdoc / antiword) — um pip install cobre os seis formatos.

Quando migrar

Troca se você faz qualquer um destes:

  • Extrai texto ou Markdown de .docx para ingestão / RAG / busca
  • Roda templates de find-and-replace em milhares de documentos
  • Lê tabelas de contratos ou relatórios
  • Quer também processar .xlsx, .pptx ou formatos legados sem adicionar mais dependências

Fica no python-docx se você faz isto e não quer descer para a API Rust específica do formato:

  • Constrói DOCX complexos do zero com estilos e temas customizados
  • Precisa de bibliotecas de extensão do python-docx (ex.: docxcompose, python-docx-ng)

Instalação

pip uninstall python-docx
pip install office-oxide

O nome no PyPI é office-oxide (com hífen); o import é office_oxide (com underscore).

Cheat sheet lado a lado

Texto puro

python-docx

from docx import Document

doc = Document("report.docx")
text = "\n".join(p.text for p in doc.paragraphs)

office_oxide

from office_oxide import Document

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

Uma chamada de método, inclui cabeçalhos e rodapés, e ~14× mais rápido.

Markdown / HTML

python-docx — sem Markdown / HTML embutido; você precisaria recorrer a pandoc, mammoth ou escrever um conversor à mão.

office_oxide

from office_oxide import Document

with Document.open("report.docx") as doc:
    md   = doc.to_markdown()
    html = doc.to_html()

Iterar parágrafos

python-docx

from docx import Document

doc = Document("report.docx")
for p in doc.paragraphs:
    print(p.style.name, p.text)

office_oxide (via IR)

from office_oxide import Document

with Document.open("report.docx") as doc:
    ir = doc.to_ir()

for section in ir["sections"]:
    for el in section["elements"]:
        if el["kind"] == "Heading":
            print(f"H{el['level']}", el["text"])
        elif el["kind"] == "Paragraph":
            print("P", " ".join(r["text"] for r in el["runs"]))

Iterar tabelas

python-docx

from docx import Document

doc = Document("report.docx")
for table in doc.tables:
    for row in table.rows:
        cells = [cell.text for cell in row.cells]
        print(cells)

office_oxide

from office_oxide import Document

with Document.open("report.docx") as doc:
    ir = doc.to_ir()

for section in ir["sections"]:
    for el in section["elements"]:
        if el["kind"] == "Table":
            for row in el["rows"]:
                print(row)

Find and replace (templating)

python-docx — sem API de primeira classe; o padrão comum é varrer todo run e reescrever o texto, o que quebra em matches cross-run. A maioria recorre a docx-mailmerge ou regex frágil.

office_oxide

from office_oxide import EditableDocument

with EditableDocument.open("template.docx") as ed:
    n = ed.replace_text("{{client_name}}", "Acme Corp")
    print(f"{n} substituições")
    ed.save("filled.docx")

replace_text lida com matches cross-run de forma transparente e preserva todas as partes OPC inalteradas (imagens, gráficos, estilos).

Ler core properties

python-docx

from docx import Document

doc = Document("report.docx")
print(doc.core_properties.author)
print(doc.core_properties.modified)

office_oxide

from office_oxide import Document

with Document.open("report.docx") as doc:
    props = doc.as_docx().core_properties()
    print(props.author)
    print(props.modified)

O que o office_oxide ainda não expõe

O EditableDocument unificado cobre o caso de templating. Para construção de DOCX mais rica — adicionar parágrafos, montar tabelas programaticamente, aplicar estilos nomeados — desça para o módulo específico do formato:

from office_oxide.docx import DocxBuilder

builder = DocxBuilder()
builder.add_heading("Relatório Q4", level=1)
builder.add_paragraph("Receita cresceu 18%.")
builder.save("report.docx")

Ou gere a partir do IR com create_from_ir(ir, "docx", "report.docx"). Veja Construir a partir do IR.

Performance

Mesmo corpus de 2.538 arquivos, single-thread:

Biblioteca Média p99 Taxa de sucesso
office_oxide 0,8 ms 3,9 ms 98,9%
python-docx 11,8 ms 98 ms 95,1%

Uma ingestão de um milhão de documentos que demora 3 h 16 min com python-docx termina em 14 minutos com office_oxide no mesmo hardware.

Veja também