agate-excel

0.4.2 · active · verified Wed Apr 15

agate-excel is an extension for the `agate` data analysis library, providing read support for both older XLS and newer XLSX Excel file formats. The current version is 0.4.2, released on December 15, 2025, and it appears to be actively maintained, supporting recent Python versions including 3.13 and 3.14. It integrates seamlessly with `agate` by adding file reading methods directly to `agate.Table` instances.

Common errors

```
ModuleNotFoundError: No module named 'agate.excel'
```
cause The 'agate-excel' package is not installed in the Python environment.

fix Install the package using pip: 'pip install agate-excel'.
```
ImportError: No module named 'xlrd'
```
cause The 'xlrd' package, required for reading older Excel files, is not installed.

fix Install the package using pip: 'pip install xlrd'.
```
AttributeError: module 'agate.Table' has no attribute 'from_xls'
```
cause The 'agate-excel' extension is not imported, so the 'from_xls' method is unavailable.

fix Import the extension in your script: 'import agateexcel'.
```
ValueError: Sheet index 1 is out of range
```
cause The specified sheet index does not exist in the Excel file.

fix Verify the sheet index or name, ensuring it exists in the file.
```
TypeError: 'NoneType' object is not callable
```
cause Attempting to call a method on a 'None' object, possibly due to a failed file read operation.

fix Ensure the Excel file path is correct and the file is accessible.

Warnings

breaking The default behavior of the `reset_dimensions` argument in `Table.from_xlsx()` changed in version 0.4.0 from `False` to `None`. If `reset_dimensions` is `None` and the worksheet's dimensions are reported as `A1:A1` in the file, `agate-excel` will now recalculate the actual dimensions. This can alter how tables with incorrectly reported dimensions are parsed.
Fix: To revert to the previous behavior of never recalculating dimensions, explicitly set `reset_dimensions=False` when calling `agate.Table.from_xlsx()`.
gotcha agate-excel extends `agate.Table` using a monkey-patching pattern. This means that simply importing `agateexcel` globally modifies the behavior of all `agate.Table` instances within your application. Be aware of this global modification, especially in larger projects or when managing dependencies carefully.
Fix: No direct fix, but be mindful of the side effects of importing `agateexcel`. Ensure it's imported in a scope where this global modification is acceptable.
gotcha Python version compatibility can change between major releases. For instance, version 0.3.0 dropped support for Python 3.5, 3.6, and 3.7. The latest version 0.4.2 explicitly adds support for Python 3.13 and 3.14.
Fix: Always check the official documentation or changelog for the specific version of `agate-excel` you are using to ensure compatibility with your Python environment. Upgrade `agate-excel` and its dependencies (like `openpyxl` and `xlrd`) together.

Install

pip install agate-excel Install stable version

Imports

agateexcel
wrong:
```
from agateexcel import Table
```
correct:
```
import agate
import agateexcel
```
agate-excel monkey-patches `agate.Table` directly; its functionality is accessed via `agate.Table.from_xls()` or `agate.Table.from_xlsx()` after importing both `agate` and `agateexcel`.

Quickstart

This quickstart demonstrates how to read data from an XLSX file using `agate-excel`. It first creates a simple XLSX file using `openpyxl` (if available) and then loads it into an `agate.Table` object. The methods `from_xls()` and `from_xlsx()` are added directly to `agate.Table` after `import agateexcel`.

import agate
import agateexcel
import os

# Create a dummy Excel file for demonstration
# In a real scenario, 'example.xlsx' would already exist.

# Using openpyxl to create a simple .xlsx file
try:
    from openpyxl import Workbook
    wb = Workbook()
    ws = wb.active
    ws['A1'] = 'Header1'
    ws['B1'] = 'Header2'
    ws['A2'] = 1
    ws['B2'] = 'Value1'
    ws['A3'] = 2
    ws['B3'] = 'Value2'
    xlsx_path = 'example.xlsx'
    wb.save(xlsx_path)

    print(f"Created temporary Excel file: {xlsx_path}")

    # Load an XLSX file
    table_xlsx = agate.Table.from_xlsx(xlsx_path)
    print("\nData from XLSX:")
    table_xlsx.print_table()

    # You can also specify a sheet by name or index
    # table_xlsx_sheet2 = agate.Table.from_xlsx(xlsx_path, sheet=0)

    # Clean up the dummy file
    os.remove(xlsx_path)
    print(f"Removed temporary Excel file: {xlsx_path}")

except ImportError:
    print("openpyxl not installed. Cannot create dummy .xlsx file.")
    print("Please install openpyxl (pip install openpyxl) to run the full quickstart example.")
except Exception as e:
    print(f"An error occurred: {e}")

# Note: Reading .xls files requires xlrd, which is not used in this dummy file creation.
# Example for XLS (assuming 'example.xls' exists):
# table_xls = agate.Table.from_xls('example.xls')

view raw JSON →