Typing stubs for xlrd

Warnings

• breaking Since `xlrd` version 2.0.0, the library *no longer supports reading `.xlsx` (Excel 2007 and later) files*. It strictly reads only the older `.xls` (Excel 97-2003 Workbook) format. Attempting to open an `.xlsx` file will result in an `xlrd.biffh.XLRDError: Excel xlsx file; not supported` error.
  Fix: For `.xlsx` files, use the `openpyxl` library instead. If using `pandas.read_excel`, specify `engine='openpyxl'` (e.g., `pd.read_excel('file.xlsx', engine='openpyxl')`) after installing `openpyxl`.
• gotcha `xlrd` has limited functionality and does not support many advanced Excel features. Specifically, it will safely ignore or not extract information about Charts, Macros, Pictures, embedded objects (including worksheets), VBA modules, Comments, Hyperlinks, Autofilters, Advanced Filters, Pivot Tables, Conditional Formatting, Data Validation, and password-protected files. Only the results of formula calculations are extracted, not the formulas themselves.
  Fix: Be aware of these limitations. For operations requiring more comprehensive interaction with Excel features or writing to `.xls` files, consider using `openpyxl` (for `.xlsx` and some `.xls` features) or `xlwt` (for writing `.xls` files).
• gotcha The `types-xlrd` package from `typeshed` requires Python >=3.10 for its stubs. While older versions of the `xlrd` library might have supported earlier Python versions (e.g., Python 2.7+ to 3.6+ for `xlrd < 2.0.0`), using `types-xlrd` implies a modern Python environment. Ensure your runtime Python version meets this requirement, especially if you are using `mypy` or other type checkers.
  Fix: Ensure your project's Python interpreter is version 3.10 or newer if you intend to use `types-xlrd` for type checking.

Install

• pip install types-xlrd xlrd Install stubs and library

Imports

• open_workbook

  import xlrd; xlrd.open_workbook

• Book

  from xlrd.book import Book

• Sheet

  from xlrd.sheet import Sheet

• XLRDError

  from xlrd.biffh import XLRDError

Quickstart

This quickstart demonstrates how to open an Excel `.xls` file, access a specific sheet, read individual cell values, and iterate through all cells in the sheet using `xlrd`. It includes basic error handling for file not found or incorrect file format. Users must provide an existing `.xls` file.

import xlrd
import os

# Create a dummy .xls file for demonstration if it doesn't exist
# In a real scenario, you would open an existing .xls file
xls_file_path = 'example.xls'
if not os.path.exists(xls_file_path):
    # This part requires an actual .xls file or a library to create one (e.g., xlwt)
    # For a runnable example without xlwt, we'll simulate opening.
    # In practice, ensure 'example.xls' is a valid Excel 97-2003 file.
    print(f"Please create a dummy Excel 97-2003 (.xls) file named '{xls_file_path}' with some data.")
    print("For example, put 'Hello' in A1 and 'World' in B1 of Sheet1.")
    # For this quickstart, we'll proceed assuming the file exists
    # and will raise an error if not, which is expected for `xlrd`.

try:
    # Open the workbook (assumes example.xls exists and is an .xls file)
    book: xlrd.Book = xlrd.open_workbook(xls_file_path)

    # Get the first sheet by index
    sheet: xlrd.sheet.Sheet = book.sheet_by_index(0)

    # Read a cell value (e.g., A1, which is (0, 0))
    cell_value: str = sheet.cell_value(0, 0)
    print(f"Value from cell A1: {cell_value}")

    # Iterate through rows and print values
    print("\nAll values in the first sheet:")
    for row_idx in range(sheet.nrows):
        for col_idx in range(sheet.ncols):
            cell = sheet.cell(row_idx, col_idx)
            print(f"({row_idx}, {col_idx}): {cell.value}", end="\t")
        print()

except xlrd.biffh.XLRDError as e:
    print(f"Error opening Excel file: {e}")
    print("Make sure 'example.xls' is a valid Excel 97-2003 (.xls) file.")
except FileNotFoundError:
    print(f"Error: The file '{xls_file_path}' was not found. Please create it.")