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.8-cp313-cp313-win_amd64.whl (829.5 kB view details)

Uploaded CPython 3.13Windows x86-64

sheetio-0.3.8-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.8-cp313-cp313-macosx_10_12_x86_64.whl (938.7 kB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

sheetio-0.3.8-cp312-cp312-win_amd64.whl (829.5 kB view details)

Uploaded CPython 3.12Windows x86-64

sheetio-0.3.8-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.8-cp312-cp312-macosx_10_12_x86_64.whl (938.3 kB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

sheetio-0.3.8-cp311-cp311-win_amd64.whl (830.4 kB view details)

Uploaded CPython 3.11Windows x86-64

sheetio-0.3.8-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.8-cp311-cp311-macosx_10_12_x86_64.whl (936.0 kB view details)

Uploaded CPython 3.11macOS 10.12+ x86-64

sheetio-0.3.8-cp310-cp310-win_amd64.whl (830.4 kB view details)

Uploaded CPython 3.10Windows x86-64

sheetio-0.3.8-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.8-cp310-cp310-macosx_10_12_x86_64.whl (936.3 kB view details)

Uploaded CPython 3.10macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: sheetio-0.3.8-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 829.5 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.8-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 272770d5078858e8ed6cb2387e0a67461982023a8a131854a3d18c0dd5d73d00
MD5 0a93353ab284bec7e3ecbaaab8b86820
BLAKE2b-256 a152a0bafa56d64ec822d9b3f262028e4f6dc549eed1fe6efea11fd17d66e99a

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 a09a1d8c0c3a2d41b8d638032eda27b005f5b458e38a5ef82feb93b88b8f004b
MD5 13b4954cb7ac9c1ab475d9b2e3d7cee2
BLAKE2b-256 1c62e51e2f84ee3c5ace30697098919a79968ac7bdd3f7cf01c77e4e6f65a4e7

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 000d9ecdaf1dc9c1683471b30552f05153b3b12a03198cfc2312bfd780212a1c
MD5 d098b43c5f69998923fd1c8e9b8c9d5f
BLAKE2b-256 04c2d9489cd76ea8c91d45841bbc794ef2c4086e475de2c2d821e8c1d5426e91

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.8-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 829.5 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.8-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b0ffe36e279b74fe0c6fd3f5ff7729252e5e6736fcc5053d3c7f380baa2e98d0
MD5 0b3e0790f27f5c001eec22b44b6d51e8
BLAKE2b-256 014158777001a4bff161312f2087b9bb8c5c0fc5acddc99134cbe15dd6ac5c7e

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 5502c33b455777dbafbf9f411717bb7f1dc5b6c4113e2f7b5c870192c4298713
MD5 529f69597ae52efd3d76e8ceb550a7bd
BLAKE2b-256 7a4d74b4d4a385fbe7cbf7e94c728dba38fc3429572b0790dc19838526e4797d

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 19d9b1d6b1354fd6f5d1f5ff248af4d2b911ed56e646f7dda9f1d62ec4254750
MD5 e7ca91fe5ff83621c8d981a0166d40b8
BLAKE2b-256 6faa9d04a86bd3a5ae7e6917335323d7e5737485244a1ebd75275b7683802b2f

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.8-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 830.4 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.8-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 db4e67a8c78790fb1e5792f2df633ebceba21d66f59ca360b0a493e827bc4897
MD5 e8c2cfb64e0038bdbbcea8cbdbf67fb7
BLAKE2b-256 0426e433622b578730d4927494b65ac7a449b1afb776e35b500c14228c823335

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp311-cp311-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp311-cp311-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 68037cf9bf179b10c3ec56b7ec847871fbd8d6ff528271b622add138ca55dfbd
MD5 aab9d9a371684bbf4a885a3a238a49f1
BLAKE2b-256 548a954cf27654e96a4997e6e29a5450b65114827f719b5d6abcdeb8e508b7a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 56e266310aa5638b4460bcd47aec39b93613159435aedd9ca1dc8291fb3ee250
MD5 9e02cdf96f82d4cdd2b9c0b5517c707c
BLAKE2b-256 a5030ca8af2f467acd8ea708f8b531883389b9e8487a39e1620906d608647524

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: sheetio-0.3.8-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 830.4 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.8-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 996501418b316959f801e6acda6a546783e8e1f860d208fbd89b14b1d2b2fed3
MD5 1c707c87e9cf5bcc76fdd9bd0a67b14d
BLAKE2b-256 cf98a4ce3623a69d1c69d2a4f9e142d1134d3ef72349ccb227baee6d317849b8

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp310-cp310-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp310-cp310-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 fe9084181270938ffad4c09f043c7d7b335e0b826ab267ecee80fe9c4488d226
MD5 af2ea3e169a991e24ad3f0b0f603dcd6
BLAKE2b-256 b29d583263b46d50e374d71c0b3d547d914491d5315aa64803900d3092d4dd53

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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.8-cp310-cp310-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sheetio-0.3.8-cp310-cp310-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 5d611ccf72371cb0c81d80927b1aa644fc19f59693f0cf169ec62c7126aeb661
MD5 eee4a46449b6912bd7f8100903a1b600
BLAKE2b-256 20247fd1bd1f3f765df5422bd72a3cacf7134ccb8c21e381bff447435f656206

See more details on using hashes here.

Provenance

The following attestation bundles were made for sheetio-0.3.8-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

0.3.9

12 files

This release

0.3.8 This release

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