Module Contents
===============

.. class:: BaseObject
   :noindex:
   
   Parent of almost all other classes in the package.
   
   For more information about this class, see :ref:`The BaseObject Class <biffh.BaseObject-class>`.

.. class:: Book()
   :noindex:
   
   Contents of a "workbook".
   
   For more information about this class, see :class:`Book`.

.. class:: Cell(ctype, value, xf_index=None)
   :noindex:
   
   Contains the data for one cell.
   
   For more information about this class, see :class:`Cell`.

.. function:: cellname(rowx, colx)

   Utility function: (5, 7) => 'H6'

.. function:: cellnameabs(rowx, colx)

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

.. class:: Colinfo()
   :noindex:

   Width and default formatting information that applies to one or
   more columns in a sheet.
  
   For more information about this class, see :class:`Colinfo`.

.. function:: colname(colx)

   Utility function: 7 => 'H', 27 => 'AB'

.. function:: 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).

   :param str filename: The path to the file to be summarised.
   :param filelike outfile: An open file, to which the summary is written.
  
.. function:: dump(filename, outfile=sys.stdout, unnumbered=False)

   For debugging: dump the file's BIFF records in char & hex.
   
   :param dtr filename: The path to the file to be dumped.
   :param filelike outfile: An open file, to which the dump is written.
   :param bool unnumbered: If **True**, omit offsets (for meaningful diffs).
   
.. attribute:: 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
   :noindex:
   
   This mixin class exists solely so that Format, Font, and XF....
   
   For more information about this class, see :class:`EqNeAttrs`.

.. attribute:: 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
   :noindex:

   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 :class:`Font`.

.. class:: Format(format_key, ty, format_str)
   :noindex:

   "Number format" information from a FORMAT record.
   
   For more information about this class, see :class:`Format`.

.. class:: Name
   :noindex:

   Information relating to a named reference, formula, macro, etc.
   
   For more information about this class, see :class:`Name`

.. function:: 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.

   :param str filename: The path to the spreadsheet file to be opened.
   :param filelike logfile: An open file to which messages and diagnostics are written.
   :param int verbosity: Increases the volume of trace material written to the logfile.
   :param bool pickleable: 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.
   :param bool use_mmap: Whether to use the mmap module is determined heuristically.
       Use this arg to override the result. Current heuristic: mmap is used if it exists.
   :param 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.
   :param str encoding_override: 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*
   :param bool formatting_info: 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*
   :param bool on_demand: 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='?')
   :noindex:
   
   Used in evaluating formulas.
   
   For more information about this class, see :class:`Operand` .

.. function:: rangename3d(book, ref3d)

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

.. function:: 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)
   :noindex:

   Represents an absolute or relative 3-dimensional reference to a box
   of one or more cells.
   
   For more information about this class, see :class:`Ref3D`.

.. class:: Rowinfo
   :noindex:
   
   Height and default formatting information that applies to a row in a sheet.
   
   For more information about this class, see :class:`Rowinfo`.

.. class:: Sheet(book, position, name, number)
   :noindex:

   Contains the data for one worksheet.
   
   For more information about this class, see :class:`Sheet`.

.. class:: XF
   :noindex:

   eXtended Formatting information for cells, rows, columns and styles.
   
   For more information about this class, see :class:`XF`.
   
.. class:: XFAlignment
   :noindex:
   
   A collection of the alignment and similar attributes of an XF record.
   
   For more information about this class, see :class:`XFAlignment`.
   
.. class::XFBackground
   :noindex:
   
   A collection of the background-related attributes of an XF record.
   
   For more information about this class, see :class:`XFBackground`.

.. class:: XFBorder
   :noindex:

   A collection of the border-related attributes of an XF record.
   
   For more information about this class, see :class:`XFBorder-class`.
   
.. class:: XFProtection
   :noindex:

   A collection of the protection-related attributes of an XF record.
   
   For more information about this class, see :class:`XFProtection`.

.. function:: xldate_as_tuple(xldate, datemode)
   :noindex:
   
   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.
   
   :param xldate: The Excel number
   :param int datemode: 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

.. function:: xldate_from_date_tuple((year, month, day), datemode)

   Convert a date tuple (year, month, day) to an Excel date.</p>
   
   :param int year: Gregorian year.
   :param int month: 1 <= month <= 12
   :param int day: 1 <= day <= last day of that (year, month)
   :param int datemode: 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
   
.. function:: 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.
   
   :param datetime_tuple: (year, month, day, hour, minute, second)
   :param int datemode: 0 - 1900-based, 1 - 1904-based.

.. function:: xldate_from_time_tuple(time_tuple)

   Convert a time_tuple (hour, minute, second) to an Excel "date" value (fraction of a day).
   
   :param tuple date: (hour, minute, second)
   
      - hour: 0 <= hour < 24
      - minute: 0 <= minute < 60
      - second: 0 <= second < 60

Raises **XLDateBadTuple**:
	Out-of-range hour, minute, or second