Skip to content
Office Oxide

Migration von python-calamine (und calamine)

calamine ist der renommierte Rust-Reader für XLSX/XLS; python-calamine ist sein Python-Binding. Beide fokussieren sich ausschließlich auf Spreadsheets.

Office Oxide ist 2,8× schneller als python-calamine bei XLSX (5,0 ms gegenüber 13,9 ms Mittelwert über 1 802 Dateien), mit der höchsten Erfolgsquote (97,8 % gegenüber 96,6 %). Zusätzlich bringt es volle DOCX-, PPTX- und Legacy-DOC/PPT-Unterstützung — Formate, die calamine gar nicht liest.

Wann migrieren

Wechseln Sie, wenn eines davon zutrifft:

  • Sie brauchen auch .docx / .pptx / .doc / .ppt (calamine ist nur XLSX/XLS)
  • Sie wollen einen breiteren Funktionsumfang: Markdown-/HTML-Ausgabe, strukturiertes IR, Templating via EditableDocument
  • Erfolgsquote ist wichtiger als calamines marginaler Performance-Vorteil in manchen Szenarien
  • Sie sind auf dem Python-Binding und wollen weniger Cross-FFI-Konversionen

Bleiben Sie bei calamine, wenn:

  • Sie ausschließlich .xlsx und .xls lesen
  • Sie auf calamine-spezifische APIs angewiesen sind (Reader::with_header_row, worksheet_range_at etc.)
  • Sie Formel-Ausdrücke brauchen (calamine legt sie offen; das Office-Oxide-IR nicht)

Installation (Python)

pip uninstall python-calamine
pip install office-oxide

Installation (Rust)

# Cargo.toml
[dependencies]
# Ersetzen:
#   calamine = "0.30"
office_oxide = "0.1.0"

Spickzettel im Direktvergleich — Python

Arbeitsmappe öffnen

python-calamine

from python_calamine import CalamineWorkbook

wb = CalamineWorkbook.from_path("budget.xlsx")

office_oxide

from office_oxide import Document

with Document.open("budget.xlsx") as doc:
    ...

Über Blätter iterieren

python-calamine

for name in wb.sheet_names:
    sheet = wb.get_sheet_by_name(name)
    for row in sheet.to_python():
        print(row)

office_oxide

with Document.open("budget.xlsx") as doc:
    ir = doc.to_ir()

for section in ir["sections"]:
    print(f"# {section.get('title')}")
    for el in section["elements"]:
        if el["kind"] == "Table":
            for row in el["rows"]:
                print(row)

Ein einzelnes Blatt als Zeilen lesen

python-calamine

sheet = wb.get_sheet_by_name("Q4")
rows = sheet.to_python()

office_oxide

with Document.open("budget.xlsx") as doc:
    table = next(
        el for section in doc.to_ir()["sections"]
        if section.get("title") == "Q4"
        for el in section["elements"] if el["kind"] == "Table"
    )
    rows = table["rows"]

Direkter:

with Document.open("budget.xlsx") as doc:
    sheet = doc.as_xlsx().sheet("Q4")
    rows = sheet.rows()    # list[list[str]]

Blattnamen

python-calamine

print(wb.sheet_names)

office_oxide

with Document.open("budget.xlsx") as doc:
    print([s.name() for s in doc.as_xlsx().sheets()])

Spickzettel im Direktvergleich — Rust

Öffnen und iterieren

calamine

use calamine::{open_workbook, Xlsx, Reader};

let mut wb: Xlsx<_> = open_workbook("budget.xlsx")?;
for sheet_name in wb.sheet_names() {
    if let Ok(range) = wb.worksheet_range(&sheet_name) {
        for row in range.rows() {
            println!("{row:?}");
        }
    }
}

office_oxide

use office_oxide::Document;

let doc = Document::open("budget.xlsx")?;
if let Some(xlsx) = doc.as_xlsx() {
    for sheet in xlsx.sheets() {
        for cell in sheet.cells() {
            println!("{}: {:?}", cell.address(), cell.value());
        }
    }
}

Formatunabhängiges IR (kein calamine-Äquivalent)

let doc = Document::open("budget.xlsx")?;
let ir = doc.to_ir();
serde_json::to_writer(std::io::stdout(), &ir)?;

Die Ausgabe hat die gleiche Form wie aus .docx oder .pptx — nützlich, wenn Downstream-Konsumenten sich nicht für das Quellformat interessieren sollen.

XLSX-Schreibvorgänge

calamine ist nur lesend. Office Oxide schreibt XLSX-Zellen über EditableDocument:

from office_oxide import EditableDocument

with EditableDocument.open("budget.xlsx") as ed:
    ed.set_cell(0, "B5", 42_000)
    ed.save("budget.xlsx")

Für vollständige XLSX-Konstruktion steigen Sie in xlsx::create::XlsxBuilder ab oder nutzen umya-spreadsheet / rust_xlsxwriter.

Performance

Bibliothek XLSX Mittel p99 Erfolgsquote
office_oxide 5,0 ms 40 ms 97,8 %
python-calamine 13,9 ms 183 ms 96,6 %
openpyxl 94,5 ms 698 ms 96,2 %
Bibliothek XLS Mittel p99 Erfolgsquote
office_oxide 2,8 ms 75 ms 99,2 %
python-calamine 9,0 ms 96 ms 90,7 %

Was unterschiedlich ist

calamine liefert pro Zelle ein typisiertes Data-Enum (Int, Float, String, Bool, DateTime, Empty, Error). Das IR von Office Oxide kollabiert auf Strings; für typisierten Zellzugriff nutzen Sie den formatspezifischen Accessor:

with Document.open("budget.xlsx") as doc:
    for sheet in doc.as_xlsx().sheets():
        for cell in sheet.cells():
            print(cell.value(), cell.value_type())   # value_type: "string" | "number" | "boolean" | "empty"

Siehe auch