Module Contents

class BaseObject

Parent of almost all other classes in the package.

For more information about this class, see The BaseObject Class.

class Book

Contents of a “workbook”.

For more information about this class, see Book.

class Cell(ctype, value, xf_index=None)

Contains the data for one cell.

For more information about this class, see Cell.

cellname(rowx, colx)

Utility function: (5, 7) => ‘H6’

cellnameabs(rowx, colx)

Utility function: (5, 7) => ‘$H$6’

class Colinfo

Width and default formatting information that applies to one or more columns in a sheet.

For more information about this class, see Colinfo.

colname(colx)

Utility function: 7 => ‘H’, 27 => ‘AB’

count_records(filename, outfile=sys.stdout)

For debugging and analysis: summarise the file’s BIFF records. I.e. produce a sorted file of (record_name, count).

Parameters:

• filename (str) – The path to the file to be summarised.
• outfile (filelike) – An open file, to which the summary is written.

dump(filename, outfile=sys.stdout, unnumbered=False)

For debugging: dump the file’s BIFF records in char & hex.

Parameters:

• filename (dtr) – The path to the file to be dumped.
• outfile (filelike) – An open file, to which the dump is written.
• unnumbered (bool) – If True, omit offsets (for meaningful diffs).

empty_cell

There is one and only one instance of an empty cell – it’s a singleton. This is it. You may use a test like “acell is empty_cell”.

class EqNeAttrs

This mixin class exists solely so that Format, Font, and XF....

For more information about this class, see EqNeAttrs.

error_text_from_code

This dictionary can be used to produce a text version of the internal codes that Excel uses for error cells. Here are its contents:

0x00: '#NULL!',  # Intersection of two cell ranges is empty
0x07: '#DIV/0!', # Division by zero
0x0F: '#VALUE!', # Wrong type of operand
0x17: '#REF!',   # Illegal or deleted cell reference
0x1D: '#NAME?',  # Wrong function or range name
0x24: '#NUM!',   # Value range overflow
0x2A: '#N/A!',   # Argument or function not available

class Font

An Excel “font” contains the details of not only what is normally considered a font, but also several other display attributes.

For more information about this class, see Font.

class Format(format_key, ty, format_str)

“Number format” information from a FORMAT record.

For more information about this class, see Format.

class Name

Information relating to a named reference, formula, macro, etc.

For more information about this class, see Name

open_workbook(filename=None, logfile=sys.stdout, verbosity=0, pickleable=True, use_mmap=USE_MMAP, file_contents=None, encoding_override=None, formatting_info=False, on_demand=False)

Open a spreadsheet file for data extraction.

Parameters:

• filename (str) – The path to the spreadsheet file to be opened.
• logfile (filelike) – An open file to which messages and diagnostics are written.
• verbosity (int) – Increases the volume of trace material written to the logfile.
• pickleable (bool) – only for compatibility reason Note: if you have large files that you need to read multiple times, it can be much faster to cPickle.dump() the xlrd.Book object once, and use cPickle.load() multiple times.
• use_mmap (bool) – Whether to use the mmap module is determined heuristically. Use this arg to override the result. Current heuristic: mmap is used if it exists.
• file_contents – ... as a string or an mmap.mmap object or some other behave-alike object. If file_contents is supplied, filename will not be used, except (possibly) in messages.
• encoding_override (str) –

  Used to overcome missing or bad codepage information in older-version files. Refer to discussion in the Unicode section above.

  – New in version 0.6.0

• formatting_info (bool) –

  Governs provision of a reference to an XF (eXtended Format) object for each cell in the worksheet.

  Default is False. This is backwards compatible and saves memory. “Blank” cells (those with their own formatting information but no data) are treated as empty (by ignoring the file’s BLANK and MULBLANK records). It cuts off any bottom “margin” of rows of empty (and blank) cells and any right “margin” of columns of empty (and blank) cells. Only cell_value and cell_type are available.

  True provides all cells, including empty and blank cells. XF information is available for each cell.

  – New in version 0.6.1

• on_demand (bool) –

  Governs whether sheets are all loaded initially or when demanded by the caller. Please refer back to the section “Loading worksheets on demand” for details.

  – New in version 0.7.1

Returns:

An instance of the Book class.

class Operand(akind=None, avalue=None, arank=0, atext='?')

Used in evaluating formulas.

For more information about this class, see Operand .

rangename3d(book, ref3d)

Utility function: Ref3D((1, 4, 5, 20, 7, 10)) => ‘Sheet2:Sheet3!$H$6:$J$20’

rangename3drel(book, ref3d)

Utility function:

Ref3D(coords=(0, 1, -32, -22, -13, 13), relflags=(0, 0, 1, 1, 1, 1)) => ‘Sheet1![@-13,#-32]:[@+12,#-23]’

where ‘@’ refers to the current or base column and ‘#’ refers to the current or base row.

class Ref3D(atuple)

Represents an absolute or relative 3-dimensional reference to a box of one or more cells.

For more information about this class, see Ref3D.

class Rowinfo

Height and default formatting information that applies to a row in a sheet.

For more information about this class, see Rowinfo.

class Sheet(book, position, name, number)

Contains the data for one worksheet.

For more information about this class, see Sheet.

class XF

eXtended Formatting information for cells, rows, columns and styles.

For more information about this class, see XF.

class XFAlignment

A collection of the alignment and similar attributes of an XF record.

For more information about this class, see XFAlignment.

class XFBorder

A collection of the border-related attributes of an XF record.

For more information about this class, see XFBorder-class.

class XFProtection

A collection of the protection-related attributes of an XF record.

For more information about this class, see XFProtection.

xldate_as_tuple(xldate, datemode)

Convert an Excel number (presumed to represent a date, a datetime or a time) into a tuple suitable for feeding to datetime or mx.DateTime constructors.

Parameters:

• xldate – The Excel number
• datemode (int) –

  0 - 1900-based, 1 - 1904-based.

  WARNING: when using this function to interpret the contents of a workbook, you should pass in the Book.datemode attribute of that workbook. Whether the workbook has ever been anywhere near a Macintosh is irrelevant.

Returns:

Gregorian (year, month, day, hour, minute, nearest_second).

Special case: if 0.0 <= xldate < 1.0, it is assumed to represent a time; (0, 0, 0, hour, minute, second) will be returned.

Note: 1904-01-01 is not regarded as a valid date in the datemode 1 system; its “serial number” is zero.

Raises XLDateNegative:

xldate < 0.00

Raises XLDateAmbiguous:

The 1900 leap-year problem (datemode == 0 and 1.0 <= xldate < 61.0)

Raises XLDateTooLarge:

Gregorian year 10000 or later

Raises XLDateBadDatemode:

datemode arg is neither 0 nor 1

Raises XLDateError:

Covers the 4 specific errors

xldate_from_date_tuple((year, month, day), datemode)

Convert a date tuple (year, month, day) to an Excel date.</p>

Parameters:

• year (int) – Gregorian year.
• month (int) – 1 <= month <= 12
• day (int) – 1 <= day <= last day of that (year, month)
• datemode (int) – 0 - 1900-based, 1 - 1904-based.

Raises XLDateAmbiguous:

The 1900 leap-year problem (datemode == 0 and 1.0 <= xldate < 61.0)

Raises XLDateBadDatemode:

datemode arg is neither 0 nor

Raises XLDateBadTuple:

(year, month, day) is too early/late or has invalid component(s)

Raises XLDateError:

Covers the specific errors

xldate_from_datetime_tuple(datetime_tuple, datemode)

Convert a datetime tuple (year, month, day, hour, minute, second) to an Excel date value. For more details, refer to other xldate_from_*_tuple functions.

Parameters:

• datetime_tuple – (year, month, day, hour, minute, second)
• datemode (int) – 0 - 1900-based, 1 - 1904-based.

xldate_from_time_tuple(time_tuple)

Convert a time_tuple (hour, minute, second) to an Excel “date” value (fraction of a day).

Parameters:

• date (tuple) –

  (hour, minute, second)

  • hour: 0 <= hour < 24
  • minute: 0 <= minute < 60
  • second: 0 <= second < 60

Raises XLDateBadTuple:

Out-of-range hour, minute, or second