===========================
How to handle time in irfpy
===========================

Introduction
============
A general way for python to handle the time is using ``datetime`` module.
``datetime.datetime`` class provide various way (including localtime) of
handling the time.

There are three typical way of expressing time in ``irfpy``.

* ``datetime.datetime`` class object
* Floating epoch time (POSIX type)
* ``Julday`` object

In addition, there are fourth commonly used time definition, i.e. ``matplotlib`` time.
This is an offset of Julian day by **(TBC)** and very similar to ``Matlab`` time.
This is not implemented in this version of ``irfpy``, but obviously in a near future scope.

utc module
==========
``utc`` module mainly provides the conversion among the above defined time format.

.. code-block:: py

        >>> import datetime
        >>> t = datetime.datetime(2010, 12, 19, 14, 23, 27)
        >>> print t
        2010-12-19 14:23:27

Only ``datetime`` without localtime zone is supported.

The time *t* can be converted by ``utc.convert`` function.
First argument is the time and the second (indeed this is *outfmt* keyword) is the format to be converted.
Default is *float*.

.. code-block:: py

        >>> from irfpy.util import utc
        >>> t_float = utc.convert(t)
        >>> print t_float
        1292768607.0

        >>> from irfpy.util import julday
        >>> t_julday = utc.convert(t, julday.Julday)
        >>> print t_julday
        Julday(2010, 12, 19, 14, 23, 27.000)