The Book Object

class Book

Contents of a “workbook”.

WARNING: You don’t call this class yourself. You use the Book object that was returned when you called xlrd.open_workbook(“myfile.xls”).</p>

Book.biff_version

Version of BIFF (Binary Interchange File Format) used to create the file. Latest is 8.0 (represented here as 80), introduced with Excel 97. Earliest supported by this module: 2.0 (represented as 20).

Book.codepage

An integer denoting the character set used for strings in this file. For BIFF 8 and later, this will be 1200, meaning Unicode; more precisely, UTF_16_LE. For earlier versions, this is used to derive the appropriate Python encoding to be used to convert to Unicode.

Examples: 1252 -> ‘cp1252’, 10000 -> ‘mac_roman’

Book.colour_map

This provides definitions for colour indexes. Please refer to the above section “The Palette; Colour Indexes” for an explanation of how colours are represented in Excel.

Colour indexes into the palette map into (red, green, blue) tuples. “Magic” indexes e.g. 0x7FFF map to None.

colour_map is what you need if you want to render cells on screen or in a PDF file. If you are writing an output XLS file, use palette_record.

– New in version 0.6.1. Extracted only if open_workbook(..., formatting_info=True)

Book.countries

A tuple containing the (telephone system) country code for:

• [0]: the user-interface setting when the file was created.
• [1]: the regional settings.

Example: (1, 61) meaning (USA, Australia).

This information may give a clue to the correct encoding for an unknown codepage. For a long list of observed values, refer to the OpenOffice.org documentation for the COUNTRY record.

Book.datemode

Which date system was in force when this file was last saved.

Value	Description
0	1900 system (the Excel for Windows default).
1	1904 system (the Excel for Macintosh default).

Book.encoding

The encoding that was derived from the codepage.

Book.font_list

A list of Font class instances, each corresponding to a FONT record.

– New in version 0.6.1

Book.format_list

A list of Format objects, each corresponding to a FORMAT record, in the order that they appear in the input file. It does not contain builtin formats. If you are creating an output file using (for example) pyExcelerator, use this list.

The collection to be used for all visual rendering purposes is format_map.

– New in version 0.6.1

Book.format_map

The mapping from XF.format_key to Format object.

– New in version 0.6.1

Book.load_time_stage_1

Time in seconds to extract the XLS image as a contiguous string (or mmap equivalent).

Book.load_time_stage_2

Time in seconds to parse the data from the contiguous string (or mmap equivalent).

Book.name_and_scope_map

A mapping from (lower_case_name, scope) to a single Name object.

– New in version 0.6.0

Book.name_map

A mapping from lower_case_name to a list of Name objects. The list is sorted in scope order. Typically there will be one item (of global scope) in the list.

– New in version 0.6.0

Book.name_obj_list

List containing a Name object for each NAME record in the workbook.

– New in version 0.6.0

Book.nsheets

The number of worksheets present in the workbook file. This information is available even when no sheets have yet been loaded.

Book.palette_record

If the user has changed any of the colours in the standard palette, the XLS file will contain a PALETTE record with 56 (16 for Excel 4.0 and earlier) RGB values in it, and this list will be e.g. [(r0, b0, g0), ..., (r55, b55, g55)]. Otherwise this list will be empty. This is what you need if you are writing an output XLS file. If you want to render cells on screen or in a PDF file, use colour_map.

– New in version 0.6.1. Extracted only if open_workbook(..., formatting_info=True)

Book.sheet_by_index(sheetx)

Parameters:

• sheetx (int) – Sheet index in range(nsheets)

Returns:

An object of the Sheet class

Book.sheet_by_name(sheet_name)

Parameters:

• sheet_name (str) – Name of sheet required

Returns:

An object of the Sheet class

Book.sheet_loaded(sheet_name_or_index)

Parameters:

• sheet_name_or_index – Name or index of sheet enquired upon

Returns:

True if sheet is loaded, False otherwise

– New in version 0.7.1

Book.sheet_names()

Returns:A list of the names of all the worksheets in the workbook file. This information is available even when no sheets have yet been loaded.

Book.sheets()

Returns:A list of all sheets in the book. All sheets not already loaded will be loaded.

Book.style_name_map

This provides access via name to the extended format information for both built-in styles and user-defined styles.

It maps name to (built_in, xf_index), where:

name

is either the name of a user-defined style, or the name of one of the built-in styles. Known built-in names are Normal, RowLevel_1 to RowLevel_7, ColLevel_1 to ColLevel_7, Comma, Currency, Percent, “Comma [0]”, “Currency [0]”, Hyperlink, and “Followed Hyperlink”.

built_in

Value	Description
0	user-defined
1	built-in style

xf_index

is an index into Book.xf_list.

References: OOo docs s6.99 (STYLE record); Excel UI Format/Style

– New in version 0.6.1

Book.unload_sheet(sheet_name_or_index)

Parameters:

• sheet_name_or_index – Name or index of sheet to be unloaded.

– New in version 0.7.1

Book.user_name

What (if anything) is recorded as the name of the last user to save the file.

Book.xf_list

A list of XF class instances, each corresponding to an XF record.

– New in version 0.6.1