{"id":6497,"library":"agate-excel","title":"agate-excel","description":"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.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/wireservice/agate-excel","tags":["excel","data processing","agate","xls","xlsx"],"install":[{"cmd":"pip install agate-excel","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core data analysis library that agate-excel extends.","package":"agate","optional":false},{"reason":"Required for reading .xlsx files.","package":"openpyxl","optional":false},{"reason":"Required for reading .xls files.","package":"xlrd","optional":false},{"reason":"A dependency often used by xlrd for parsing OLE2 files (.xls).","package":"olefile","optional":false}],"imports":[{"note":"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`.","wrong":"from agateexcel import Table","symbol":"agateexcel","correct":"import agate\nimport agateexcel"}],"quickstart":{"code":"import agate\nimport agateexcel\nimport os\n\n# Create a dummy Excel file for demonstration\n# In a real scenario, 'example.xlsx' would already exist.\n\n# Using openpyxl to create a simple .xlsx file\ntry:\n    from openpyxl import Workbook\n    wb = Workbook()\n    ws = wb.active\n    ws['A1'] = 'Header1'\n    ws['B1'] = 'Header2'\n    ws['A2'] = 1\n    ws['B2'] = 'Value1'\n    ws['A3'] = 2\n    ws['B3'] = 'Value2'\n    xlsx_path = 'example.xlsx'\n    wb.save(xlsx_path)\n\n    print(f\"Created temporary Excel file: {xlsx_path}\")\n\n    # Load an XLSX file\n    table_xlsx = agate.Table.from_xlsx(xlsx_path)\n    print(\"\\nData from XLSX:\")\n    table_xlsx.print_table()\n\n    # You can also specify a sheet by name or index\n    # table_xlsx_sheet2 = agate.Table.from_xlsx(xlsx_path, sheet=0)\n\n    # Clean up the dummy file\n    os.remove(xlsx_path)\n    print(f\"Removed temporary Excel file: {xlsx_path}\")\n\nexcept ImportError:\n    print(\"openpyxl not installed. Cannot create dummy .xlsx file.\")\n    print(\"Please install openpyxl (pip install openpyxl) to run the full quickstart example.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n# Note: Reading .xls files requires xlrd, which is not used in this dummy file creation.\n# Example for XLS (assuming 'example.xls' exists):\n# table_xls = agate.Table.from_xls('example.xls')","lang":"python","description":"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`."},"warnings":[{"fix":"To revert to the previous behavior of never recalculating dimensions, explicitly set `reset_dimensions=False` when calling `agate.Table.from_xlsx()`.","message":"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.","severity":"breaking","affected_versions":"0.4.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (check changelog for specific changes)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install agate-excel'.","cause":"The 'agate-excel' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'agate.excel'"},{"fix":"Install the package using pip: 'pip install xlrd'.","cause":"The 'xlrd' package, required for reading older Excel files, is not installed.","error":"ImportError: No module named 'xlrd'"},{"fix":"Import the extension in your script: 'import agateexcel'.","cause":"The 'agate-excel' extension is not imported, so the 'from_xls' method is unavailable.","error":"AttributeError: module 'agate.Table' has no attribute 'from_xls'"},{"fix":"Verify the sheet index or name, ensuring it exists in the file.","cause":"The specified sheet index does not exist in the Excel file.","error":"ValueError: Sheet index 1 is out of range"},{"fix":"Ensure the Excel file path is correct and the file is accessible.","cause":"Attempting to call a method on a 'None' object, possibly due to a failed file read operation.","error":"TypeError: 'NoneType' object is not callable"}]}