==================================
Epoch Timestamp Management Utility
==================================

The `epoch` provides a set of routines that help with the management
of UNIX epoch timestamps, including generation, adjustment, and
parsing.


Project
=======

* Homepage: https://github.com/metagriffin/epoch
* Bugs: https://github.com/metagriffin/epoch/issues


Installation
============

.. code:: bash

  $ pip install epoch


Usage
=====

The following routines are available:

* ``epoch.now()`` : float

  Returns a float representation of the current UNIX epoch timestamp,
  i.e. the number of seconds since 1970/01/01.

* ``epoch.sod([ts][, tz][, offset])`` : float

  Returns the epoch timestamp of the start of the current day relative
  to the timezone `tz`. If `ts` is specified, the start of the day
  containing `ts` is returned. If `offset` is specified, it is taken
  to be an integral number of days to offset the returned value by.
  Note that due to leap seconds, daylight savings, etc, this is more
  complex than just 60 seconds * 60 minutes * 24 hours.

* ``epoch.sow([ts][, tz][, offset][, day])`` : float

  Returns the epoch timestamp of the start of the current Gregorian
  week relative to the timezone `tz`. If `ts` is specified, the start
  of the week containing `ts` is returned. If `offset` is specified,
  it is taken to be an integral number of weeks to offset the returned
  value by. Note that due to leap days, leap seconds, daylight
  savings, etc, this is more complex than just 60 seconds * 60 minutes
  * 24 hours * 7 days. If `day` is specified, it specifies which day
  is defined to be the "first" day of the week, where ``0`` (the
  default) is Monday through ``6`` being Sunday.

* ``epoch.som([ts][, tz][, offset])`` : float

  Returns the epoch timestamp of the start of the current Gregorian
  month relative to the timezone `tz`. If `ts` is specified, the start
  of the month containing `ts` is returned. If `offset` is specified,
  it is taken to be an integral number of months to offset the returned
  value by.

* ``epoch.soy([ts][, tz][, offset])`` : float

  Returns the epoch timestamp of the start of the current Gregorian
  year relative to the timezone `tz`. If `ts` is specified, the start
  of the year containing `ts` is returned. If `offset` is specified,
  it is taken to be an integral number of years to offset the returned
  value by.

* ``epoch.zulu([ts][, ms])`` : string

  Returns the specified epoch time `ts` (or current time if None or
  not provided) as an ISO 8601 Combined string in zulu time (with
  millisecond precision), e.g. ``epoch.zulu(1362187446.553)`` =>
  ``'2013-03-02T01:24:06.553Z'``. If `ms` is True (the default),
  milliseconds will be included, otherwise truncated. If `ts` has
  beyond-millisecond precision, it will be truncated to
  millisecond-level precision.

* ``epoch.parseZulu(text)`` : string

  Parses an ISO 8601 Combined string into an epoch timestamp. Note
  that this function is intended to be used with strings generated by
  `epoch.zulu`, and is therefore not very forgiving. For a much more
  human-friendly parser, try::

    import dateutil.parser
    result = dateutil.parser.parse(text, tzinfos = {'UTC': 0}))

  but please note that it does not properly warn about ambiguities;
  for example ``01/02/03`` gets interpreted without hesitation as
  ``2003/01/02``... ugh.

Note that the `epoch` package, when working with `datetime` objects,
always uses timezone-aware objects.
