epoch 0.1.1

A utility library to manage and manipulate UNIX epoch timestamps.

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

$ 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) : float

  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.