=======
display
=======

This module contains functions that allow easy and safe display of
information returned by xlrd.

The functions are as follows:

*quoted_sheet_name(sheet_name,encoding='ascii')*

  This returns a string-version of the supplied sheet name that is
  safe to display.

  This includes encoding the unicode titlename into a string:

  >>> from xlutils.display import quoted_sheet_name
  >>> quoted_sheet_name(u'Price(\xa3)','utf-8')
  'Price(\xc2\xa3)'

  Quoting if there are spaces in the sheet name:
  
  >>> quoted_sheet_name(u'My Sheet')
  "'My Sheet'"

  And replacing single quotes with double quotes in sheet names: 

  >>> quoted_sheet_name(u"John's Sheet")
  "'John''s Sheet'"

*cell_display(cell,datemode=0,encoding='ascii')*

  This returns a string representation of the supplied cell, no matter
  what type of cell it is. Here's some example output

  >>> import xlrd
  >>> from xlrd.sheet import Cell
  >>> from xlutils.display import cell_display
  
  >>> cell_display(Cell(xlrd.XL_CELL_EMPTY,''))
  'undefined'

  >>> cell_display(Cell(xlrd.XL_CELL_BLANK,''))
  'blank'

  >>> cell_display(Cell(xlrd.XL_CELL_NUMBER,1.2))
  'number (1.2000)'

  >>> cell_display(Cell(xlrd.XL_CELL_DATE,36892.0))
  'date (2001-01-01 00:00:00)'

  Erroneous date values will be displayed like this:

  >>> cell_display(Cell(xlrd.XL_CELL_DATE,1.5))
  'date? (1.500000)'

  NB: To display dates correctly, make sure that datemode is passed
      and is taken from the datemode attribute of the xlrd.Book from
      which the cell originated.

  >>> cell_display(Cell(xlrd.XL_CELL_TEXT,u'Price (\xa3)'))
  'text (Price (?))'

  >>> cell_display(Cell(xlrd.XL_CELL_TEXT,u'Price (\xa3)'),encoding='utf-8')
  'text (Price (\xc2\xa3))'

  >>> cell_display(Cell(xlrd.XL_CELL_ERROR,0))
  'error (#NULL!)'

  >>> cell_display(Cell(xlrd.XL_CELL_ERROR,2000))
  'unknown error code (2000)'

  >>> cell_display(Cell(xlrd.XL_CELL_BOOLEAN,0))
  'logical (FALSE)'

  If you manage to pass a cell with an unknown cell type, an exception
  will be raised:

  >>> cell_display(Cell(69,0))
  Traceback (most recent call last):
  ...
  Exception: Unknown Cell.ctype: 69
