calamine

 
 

Библиотека на чистом Rust для электронных таблиц

Чтение XLS, XLSX, XLSM, XLSB, ODS и других форматов с нулевой копией десериализации в Rust.

Что такое calamine?

calamine — это высокопроизводительная, чистая библиотека на Rust для чтения и десериализации файлов электронных таблиц Excel и OpenDocument. Она поддерживает форматы, такие как XLS, XLSX, XLSM, XLSB, ODS и другие, делая акцент на быстрой, безопасной и нулевой копии извлечения данных. Разработана для надёжности и минимальных зависимостей, calamine избегает внешних системных библиотек и полностью полагается на реализации на чистом Rust. Её API позволяет разработчикам эффективно извлекать значения ячеек, работать с проектами VBA и разбирать формулы без сложной настройки или накладных расходов во время выполнения.

Библиотека превосходит в приложениях, критичных к производительности, предлагая значительно более быструю обработку по сравнению с альтернативами на Python, C# и Go. Благодаря встроенной интеграции с Serde, calamine обеспечивает бесшовное сопоставление данных таблиц со структурами Rust. Она поддерживает ленивую загрузку больших файлов, настройку строки заголовка и дополнительные функции, такие как поддержка даты/времени через chrono и извлечение данных изображений. Независимо от того, создаёте ли вы CLI‑инструменты, веб‑бэкенды или встроенные системы, calamine обеспечивает надёжную, предсказуемую производительность на всех платформах.

Previous Next

Начало работы с calamine

Чтобы начать использовать calamine, добавьте её в ваш Rust‑проект через Cargo. Вы можете установить её напрямую, используя cargo add calamine, или вручную добавить зависимость в ваш Cargo.toml. Библиотека доступна на crates.io, а её исходный код размещён на calamine GitHub. Для расширенного использования включите необязательные функции, такие как chrono для поддержки даты/времени или picture для извлечения данных изображений. Библиотека компилируется без проблем на стабильном Rust и не требует внешних бинарных файлов или системных библиотек.

Установите calamine через Cargo

cargo add calamine

Десериализация таблиц на основе Serde

calamine предоставляет мощную интеграцию с Serde для сопоставления данных таблиц напрямую с Rust‑структурами. С помощью RangeDeserializerBuilder разработчики могут определять строго типизированные модели данных и автоматически десериализовать строки в структурированные записи. Библиотека включает вспомогательные функции, такие как deserialize_as_f64_or_none и deserialize_as_f64_or_string, для корректной обработки столбцов смешанных типов. Такой подход обеспечивает типовую безопасность, уменьшает количество шаблонного кода и позволяет выполнять проверку структуры данных во время компиляции. Он особенно полезен для конвейеров данных, инструментов отчетности и ETL‑приложений, где критичны надежность и производительность.

Десериализуйте строки таблицы в структуры Rust

use calamine::{deserialize_as_f64_or_none, open_workbook, RangeDeserializerBuilder, Reader, Xlsx};
use serde::Deserialize;

#[derive(Deserialize)]
struct Record {
    metric: String,
    #[serde(deserialize_with = "deserialize_as_f64_or_none")]
    value: Option,
}

let mut excel: Xlsx<_> = open_workbook("file.xlsx")?;
let range = excel.worksheet_range("Sheet1")?;
let iter = RangeDeserializerBuilder::with_headers(&["metric", "value"]).from_range(&range)?;
for result in iter {
    let record: Record = result?;
    println!("{:?}", record);
}

Извлечение проекта VBA и формул

calamine позволяет извлекать модули проекта VBA и определения формул из файлов Excel. Разработчики могут получать VBA‑код из модулей, обнаруживать сломанные ссылки и просматривать определённые имена и их формулы. Эта возможность важна для инструментов миграции, аудита и анализа устаревших систем. API предоставляет структурированный доступ к метаданным VBA и поддерживает как простые, так и сложные сценарии интроспекции книг. Независимо от того, анализируете ли вы макросы с точки зрения безопасности или конвертируете устаревшую логику Excel, calamine обеспечивает точный низкоуровневый доступ к скрытому содержимому книги.

Извлечение VBA-кода и определённых имён

use calamine::{open_workbook_auto, Reader};

let mut workbook = open_workbook_auto("file.xlsx")?;
if let Ok(Some(vba)) = workbook.vba_project() {
    let module = vba.get_module("Module1").unwrap();
    println!("{}", module);
    for ref in vba.get_references() {
        if ref.is_missing() { println!("Broken: {}", ref.name); }
    }
}
for (name, formula) in workbook.defined_names() {
    println!("{}: {}", name, formula);
}

Ленивая загрузка и работа с большими файлами

calamine поддерживает ленивую загрузку файлов XLSX и XLSB, позволяя эффективно обрабатывать большие таблицы без загрузки всех листов в память одновременно. Настраивая строки заголовков и используя итерацию по диапазонам, разработчики могут минимизировать потребление памяти и максимизировать пропускную способность. Эта функция особенно ценна для безсерверных функций, CLI‑инструментов и встраиваемых развертываний, где ресурсы ограничены. Тесты показывают, что calamine читает более 1 млн строк с минимальными затратами памяти по сравнению с альтернативами, такими как openpyxl и ClosedXML, что делает её идеальной для высокомасштабных конвейеров ingest‑а данных.

Эффективная обработка больших электронных таблиц

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

let mut excel: Xlsx<_> = open_workbook("large.xlsx")?;
let range = excel
    .worksheet_range("Sheet1")?
    .expect("Sheet not found");

for row in range.rows() {
    // Process row without loading entire file
    process_row(row);
}

Оптимизация производительности и тесты

calamine обеспечивает исключительную производительность, обрабатывая 41 млн ячеек менее чем за 25 секунд — превзойдя библиотеки Python, C# и Go до 9,4‑кратного ускорения. Его дизайн без копирования и минимальные аллокации кучи существенно снижают нагрузку на CPU и использование памяти. Тесты на файле XLSX размером 186 МБ показывают, что calamine читает только 186 МБ с диска, в то время как excelize использует 1,5 ГБ. Детерминированное поведение памяти библиотеки и низкое давление на сборщик мусора делают её подходящей для приложений в реальном времени и с чувствительностью к задержкам. Разработчики получают предсказуемое использование ресурсов и стабильную пропускную способность при разнообразных нагрузках.

 Русский