Package: epoch
==================================Epoch Timestamp Management Utility==================================The `epoch` provides a set of routines that help with the managementof UNIX epoch timestamps, including generation, adjustment, andparsing.Project=======* Homepage: https://github.com/metagriffin/epoch* Bugs: https://github.com/metagriffin/epoch/issuesInstallation============.. code:: bash$ pip install epochUsage=====The following routines are available:* ``epoch.now()`` : floatReturns a float representation of the current UNIX epoch timestamp,i.e. the number of seconds since 1970/01/01.* ``epoch.sod([ts][, tz][, offset][, replace])`` : floatReturns the epoch timestamp of the start of the current day relativeto the timezone `tz`. If `ts` is specified, the start of the daycontaining `ts` is returned. If `offset` is specified, it is takento be an integral number of days to offset the returned value by.Note that due to leap seconds, daylight savings, etc, this is morecomplex than just 60 seconds * 60 minutes * 24 hours. If `replace`is specified, it is a dictionary of datetime attributes to replaceafter all other modifications have been made.For example, the following will return the epoch timestamp inAnchorage, AK, USA for tomorrow at 3 PM local time:.. code:: pythonepoch.sod(offset=1, tz='America/Anchorage', replace=dict(hour=15))* ``epoch.sow([ts][, tz][, offset][, day][, replace])`` : floatReturns the epoch timestamp of the start of the current Gregorianweek relative to the timezone `tz`. If `ts` is specified, the startof the week containing `ts` is returned. If `offset` is specified,it is taken to be an integral number of weeks to offset the returnedvalue by. Note that due to leap days, leap seconds, daylightsavings, etc, this is more complex than just 60 seconds * 60 minutes* 24 hours * 7 days. If `day` is specified, it specifies which dayis defined to be the "first" day of the week, where ``0`` (thedefault) is Monday through ``6`` being Sunday. If `replace` isspecified, it is a dictionary of datetime attributes to replaceafter all other modifications have been made (see `epoch.sod` forexamples).* ``epoch.som([ts][, tz][, offset][, replace])`` : floatReturns the epoch timestamp of the start of the current Gregorianmonth relative to the timezone `tz`. If `ts` is specified, the startof the month containing `ts` is returned. If `offset` is specified,it is taken to be an integral number of months to offset thereturned value by. If `replace` is specified, it is a dictionary ofdatetime attributes to replace after all other modifications havebeen made (see `epoch.sod` for examples).* ``epoch.soy([ts][, tz][, offset][, replace])`` : floatReturns the epoch timestamp of the start of the current Gregorianyear relative to the timezone `tz`. If `ts` is specified, the startof the year containing `ts` is returned. If `offset` is specified,it is taken to be an integral number of years to offset the returnedvalue by. If `replace` is specified, it is a dictionary of datetimeattributes to replace after all other modifications have been made(see `epoch.sod` for examples).* ``epoch.zulu([ts][, ms])`` : stringReturns the specified epoch time `ts` (or current time if None ornot provided) as an ISO 8601 Combined string in zulu time (withmillisecond 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` hasbeyond-millisecond precision, it will be truncated tomillisecond-level precision.* ``epoch.parseZulu(text)`` : floatParses an ISO 8601 Combined string into an epoch timestamp. Notethat this function is limited to microsecond-level accuracy (a`datetime` system library limitation) and isintended to be used withstrings generated by `epoch.zulu`, and is therefore not veryforgiving. For a much more human-friendly parser, try::import dateutil.parserresult = 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.* ``epoch.parse(value)`` : floatTries the following methods of extracting an epoch timestamp from`text`:* Checks for None, integer, or float type (and returns that as-is)* Checks for an all-digits text, and casts that to float* Fallsback to parsing via :func:`epoch.parseZulu`Note that this function is intended to be used with code-generatedstrings (such as those generated by `epoch.zulu`), and is thereforenot very forgiving. For a much more human-friendly parser, see theexample in :func:`epoch.parseZulu`.* ``epoch.tsreplace([ts][, tz][, *params])`` : floatAn epoch timestamp-oriented version of `epoch.dtreplace`. Example:.. code:: pythonimport epochts = epoch.parse('2015-12-08T14:56:33Z')# ts == 1449586593.0ts = epoch.tsreplace(ts, hour=9, minute=30)# ts == 1449567033.0s = epoch.zulu(ts)# s == '2015-12-08T09:30:33.000Z'ts = epoch.tsreplace(ts, tz='Europe/Paris', hour=9, minute=30)# ts == 1449563433.0s = epoch.zulu(ts)# s == '2015-12-08T08:30:33.000Z'* ``epoch.dtreplace(dt[, *params])`` : datetimeA version of :meth:`datetime.datetime.replace()` that properlymaintains the `dt.tzinfo` if the replace will cause DST boundaryswitching.* ``epoch.ts2age(ts[, origin][, tz])`` : float## TODO: DOCUMENT## import pdb;pdb.set_trace()* ``epoch.age2ts(age[, origin][, tz])`` : float## TODO: DOCUMENT## import pdb;pdb.set_trace()Note that the `epoch` package, when working with `datetime` objects,always uses timezone-aware objects.