API Reference

A fast library for reading and writing XLSX files.

class fastxlsx.DType

Enumeration for data types.

Any = DType.Any

Bool = DType.Bool

Date = DType.Date

DateTime = DType.DateTime

Float = DType.Float

Int = DType.Int

Str = DType.Str

class fastxlsx.DShape

Class to describe the shape of data.

Column: alias of DShape_Column

Matrix: alias of DShape_Matrix

Row: alias of DShape_Row

Scalar: alias of DShape_Scalar

class fastxlsx.RangeInfo(pos, data_shape=Ellipsis, *, dtype=Ellipsis, strict=True)

Class to describe the range of data.

data_shape

dtype

end: The 0-based ending position of the range as (row, col)

pos

shape: The shape of the range as (n_rows, n_cols)

start: The 0-based starting position of the range as (row, col)

strict

class fastxlsx.ReadOnlyWorkbook(path)

Read-only workbook class

get(idx_or_name)

Get the sheet by index or name.

Parameters:: idx_or_name (Union[int, str]) – The 0-based index or name of the sheet.
Return type:: ReadOnlyWorksheet

get_by_idx(idx)

Get the sheet by index.

Parameters:: idx (int) – The 0-based index of the sheet.
Return type:: ReadOnlyWorksheet

get_by_name(sheet_name)

Get the sheet by sheet name.

Parameters:: name (str) – The name of the sheet.
Return type:: ReadOnlyWorksheet

n_sheets

path

read_worksheets(worksheets_to_read)

Read values from multiple worksheets based on specified ranges.

Parameters:: worksheets_to_read (Dict[Union[str, int], Union[List[RangeInfo], Dict[str, RangeInfo]]]) – A dictionary mapping worksheet identifiers (either by name or index) to a list or dict of RangeInfo objects. Each RangeInfo object describes a range of cells to read from the corresponding worksheet.
Returns:: A dictionary mapping worksheet identifiers (either by name or index) to a list or dict of values read from the specified ranges, where each range is replaced by the corresponding data.
Return type:: Dict[Union[str, int], Union[List[Any], Dict[str, Any]]]

Examples

>>> from fastxlsx import WorkbookReanonly, RangeInfo, DShape, DType
>>> wb = WorkbookReanonly("example.xlsx")
>>> worksheets_to_read = {
        "Sheet1": [
            RangeInfo((0, 0), DShape.Matrix(2, 2), dtype=DType.Int),
            RangeInfo((2, 0), DShape.Column(3), dtype=DType.Str),
        ],
        1: [RangeInfo((0, 0), DShape.Row(5), dtype=DType.Float)],
    }
>>> res = wb.read_worksheets(worksheets_to_read)
>>> res
{
    "Sheet1": [np.array([[1, 2], [3, 4]]), ["A", "B", "C"]],
    1: [np.array([1.1, 2.2, 3.3, 4.4, 5.5])],
}

sheetnames

worksheets: The sheets.

class fastxlsx.ReadOnlyWorksheet

Read-only worksheet class

cell_value(cell_addr, *, dtype=Ellipsis, strict=True)

Read a value from a specific cell in the worksheet.

Parameters:

cell_addr (Union[Tuple[int, int], str]) – The cell address, either as a tuple of (row, col) or a string (e.g., “A1”).
dtype (DType, default DType.Any) – The expected data type of the cell value. If use DType.Any, will determine automatically.
strict (bool, default True) – Whether to enforce strict type checking. If True, raise error when the dtype does not match, else use default value.

Returns:

The value read from the specified cell as the specified dtype.

Return type:

Any

n_cols

n_rows

read_value(range_info)

Read a single value from the worksheet based on the specified range.

Parameters:: range_info (RangeInfo) – The range information describing the position, shape, and data type of the value to read.
Returns:: The value read from the specified range. Could be scalar or 1d-array or 2d-array.
Return type:: Any

read_values(range_infos)

Read multiple values from the worksheet based on a list of ranges.

Parameters:: range_info_list (List[RangeInfo] | Dict[str, RangeInfo]) – A list or dict of RangeInfo objects, each describing a range of cells to read.
Returns:: A list or dict of values read from the specified ranges.
Return type:: List[Any] | Dict[str, Any]

title

class fastxlsx.WriteOnlyWorkbook

Write-only workbook class

create_sheet(title)

Create a new worksheet with the specified name.

Parameters:: name (str) – The name of the new worksheet.
Returns:: The newly created worksheet.
Return type:: WriteOnlyWorksheet

get(idx_or_title)

Get a worksheet by its index or name.

Parameters:: idx_or_name (Union[int, str]) – The 0-based index or name of the worksheet.
Returns:: The worksheet at the specified index or with the specified name.
Return type:: WriteOnlyWorksheet

get_by_idx(idx)

Get a worksheet by its index.

Parameters:: idx (int) – The 0-based index of the worksheet.
Returns:: The worksheet at the specified index.
Return type:: WriteOnlyWorksheet

get_by_name(name)

Get a worksheet by its name.

Parameters:: name (str) – The name of the worksheet.
Returns:: The worksheet with the specified name.
Return type:: WriteOnlyWorksheet

save(path)

Save the workbook to the specified file path.

Parameters:: path (str) – The file path where the workbook will be saved.

sheetnames

Get the names of all worksheets in the workbook.

Returns:: A list of worksheet names.
Return type:: List[str]

class fastxlsx.WriteOnlyWorksheet(title)

Write-only worksheet class

title

write_cell(cell_addr, value, *, dtype=Ellipsis)

Write a value to a specific cell in the worksheet.

Parameters:

cell_addr (Union[Tuple[int, int], str]) – The cell address, either as a 0-based tuple of (row, col) or a string (e.g., “A1”).
value (Any) – The value to write to the cell.
dtype (DType, default DType.Any) – The data type to enforce for the value. If None, try for each type automatically.

write_column(cell_addr, value, *, dtype=None)

Write a column of values starting from a specific cell.

Parameters:

cell_addr (Union[Tuple[int, int], str]) – The starting cell address, either as a tuple of (row, col) or a string (e.g., “A1”).
value (Union[np.ndarray, List[Any]]) – The column of values to write.n MUST be np.ndarray with correct dtype if dtype is one of [DType.Bool, DType.Int, DType.Float]
dtype (Optional[DType], default None) – The data type to enforce for the values. If None, will try for every possible types.n DType.Any allow each item have different type, but will also increase the time cost.

write_matrix(cell_addr, value, *, dtype=None)

Write a matrix of values starting from a specific cell.

Parameters:

cell_addr (Union[Tuple[int, int], str]) – The starting cell address, either as a tuple of (row, col) or a string (e.g., “A1”).
value (Union[np.ndarray, List[List[Any]]]) – The matrix of values to write.n MUST be np.ndarray with correct dtype if dtype is one of [DType.Bool, DType.Int, DType.Float]
dtype (Optional[DType], default None) – The data type to enforce for the values. If None, will try for every possible types.n DType.Any allow each item have different type, but will also increase the time cost.

write_row(cell_addr, value, *, dtype=None)

Write a row of values starting from a specific cell.

Parameters:

cell_addr (Union[Tuple[int, int], str]) – The starting cell address, either as a tuple of (row, col) or a string (e.g., “A1”).
value (Union[np.ndarray, List[Any]]) – The row of values to write. 1d array-like.n MUST be np.ndarray with correct dtype if dtype is one of [DType.Bool, DType.Int, DType.Float]
dtype (Optional[DType], default None) – The data type to enforce for the values. If None, will try for every possible types.n DType.Any allow each item have different type, but will also increase the time cost.

fastxlsx.read_many(workbooks_to_read)

Read values from multiple workbooks based on specified ranges.

This function reads data from multiple workbooks, where each workbook is identified by its file path. For each workbook, a dictionary maps worksheet identifiers (either by name or index) to a list of RangeInfo objects, which describe the ranges of cells to read.

Parameters:

workbooks_to_read (Dict[str, Dict[Union[int, str], Union[List[RangeInfo], Dict[str, RangeInfo]]]]) – A dictionary mapping workbook file paths to nested dictionaries. Each nested dictionary maps worksheet identifiers (either by name or index) to a list or dict of RangeInfo objects.

Returns:

A dictionary mapping workbook file paths to nested dictionaries. Each nested dictionary maps worksheet identifiers (either by name or index) to a list or dict of values read from the specified ranges.

The structure of the returned dictionary mirrors the input workbooks_to_read, with each RangeInfo replaced by the corresponding data.

Return type:

Dict[str, Dict[Union[int, str], Union[List[Any], Dict[str, Any]]]]

Examples

>>> from fastxlsx import RangeInfo, DShape, DType, read_many
>>> wb = WorkbookReanonly("example.xlsx")
>>> workbooks_to_read = {
        "workbook1.xlsx": {
            "Sheet1": [
                RangeInfo((0, 0), DShape.Matrix(2, 2), dtype=DType.Int),
                RangeInfo((2, 0), DShape.Column(3), dtype=DType.Str),
            ],
            1: [RangeInfo((0, 0), DShape.Row(5), dtype=DType.Float)],
        },
        "workbook2.xlsx": {
            0: [RangeInfo((0, 0), DShape.Scalar(), dtype=DType.Str)],
        },
    }
>>> res = read_many(workbooks_to_read)
>>> res
    {
        "workbook1.xlsx": {
            "Sheet1": [np.array([[1, 2], [3, 4]]), ["A", "B", "C"]],
            1: [np.array([1.1, 2.2, 3.3, 4.4, 5.5])],
        },
        "workbook2.xlsx": {0: ["Some string"]},
    }

fastxlsx.write_many(workbooks_to_write)

Write multiple workbooks to disk.

This function writes multiple workbooks to their respective file paths. Each workbook is represented by a list of WriteOnlyWorksheet objects, which contain the data to be written.

Parameters:: workbooks_to_write (Dict[str, List[WriteOnlyWorksheet]]) – A dictionary mapping workbook file paths to lists of WriteOnlyWorksheet objects. Each WriteOnlyWorksheet object represents a worksheet containing data to be written.

Examples

>>> from fastxlsx import DType, WriteOnlyWorksheet, write_many
>>> workbooks_to_write = {}
>>> for i_workbook in range(10):
        ws_list = []
        for i_sheet in range(6):
            ws = WriteOnlyWorksheet(f"Sheet{i_sheet}")
            ws.write_cell("A1", 10 * i_workbook + i_sheet, dtype=DType.Int)
            ws.write_matrix((1, 1), np.random.random((3, 3)), dtype=DType.Float)
            ws_list.append(ws)
        workbooks_to_write[f"workboopk_{i_workbook}.xlsx"] = ws_list
>>> write_many(workbooks_to_write)

fastxlsx.version(): Returns the current version of the library.

fastxlsx.addr_to_idx(addr)

Convert a cell address string (e.g., “A1”) to a 0-based (row, col) index.

Parameters:: addr (str) – The cell address string (e.g., “A1”).
Returns:: A tuple of (row, col) indices.
Return type:: Tuple[int, int]

fastxlsx.idx_to_addr(row, col)

Convert a 0-based (row, col) index to a cell address string (e.g., “A1”).

Parameters:

row (int) – The 0-based row index.
col (int) – The 0-based column index.

Returns:

The cell address string (e.g., “A1”).

Return type:

str