The Cell Object
===============

.. class:: Cell(ctype, value, xf_index=None)

   Contains the data for one cell. (:class:`XFCell` is the base class of :class:`Cell`)

   WARNING: You don't call this class yourself. You access Cell objects
   via methods of the Sheet object(s) that you found in the Book object that
   was returned when you called :func:`open_workbook`.

Cell objects have three attributes:

.. attribute:: Cell.ctype

   is an int

.. attribute:: Cell.value

  (which depends on :attr:`ctype`)

.. attribute:: Cell.xf_index

  If "formatting_info" is not enabled when the workbook is opened, xf_index will be None.
  The following table describes the types of cells and how their values
  are represented in Python.

=============== =============== =================================================================
Type symbol 	Type number 	Python value
=============== =============== =================================================================
XL_CELL_EMPTY 	    0 	        empty string ''
XL_CELL_TEXT 	    1 	        a Unicode string
XL_CELL_NUMBER 	    2 	        float
XL_CELL_DATE 	    3           float
XL_CELL_BOOLEAN     4 	        int; 1 means *True*, 0 means *False*
XL_CELL_ERROR 	    5 	        int representing internal Excel codes; for a text representation,
                                refer to the supplied dictionary error_text_from_code
XL_CELL_BLANK 	    6           empty string ''. Note: this type will appear only when
                                open_workbook(..., formatting_info= *True*) is used.
=============== =============== =================================================================

.. class:: XFCell

   Add convenient methods and attributes for easy access of cell properties.
   (:class:`XFCell` is the base class of :class:`Cell`!)

   - *New in xlrd3 0.1.1*

.. attribute:: XFCell.has_xf

   *True* if cell has a xf record. Workbook was opened with formatting_info=True.

.. method:: XFCell.get_color(index)

   Get rgb-tuple of color index.

.. attribute:: XFCell.book

   The :class:`Book` object.

.. attribute:: XFCell.sheet

   The :class:`Sheet` object.

.. attribute:: XFCell.xf

   The :class:`XF` object.


.. attribute:: XFCell.is_datetime

   *True* if cell type is XL_CELL_DATE.

.. attribute:: XFCell.has_date

   *True* if cell has a valid **date** and not only a time.

.. method:: XFCell.datetime()

   Returns a datetime.datetime object if cell type is XL_CELL_DATE
   else raises a **TypeError**. Raises **ValueError** if the cell does
   not have a date value (only a time value is present).

.. method:: XFCell.date()

   Returns a datetime.date object if cell type is XL_CELL_DATE
   else raises a **TypeError**. Raises **ValueError** if the cell does not have
   a date value (only a time value is present).

.. method:: XFCell.time()

   Returns a datetime.time object if cell type is XL_CELL_DATE else
   raises a **TypeError**.

.. attribute:: XFCell.background

   Get the :class:`XFBackground` object.

.. method:: XFCell.background_color()

   Get the background color as rgb-tuple.

.. method:: XFCell.pattern_color()

   Get the pattern color as rgb-tuple.

.. method:: XFCell.fill_pattern()

   Get the fill pattern. see :attr:`XFBackground.fill_pattern`

.. method:: XFCell.font()

   Get the :class:`Font` object.

.. method:: XFCell.font_color()

   Get the font color as rgb-tuple.

.. method:: XFCell.format()

   Get the :class:`Format` object.

.. method:: XFCell.format_str()

   Get the :attr:`Format.format_str`.

.. method:: XFCell.alignment()

   Get the :class:`XFAlignment` object.

.. method:: XFCell.bordercolors()

   Get border colors as dict of rgb-color-tuples.

   keys: 'top', 'bottom', 'left', 'right', 'diag'

   example get rgb-values for the top cell border::

      colors = cell.bordercolors()
      r,g,b = colors['top']

.. method:: XFCell.borderstyles()

   Get border styles as dict of int. Border styles see :class:`XFBorder`

   keys: 'top', 'bottom', 'left', 'right', 'diag'

.. attribute:: XFCell.has_up_diag

   If *True* draw a line across the cell from bottom left to top right.

.. attribute:: XFCell.has_down_diag

   If *True* draw a line across the cell from top left to bottom right.

.. attribute:: XFCell.is_cell_locked

   see :attr:`XFProtection.cell_locked`

.. attribute:: XFCell.is_formula_hidden

   see :attr:`XFProtection.formula_hidden`