Skip to main content

sheetio -- Fast Rust-Powered Excel Form Data Extraction

PyPI version CI Python 3.10+ License: MIT

Extract structured data from Excel forms (.xlsx, .xlsm) into JSON. Built in Rust with Python bindings via PyO3 for fast parallel processing of hundreds of files. Designed for standardized Excel forms that don't fit the typical CSV format -- government reports, engineering forms, financial templates, and survey spreadsheets.

Why sheetio?

  • Fast -- Rust core with async parallel file processing. Process hundreds of Excel forms in seconds.
  • Flexible -- Three extraction modes (single cells, row patterns, dataframes) handle any form layout.
  • Simple -- One function, JSON config, JSON output. No complex API to learn.
  • Robust -- Handles missing data, duplicate keys, wildcard sheet matching, and composite identifiers.

Quick Start

pip install sheetio
import sheetio
import json

files = ["form_001.xlsx", "form_002.xlsx", "form_003.xlsx"]

config = [
    {
        "sheets": ["Sheet1"],
        "extractions": [
            {
                "function": "single_cells",
                "label": "header",
                "instructions": {
                    "title": "b2",
                    "date": "d4",
                    "author": "b6"
                }
            },
            {
                "function": "multirow_patterns",
                "label": "items",
                "instructions": {
                    "row_range": [10, 100],
                    "unique_id": "A",
                    "stop_if_empty": "A",
                    "columns": {
                        "ID": "A",
                        "Description": "B",
                        "Value": "C"
                    }
                }
            }
        ]
    }
]

result = json.loads(sheetio.excel_extract(files, config, 5))

Config Builder

Use ExtractionConfig to build configs iteratively with method chaining, instead of writing raw dicts:

from sheetio import ExtractionConfig

config = ExtractionConfig()

# Add extractions with a fluent API
config.add_sheets(["Sheet1"]) \
    .single_cells("header", title="B2", date="D4", author="B6") \
    .multirow("items",
        row_range=(10, 100),
        unique_id="A",
        stop_if_empty="A",
        columns={"ID": "A", "Description": "B", "Value": "C"})

# Extract directly — returns parsed Python dicts (no json.loads needed)
result = config.extract(["form_001.xlsx", "form_002.xlsx"], workers=5)

# Save / load configs as JSON files
config.to_json("my_config.json")
config = ExtractionConfig.from_json("my_config.json")

# Inspect what you've built
config.summary()

# Or get the raw config list for manual use
raw = config.build()

All three extraction types are supported: .single_cells(), .multirow(), .dataframe(). See the Extraction Types Reference below for all available options.

Key Features

Feature Description
Parallel processing Process multiple files simultaneously with configurable worker count
Wildcard sheets Match sheets by pattern: "School_*" matches School_A, School_B, etc.
Composite keys Combine multiple columns as unique identifiers: ["Project", "Year"]
Gap tolerance Continue extraction through empty rows with stop_consecutive
Duplicate handling Automatic _1, _2 suffixes for duplicate keys
Multi-column merge Extract arrays from multiple columns per field: ["X", "Y", "Z"]
Multi-row headers Concatenate header rows for dataframe extraction

Requirements

  • Python 3.10 or higher
  • Supported platforms: Windows, macOS, Linux

Extraction Types Reference

Configuration Structure

The extraction_details parameter is a list of dictionaries that define the extraction rules for each Excel sheet. Each dictionary contains:

  • sheets: A list of sheet names to extract data from. Accepts patterns with *. Example: "School_*" will loop through sheets like School_A, School_B, etc.
  • skip_sheets: An optional list of sheet names to skip. Can be useful when using patterns in the list of sheets.
  • extractions: A list of extraction rules that will be applied to the sheets listed.

Each extraction rule contains:

  • function: Type of extraction function: single_cells, multirow_patterns, or dataframe.
  • label: Optional key string to store results under. If not specified the extracted key value pairs will be stored directly under the sheet name.
  • break_if_null: An optional check to skip sheet if specified cell is null.
  • instructions: Instructions for the extraction function. See details for each function type below.

Single Cells Extraction

Extracts individual cells from the Excel sheet.

Instructions:

  • instructions: A dictionary where the keys are the reference name and the values are the cell references (e.g., "a1", "b2").

Example:

{
    "sheets": ["Sheet1"],
    "extractions": [
        {
            "function": "single_cells",
            "label": "single",
            "break_if_null": "c3",
            "instructions": {
                "Value 1": "a1",
                "Value 2": "b2",
                "Value 3": "c3",
                "Date": "d4",
                "Datetime": "e5"
            }
        }
    ]
}

Multirow Patterns Extraction

Extracts data from multiple rows based on a pattern.

Instructions:

  • row_range: A list of two integers defining the row range to extract.
  • unique_id (optional): The column(s) to use as a unique identifier. Can be either:
    • A single column as a string: "B"
    • Multiple columns as an array: ["B", "C"] for composite keys
    • When using composite keys, if ANY column contains null/empty values, the row is skipped
    • If omitted: Results are returned as an array/list instead of a dictionary
  • unique_id_separator (optional): The separator to use when joining multiple columns for composite keys. Defaults to "_".
  • columns: A dictionary where the keys are the column names and the values are the column letters (e.g., "B", "C").
  • stop_if_empty (optional): Controls when to stop processing rows. Can be:
    • A column string: "A" - Stop when this column is empty
    • An array of columns: ["A", "B"] - Stop when ALL specified columns are empty
    • The string "row" - Stop when the entire data row is empty
    • An object with detailed configuration:
      {"column": "A", "consecutive": 2}
      
      or
      {"mode": "row", "consecutive": 1}
      
  • stop_consecutive (optional): Used with simple stop_if_empty syntax to specify how many consecutive empty rows trigger a stop. Defaults to 1.

Example with single unique_id:

{
    "sheets": ["Sheet 1", "Sheet 2"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "deposits",
            "instructions": {
                "row_range": [1, 10],
                "unique_id": "B",
                "columns": {
                    "Title": "B",
                    "Description": "C",
                    "Estimate": "D",
                    "Chance": "E",
                }
            }
        }
    ]
}

Example with composite unique_id:

{
    "sheets": ["Sheet 1"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "projects",
            "instructions": {
                "row_range": [1, 50],
                "unique_id": ["B", "C"],
                "unique_id_separator": "-",
                "columns": {
                    "Project": "B",
                    "Year": "C",
                    "Budget": "D",
                    "Status": "E"
                }
            }
        }
    ]
}

Example without unique_id (returns array/list):

{
    "sheets": ["Sheet 1"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "items",
            "instructions": {
                "row_range": [1, 1000],
                "stop_if_empty": "A",
                "columns": {
                    "Name": "A",
                    "Value": "B",
                    "Description": "C"
                }
            }
        }
    ]
}
# Returns: {"items": [{"Name": "...", "Value": ...}, {"Name": "...", "Value": ...}]}

Example with stop_if_empty and gap tolerance:

{
    "sheets": ["Sheet 1"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "data",
            "instructions": {
                "row_range": [1, 100],
                "stop_if_empty": "A",
                "stop_consecutive": 3,
                "columns": {
                    "ID": "A",
                    "Value": "B"
                }
            }
        }
    ]
}

Example with row-based empty detection:

{
    "sheets": ["Sheet 1"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "records",
            "instructions": {
                "row_range": [1, 500],
                "stop_if_empty": {
                    "mode": "row",
                    "consecutive": 2
                },
                "columns": {
                    "Field1": "A",
                    "Field2": "B",
                    "Field3": "C"
                }
            }
        }
    ]
}

Example with multiple column monitoring:

{
    "sheets": ["Sheet 1"],
    "extractions": [
        {
            "function": "multirow_patterns",
            "label": "transactions",
            "instructions": {
                "row_range": [1, 1000],
                "unique_id": "A",
                "stop_if_empty": ["A", "B"],
                "columns": {
                    "ID": "A",
                    "Date": "B",
                    "Amount": "C"
                }
            }
        }
    ]
}

Dataframe Extraction

Extracts tabular data with headers, returning JSON that can easily be converted to a Pandas DataFrame.

Instructions:

  • row_range: A list of two integers defining the row range to extract.
  • column_range: A list of column letters to extract.
  • header_row: A list of row numbers to use as the header.
  • separator: Optional separator to use when combining header cells (default " ").

Example:

{
    "sheets": ["School_*"],
    "extractions": [
        {
            "function": "dataframe",
            "label": "DataFrame",
            "instructions": {
                "row_range": [5, 15],
                "column_range": ["B", "F"],
                "header_row": [2, 3, 4],
                "separator": " ",
            }
        }
    ]
}

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

# Development setup
pip install maturin pytest openpyxl ruff
maturin develop --release
make lint   # check formatting
make test   # run tests

License

sheetio is released under the MIT License. See the LICENSE file for more details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

sheetio-0.3.9-cp313-cp313-win_amd64.whl (828.2 kB view details)

Uploaded CPython 3.13Windows x86-64

sheetio-0.3.9-cp313-cp313-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.34+ x86-64

sheetio-0.3.9-cp313-cp313-macosx_10_12_x86_64.whl (936.2 kB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

sheetio-0.3.9-cp312-cp312-win_amd64.whl (828.1 kB view details)

Uploaded CPython 3.12Windows x86-64

sheetio-0.3.9-cp312-cp312-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.34+ x86-64

sheetio-0.3.9-cp312-cp312-macosx_10_12_x86_64.whl (936.0 kB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

sheetio-0.3.9-cp311-cp311-win_amd64.whl (830.2 kB view details)

Uploaded CPython 3.11Windows x86-64

sheetio-0.3.9-cp311-cp311-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.34+ x86-64

sheetio-0.3.9-cp311-cp311-macosx_10_12_x86_64.whl (939.5 kB view details)

Uploaded CPython 3.11macOS 10.12+ x86-64

sheetio-0.3.9-cp310-cp310-win_amd64.whl (830.2 kB view details)

Uploaded CPython 3.10Windows x86-64

sheetio-0.3.9-cp310-cp310-manylinux_2_34_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.34+ x86-64

sheetio-0.3.9-cp310-cp310-macosx_10_12_x86_64.whl (939.6 kB view details)

Uploaded CPython 3.10macOS 10.12+ x86-64

File details

Details for the file sheetio-0.3.9-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.9-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 828.2 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sheetio-0.3.9-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c5e9646eb94deb79e676cd1fc37234cfc95a9abc0925453812125e2cee404fb8
MD5 dee375ebdb2996c41b2a5d060d06bdeb
BLAKE2b-256 32caa21488e4ceeb973306122bf505c0b333ec68b8cdb4d0753774261b3fa12b

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp313-cp313-win_amd64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 7dfffaa077e195d53717d73742ee0de64c1d55ae11d5f41a822eacd60012d793
MD5 d3727161af7fabf6c05c34c4199ae94f
BLAKE2b-256 345466e0159c74cfdb54ada77de3ce022bd2ed5e42d4bda57fafea7f6fa586eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp313-cp313-manylinux_2_34_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a26fe44df050eb3fd72f6f3257ea0f3d3e6a49df82a7d0c3ec055c1d6b820ca5
MD5 f515626fbf6b5f111aac487cf278d617
BLAKE2b-256 e5b47fd7558bf4de02300ba2c013ddaee671bc5586e8cc339d1b5ffcef294170

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp313-cp313-macosx_10_12_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.9-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 828.1 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sheetio-0.3.9-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b9d5e58cc27a769ea99260ab1b588e271b761dbc02378a3fabf955df57055d4e
MD5 13f40d7bdf5cb70fae0acd11ab08d0fe
BLAKE2b-256 070adaa5aaa1b265732205dfd4daa6b0be3cd66d44c57f4aa1d0f513be5f563c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp312-cp312-win_amd64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 f08441a4505bb2062b79ac6d42fd3a363e3e6f32fec9baec52d80cc7c76b20b1
MD5 fd3c3d5bc1eb903b9d837e4efc2eebe9
BLAKE2b-256 078cad5bbfb2e931c457a5a09c1a4ce882f3fb6ba0b3425729df5b3c01547299

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp312-cp312-manylinux_2_34_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 d3dc5b91f04e855be0e106668ae88ccca62d4b233d0b41a5e1d1ea2f7ece8424
MD5 ffe5b51f706f22e0b0cb9c6070197f70
BLAKE2b-256 282bf8efecc4d0e7aee039b011478e7b646b6fd3ba35aa158b79cc703f7991e7

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp312-cp312-macosx_10_12_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.9-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 830.2 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sheetio-0.3.9-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 0f54ddb11abf59173249bb877e308e32587dccb3833d32b75e07ff2dad82e73a
MD5 b0b8c12fa1ad75d4874fd8b5a86ca198
BLAKE2b-256 ae6a3c4f106344debec7bd341b98342c799b20c3181dacfc007d349881ea4841

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp311-cp311-win_amd64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp311-cp311-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 342279cc66fecc95bf7ccff3e9a6f518040b65cc24b78be1ed23ff32fa339213
MD5 46d93c4eb59f1325d67a7299418c7417
BLAKE2b-256 56792e05bac97e4993782654313f9df050cf8a2077f3ea686a716981223a0792

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp311-cp311-manylinux_2_34_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e5349b04f8c92e9bd6e17c6b56e9c7bd66409417a6b3b3144a43b5fd971e3ff9
MD5 edb4a74c5e8be1aa03a0599a9d3a3c31
BLAKE2b-256 9168ec35540be0bd3f8f5f61940cfea6999cbfe08bf3e781a46fc6b325770a82

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp311-cp311-macosx_10_12_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.9-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 830.2 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sheetio-0.3.9-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 a293d5896d1412e9cc9a665cbba1b64f15f2b226de0bde5b9dd682f92e79a02d
MD5 ce444b666bb7e477b5536214d8362068
BLAKE2b-256 ec047577b7765b9718a4e9293299d08f5580c4c80fcab792e19e7b333ceb1ac2

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp310-cp310-win_amd64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp310-cp310-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 79d8916e3bb4931b54e15aac26befad29da93b35d855845b344ed13d9c34630e
MD5 108d532e8a9c6e831221fcb5873c4a81
BLAKE2b-256 c8ef1ecc80dfffa01b41f73da51e2a5d286777bac9d71d90e6dc82b504e6676c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp310-cp310-manylinux_2_34_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sheetio-0.3.9-cp310-cp310-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.9-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 99aa8456efe1163607ed50c00a87043c79cbb8137761d9ce926796abb34090d7
MD5 1bd618c3e066ab6fa21b6dbb4244c498
BLAKE2b-256 201a077fefdd170af41f0464e99b9f5b0b6b795d571fa129e601cb24e95355b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.9-cp310-cp310-macosx_10_12_x86_64.whl:

Publisher: build_wheels.yml on kkollsga/sheetio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.9 This release

12 files

0.3.8

12 files

0.3.7

12 files

0.3.6

12 files

0.3.5

12 files

0.3.4

12 files

0.3.3

12 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page