Skip to content
Office Oxide

Python-Bibliothek für Office — Schnellstart

office_oxide ist die schnellste Python-Bibliothek für Office-Dokumente. Reiner Rust-Kern, idiomatische Python-API, keine Laufzeit-Abhängigkeiten. DOCX, XLSX, PPTX (sowie die Altformate DOC, XLS, PPT) werden in unter einer Millisekunde gelesen — 8- bis 100-mal schneller als python-docx, openpyxl und python-pptx.

Installation

pip install office-oxide

Wheels für CPython 3.8–3.14 sind für Linux, macOS und Windows veröffentlicht. Der Distributionsname auf PyPI ist office-oxide (mit Bindestrich); der Importname ist office_oxide (mit Unterstrich).

Ein Dokument lesen

from office_oxide import Document

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

Oder als einfacher Funktionsaufruf:

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

Kern-API

Document.open erkennt das Format an der Dateierweiterung (und prüft per Magic-Bytes nach). Akzeptiert str, bytes oder beliebige os.PathLike. Als Context Manager nutzen, damit nativer Speicher deterministisch freigegeben wird.

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 — semantisches HTML
    ir = doc.to_ir()            # verschachteltes dict (DocumentIR)

    doc.save_as("deck.docx")    # auch altes PPT → PPTX möglich

Wenn die Datei nicht auf der Platte liegt, aus rohen Bytes öffnen:

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

Modul-Shortcuts:

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"

Bearbeiten

EditableDocument bewahrt alle unveränderten OPC-Teile (Bilder, Diagramme, Stile, Beziehungen) beim Speichern unverändert. Nur DOCX, XLSX und PPTX werden unterstützt.

from office_oxide import EditableDocument

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

Text in DOCX / PPTX ersetzen

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 läuft in DOCX über <w:t>-Elemente und in PPTX über <a:t> auf jeder Folie. Liefert die Zahl der Ersetzungen zurück.

XLSX-Zellen schreiben

from office_oxide import EditableDocument

with EditableDocument.open("budget.xlsx") as ed:
    ed.set_cell(0, "A1", "Total")     # Zeichenkette
    ed.set_cell(0, "B1", 42.5)        # Zahl (int geht auch)
    ed.set_cell(0, "C1", True)        # Boolean
    ed.set_cell(0, "D1", None)        # leer
    ed.save("budget.xlsx")

sheet_index ist nullbasiert; cell_ref nutzt die Standard-Tabellenkalkulationsnotation (A1, AA12).

Format-unabhängige IR

doc.to_ir() liefert ein verschachteltes dict, das Rusts DocumentIR widerspiegelt: Abschnitte mit Überschriften, Absätzen, Tabellen, Listen und Bildern. Praktisch für Pipelines und um LLMs strukturierten Kontext zu liefern.

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

Bytes-basierte Pipelines

from_bytes spart Tempdateien in serverlosen und Streaming-Workflows:

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

Altformate

DOC, XLS und PPT laufen über dieselbe API. Über die Endung wird automatisch der Legacy-CFB-Parser gewählt; save_as schreibt transparent ein modernes OOXML:

with Document.open("legacy.doc") as doc:
    print(doc.plain_text())
    doc.save_as("legacy.docx")     # DOC → DOCX in einer Zeile

Fehler

Parse- und IO-Fehler lösen OfficeOxideError aus. IO-Fehler in save_as werden in IOError verpackt.

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 fehlgeschlagen: {e}")
except FileNotFoundError:
    print("Datei nicht gefunden")

Fehlersuche

Symptom Wahrscheinliche Ursache
OfficeOxideError: unsupported format: "" Pfad ohne Erweiterung — Document.from_bytes(data, "docx") verwenden.
RuntimeError: Document is closed Du hast den with-Block verlassen, hältst aber noch eine Referenz. Frisch öffnen.
ImportError: _native Die Wheel passt nicht zur Plattform. pip install --force-reinstall office-oxide.
Legacy-DOC liest Müll Die Datei ist ggf. verschlüsselt (Word 97 RC4). office_oxide entschlüsselt nicht — vorher mit LibreOffice entschlüsseln.
Unicode-Probleme unter Windows pathlib.Path statt Byte-Pfaden verwenden; Document.open regelt die Plattform-Kodierung.

Siehe auch