Pyexcel IO

0.6.7 · active · verified Fri Apr 10

Pyexcel-io is a Python library providing a unified API to read and write structured data from various file formats (CSV, TSV, and extensions like XLS, XLSX, ODS via plugins) and databases (SQLAlchemy, Django models). It focuses on data processing, not formatting, fonts, or charts. It is actively maintained with frequent minor releases.

Warnings

breaking Pyexcel-io v0.6.0 dropped support for Python 2 and older Python 3 versions (3.3, 3.4, 3.5). Python 3.6+ is now required.
Fix: Upgrade to Python 3.6 or newer, or use pyexcel-io versions lower than 0.6.0 if Python 2 or older Python 3 is necessary.
breaking The plugin interface was completely rewritten in v0.6.0, making plugins developed for older versions (e.g., v0.3.x) incompatible. This also impacts PyInstaller users requiring updated configurations.
Fix: Update existing plugins or develop new ones conforming to the new plugin interface. Review PyInstaller documentation for updated packaging instructions.
gotcha The `chardet` library, previously an implicit dependency for `csvz` and `tsvz` readers, became optional in v0.6.7. If your application relies on these formats, you may need to install `chardet` explicitly.
Fix: If reading `csvz` or `tsvz` formats, explicitly install `chardet`: `pip install chardet`.
gotcha In versions prior to 0.6.7, pathnames containing dots ('.') could cause `file_name` errors when using `get_writer`.
Fix: Upgrade to pyexcel-io v0.6.7 or newer. If upgrading is not possible, avoid dots in filenames or provide a file-like object instead.
gotcha When multiple pyexcel plugins (e.g., `pyexcel-ods` and `pyexcel-odsr`) are installed that support the same file format, `pyexcel-io` might pick one unpredictably. This can lead to unexpected behavior or an error.
Fix: Explicitly specify the desired plugin using the `library` parameter in `get_data` or `save_data` (e.g., `get_data(..., library='pyexcel-odsr')`), or uninstall the unwanted overlapping plugin.
gotcha Pyexcel-io specifically focuses on tabular data; it does not support reading or writing fonts, colors, charts, images, or password-protected Excel files.
Fix: Users needing to preserve such formatting or handle protected files should consider alternative libraries or pre-process/post-process files outside of pyexcel-io.
gotcha While pyexcel-io supports 'streaming' for large files, many underlying plugins for formats like XLS, XLSX, and ODS (e.g., `pyexcel-xls`, `pyexcel-xlsx`, `pyexcel-ods`) still load the entire file into memory due to their zipped XML structure. Only `csv` readers, `pyexcel-xlsxr`, `pyexcel-odsr`, and `pyexcel-htmlr` truly support partial/streaming reads for memory efficiency.
Fix: For optimal memory usage with large files, prefer CSV format or plugins explicitly designed for streaming (e.g., `pyexcel-xlsxr`).

Install

pip install pyexcel-io Install pyexcel-io

Imports

get_data
```
from pyexcel_io import get_data
```
save_data
```
from pyexcel_io import save_data
```

Quickstart

This quickstart demonstrates how to use `pyexcel-io` to write tabular data to a virtual CSV file (using `StringIO`) and then read it back. The core functions `save_data` and `get_data` provide a unified interface for various data sources and formats.

import os
from pyexcel_io import save_data, get_data
from io import StringIO

# --- Writing data to a virtual CSV file (StringIO) ---
data_to_write = [
    ["Name", "Age", "City"],
    ["Alice", 30, "New York"],
    ["Bob", 24, "London"]
]

output_stream = StringIO()
save_data(output_stream, data_to_write, file_type='csv')

# Simulate getting content from the stream
output_stream.seek(0)
csv_content = output_stream.getvalue()
print("Generated CSV content:\n" + csv_content)

# --- Reading data from the virtual CSV file (StringIO) ---
input_stream = StringIO(csv_content)
# get_data returns a dictionary where keys are sheet names (or 'csv' for single file)
dread_data = get_data(input_stream, file_type='csv')

# Access the first (and only) sheet, usually named 'csv'
if 'csv' in dread_data:
    print("\nRead data:")
    for row in dread_data['csv']:
        print(row)
else:
    print("Error: Could not read data from CSV stream.")

# Example with a physical file (uncomment to test locally)
# file_name = "example.csv"
# save_data(file_name, data_to_write)
# data_from_file = get_data(file_name)
# print(f"\nData from {file_name}: {data_from_file[file_name]}")
# os.remove(file_name) # Clean up

view raw JSON →