API reference

Top-level functions

pyxlsb.open_workbook(name, *args, **kwargs)

Opens the given workbook file path.

Parameters

name (str) – The name of the XLSB file to open.

Returns

The workbook instance for the given file name.

Return type

Workbook

Examples

This is typically the entrypoint to start working with an XLSB file:

>>> from pyxlsb import open_workbook
>>> with open_workbook('test_files/test.xlsb') as wb:
...     print(wb.sheets)
...
['Test']
pyxlsb.convert_date(date)

Convert an Excel date to a datetime instance.

Parameters

date (int or float) – The numeric Excel date value to convert.

Returns

The corresponding datetime instance or None if invalid.

Return type

datetime

Deprecated since version 1.1.0: Will be removed in 1.2.0. Use convert_date on Workbook instances instead.

Workbook

class pyxlsb.workbook.Workbook(pkg)

The main Workbook class providing worksheets and other metadata.

sheets

The worksheet names in this workbook.

Type

list(str)

get_sheet(idx_or_name, with_rels=False)

Get a sheet by name or 1-based index.

Parameters

  • idx_or_name (int or str) – The 1-based index or name of the sheet

  • with_rels (bool, optional) – If the relationships should be parsed, defaults to False

Returns

The corresponding worksheet instance.

Return type

Worksheet

Raises

  • IndexError – When the index or name is invalid.

  • ValueError – For an incompatible index or name type.

Deprecated since version 1.1.0: Will be removed in 1.2.0. Use either get_sheet_by_index or get_sheet_by_name instead.

get_sheet_by_index(idx, with_rels=False)

Get a worksheet by index.

Parameters

  • idx (int) – The index of the sheet.

  • with_rels (bool, optional) – If the relationships should be parsed, defaults to False

Returns

The corresponding worksheet instance.

Return type

Worksheet

Raises

IndexError – When the provided index is out of range.

get_sheet_by_name(name, with_rels=False)

Get a worksheet by its name.

Parameters

  • name (str) – The name of the sheet.

  • with_rels (bool, optional) – If the relationships should be parsed, defaults to False

Returns

The corresponding worksheet instance.

Return type

Worksheet

Raises

IndexError – When the provided name is invalid.

get_shared_string(idx)

Get a string in the shared string table.

Parameters

idx (int) – The index of the string in the shared string table.

Returns

The string at the index in table table or None if not found.

Return type

str

convert_date(value)

Convert an Excel numeric date value to a datetime instance.

Parameters

value (int or float) – The Excel date value.

Returns

The equivalent datetime instance or None when invalid.

Return type

datetime.datetime

convert_time(value)

Convert an Excel date fraction time value to a time instance.

Parameters

value (float) – The Excel fractional day value.

Returns

The equivalent time instance or None if invalid.

Return type

datetime.time

close()

Release the resources associated with this workbook.

Worksheet

class pyxlsb.worksheet.Worksheet(workbook, name, fp, rels_fp=None)

A worksheet.

workbook

The containing workbook.

Type

Workbook

name

The name of this worksheet.

Type

str

rows(sparse=True)

Get a row iterator to iterate through the cell data.

Parameters

sparse (bool, optional) – If empty rows should be skipped, defaults to True

Yields

Row – The rows in this worksheet.

close()

Release the resources associated with this worksheet.

Row

class pyxlsb.row.Row(sheet, num)

A row in a worksheet.

Cell

class pyxlsb.cell.Cell(row, col, value=None, formula=None, style_id=None)

A cell in a worksheet.

row

The containing row.

Type

Row

col

The column index for this cell.

Type

int

value

The cell value.

Type

mixed

formula

The formula PTG bytes.

Type

bytes

style_id

The style index in the style table.

Type

int

property row_num

The row number of this cell.

property string_value

The string value of this cell or None if not a string.

property numeric_value

The numeric value of this cell or None if not a number.

property bool_value

The boolean value of this cell or None if not a boolean.

property date_value

The date value of this cell or None if not a numeric cell.

property is_date_formatted

If this cell is formatted using a date-like format code.

property c

The column number of this cell.

Deprecated since version 1.1.0: Use the col property instead.

property f

The formula of this cell.

Deprecated since version 1.1.0: Use the formula property instead.

property r

The row number of this cell.

Deprecated since version 1.1.0: Use the row_num property instead.

property v

The value of this cell.

Deprecated since version 1.1.0: Use the value or the typed *_value properties instead.