-
-
Save zed/92df922103ac9deb1a05 to your computer and use it in GitHub Desktop.
#!/usr/bin/env python | |
"""Get TAI-UTC difference in seconds for a given time using tzdata. | |
i.e., find the number of seconds that must be added to UTC to compute | |
TAI for any timestamp at or after the given time[1]. | |
>>> from datetime import datetime | |
>>> import leapseconds | |
>>> leapseconds.dTAI_UTC_from_utc(datetime(2005, 1, 1)) | |
datetime.timedelta(seconds=32) | |
>>> leapseconds.utc_to_tai(datetime(2015, 7, 1)) | |
datetime.datetime(2015, 7, 1, 0, 0, 36) | |
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 36)) | |
datetime.datetime(2015, 7, 1, 0, 0) | |
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 35)) # leap second | |
datetime.datetime(2015, 7, 1, 0, 0) | |
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 34)) | |
datetime.datetime(2015, 6, 30, 23, 59, 59) | |
Python 2.6+, Python 3, Jython, Pypy support. | |
[1]: https://github.com/eggert/tz/blob/master/leap-seconds.list | |
[2]: https://github.com/eggert/tz/blob/master/tzfile.h | |
[3]: https://github.com/eggert/tz/blob/master/zic.c | |
[4]: https://datacenter.iers.org/data/16/bulletinc-067.txt | |
""" | |
from __future__ import with_statement | |
from collections import namedtuple | |
from datetime import datetime, timedelta | |
from struct import Struct | |
from warnings import warn | |
__all__ = ['leapseconds', 'LeapSecond', | |
'dTAI_UTC_from_utc', 'dTAI_UTC_from_tai', | |
'tai_to_utc', 'utc_to_tai', | |
'gps_to_utc', 'utc_to_gps', | |
'tai_to_gps', 'gps_to_tai'] | |
__version__ = "0.3.0" | |
# from timezone/tzfile.h [2] (the file is in public domain) | |
""" | |
struct tzhead { | |
char tzh_magic[4]; /* TZ_MAGIC */ | |
char tzh_version[1]; /* '\0' or '2' or '3' as of 2013 */ | |
char tzh_reserved[15]; /* reserved--must be zero */ | |
char tzh_ttisgmtcnt[4]; /* coded number of trans. time flags */ | |
char tzh_ttisstdcnt[4]; /* coded number of trans. time flags */ | |
char tzh_leapcnt[4]; /* coded number of leap seconds */ | |
char tzh_timecnt[4]; /* coded number of transition times */ | |
char tzh_typecnt[4]; /* coded number of local time types */ | |
char tzh_charcnt[4]; /* coded number of abbr. chars */ | |
}; | |
# from zic.c[3] (the file is in public domain) | |
convert(const int_fast32_t val, char *const buf) | |
{ | |
register int i; | |
register int shift; | |
unsigned char *const b = (unsigned char *) buf; | |
for (i = 0, shift = 24; i < 4; ++i, shift -= 8) | |
b[i] = val >> shift; | |
} | |
# val = 0x12345678 | |
# (val >> 24) & 0xff, (val >> 16) & 0xff, (val >> 8) & 0xff, val & 0xff | |
# 0x12 0x34 0x56 0x78 | |
# therefore "coded number" means big-endian 32-bit integer | |
""" | |
dTAI_GPS = timedelta(seconds=19) # constant offset | |
NTP_EPOCH = datetime(1900, 1, 1) | |
LeapSecond = namedtuple('LeapSecond', 'utc dTAI_UTC') # tai = utc + dTAI_UTC | |
sentinel = LeapSecond(utc=datetime.max, dTAI_UTC=timedelta(0)) | |
def leapseconds( | |
tzfiles=[ | |
"/usr/share/zoneinfo/leap-seconds.list", | |
"/usr/share/zoneinfo/right/UTC", | |
"/usr/lib/zoneinfo/right/UTC", | |
], | |
use_fallback=False, | |
): | |
"""Extract leap seconds from *tzfiles*. | |
>>> leapseconds()[0] | |
LeapSecond(utc=datetime.datetime(1972, 1, 1, 0, 0), dTAI_UTC=datetime.timedelta(seconds=10)) | |
>>> leapseconds(tzfiles=["non-existent"])[27] | |
Traceback (most recent call last): | |
... | |
ValueError: Unable to open any tzfile: ['non-existent'] | |
>>> leapseconds(tzfiles=["non-existent"], use_fallback=True)[27] | |
LeapSecond(utc=datetime.datetime(2017, 1, 1, 0, 0), dTAI_UTC=datetime.timedelta(seconds=37)) | |
""" | |
for filename in tzfiles: | |
try: | |
file = open(filename, 'rb') | |
except IOError: | |
continue | |
else: | |
break | |
else: # no break | |
if not use_fallback: | |
raise ValueError('Unable to open any tzfile: %s' % (tzfiles,)) | |
else: | |
return _fallback() | |
with file: | |
header = Struct('>4s c 15x 6i') # see struct tzhead above | |
(magic, version, _, _, leapcnt, timecnt, typecnt, | |
charcnt) = header.unpack_from(file.read(header.size)) | |
if magic != "TZif".encode(): | |
# assume /usr/share/zoneinfo/leap-seconds.list like file | |
file.seek(0) # rewind | |
return leapseconds_from_listfile(file) | |
if version not in '\x0023'.encode(): | |
warn('Unsupported version %r in tzfile: %s' % ( | |
version, file.name), RuntimeWarning) | |
if leapcnt == 0: | |
raise ValueError("No leap seconds in tzfile: %s" % ( | |
file.name)) | |
"""# from tzfile.h[2] (the file is in public domain) | |
. . .header followed by. . . | |
tzh_timecnt (char [4])s coded transition times a la time(2) | |
tzh_timecnt (unsigned char)s types of local time starting at above | |
tzh_typecnt repetitions of | |
one (char [4]) coded UT offset in seconds | |
one (unsigned char) used to set tm_isdst | |
one (unsigned char) that's an abbreviation list index | |
tzh_charcnt (char)s '\0'-terminated zone abbreviations | |
tzh_leapcnt repetitions of | |
one (char [4]) coded leap second transition times | |
one (char [4]) total correction after above | |
""" | |
file.read(timecnt * 5 + typecnt * 6 + charcnt) # skip | |
result = [LeapSecond(datetime(1972, 1, 1), timedelta(seconds=10))] | |
nleap_seconds = 10 | |
tai_epoch_as_tai = datetime(1970, 1, 1, 0, 0, 10) | |
buf = Struct(">2i") | |
for _ in range(leapcnt): # read leap seconds | |
t, cnt = buf.unpack_from(file.read(buf.size)) | |
dTAI_UTC = nleap_seconds + cnt | |
utc = tai_epoch_as_tai + timedelta(seconds=t - dTAI_UTC + 1) | |
assert utc - datetime(utc.year, utc.month, utc.day) == timedelta(0) | |
result.append(LeapSecond(utc, timedelta(seconds=dTAI_UTC))) | |
result.append(sentinel) | |
return result | |
def leapseconds_from_listfile(file, comment="#".encode()): | |
"""Extract leap seconds from *file* | |
See /usr/share/zoneinfo/leap-seconds.list | |
""" | |
result = [] | |
for line in file: | |
if not line.startswith(comment): # skip comments | |
# ntp time, dtai, # day month year | |
ntp_time, dtai = line.partition(comment)[0].split() | |
utc = NTP_EPOCH + timedelta(seconds=int(ntp_time)) | |
result.append(LeapSecond(utc, timedelta(seconds=int(dtai)))) | |
result.append(sentinel) | |
return result | |
def _fallback(): | |
"""Leap seconds list if no tzfiles are available.""" | |
return [ | |
LeapSecond(utc=datetime(1972, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 10)), | |
LeapSecond(utc=datetime(1972, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 11)), | |
LeapSecond(utc=datetime(1973, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 12)), | |
LeapSecond(utc=datetime(1974, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 13)), | |
LeapSecond(utc=datetime(1975, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 14)), | |
LeapSecond(utc=datetime(1976, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 15)), | |
LeapSecond(utc=datetime(1977, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 16)), | |
LeapSecond(utc=datetime(1978, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 17)), | |
LeapSecond(utc=datetime(1979, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 18)), | |
LeapSecond(utc=datetime(1980, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 19)), | |
LeapSecond(utc=datetime(1981, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 20)), | |
LeapSecond(utc=datetime(1982, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 21)), | |
LeapSecond(utc=datetime(1983, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 22)), | |
LeapSecond(utc=datetime(1985, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 23)), | |
LeapSecond(utc=datetime(1988, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 24)), | |
LeapSecond(utc=datetime(1990, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 25)), | |
LeapSecond(utc=datetime(1991, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 26)), | |
LeapSecond(utc=datetime(1992, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 27)), | |
LeapSecond(utc=datetime(1993, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 28)), | |
LeapSecond(utc=datetime(1994, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 29)), | |
LeapSecond(utc=datetime(1996, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 30)), | |
LeapSecond(utc=datetime(1997, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 31)), | |
LeapSecond(utc=datetime(1999, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 32)), | |
LeapSecond(utc=datetime(2006, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 33)), | |
LeapSecond(utc=datetime(2009, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 34)), | |
LeapSecond(utc=datetime(2012, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 35)), | |
LeapSecond(utc=datetime(2015, 7, 1, 0, 0), dTAI_UTC=timedelta(0, 36)), | |
LeapSecond(utc=datetime(2017, 1, 1, 0, 0), dTAI_UTC=timedelta(0, 37)), | |
sentinel] | |
def dTAI_UTC_from_utc(utc_time): | |
"""TAI time = utc_time + dTAI_UTC_from_utc(utc_time).""" | |
return _dTAI_UTC(utc_time, lambda ls: ls.utc) | |
def dTAI_UTC_from_tai(tai_time): | |
"""UTC time = tai_time - dTAI_UTC_from_tai(tai_time).""" | |
return _dTAI_UTC(tai_time, lambda ls: ls.utc + ls.dTAI_UTC) | |
def _dTAI_UTC(time, leapsecond_to_time, leapseconds=leapseconds): | |
"""Get TAI-UTC difference in seconds for a given time. | |
>>> from datetime import datetime, timedelta | |
>>> _dTAI_UTC(datetime(1972, 1, 1), lambda ls: ls.utc) | |
datetime.timedelta(seconds=10) | |
>>> tai = lambda ls: ls.utc + ls.dTAI_UTC | |
>>> _dTAI_UTC(datetime(2015, 7, 1, 0, 0, 34), tai) | |
datetime.timedelta(seconds=35) | |
>>> _dTAI_UTC(datetime(2015, 7, 1, 0, 0, 35), tai) # leap second | |
datetime.timedelta(seconds=35) | |
>>> _dTAI_UTC(datetime(2015, 7, 1, 0, 0, 36), tai) | |
datetime.timedelta(seconds=36) | |
Bulletin C 67 says "NO leap second will be introduced at the end | |
of June 2024."[4] and therefore TAI-UTC is still 37s as of 10 June | |
2024: | |
>>> _dTAI_UTC(datetime(2024, 6, 10), lambda ls: ls.utc) | |
datetime.timedelta(seconds=37) | |
""" | |
leapseconds_list = leapseconds() | |
transition_times = list(map(leapsecond_to_time, leapseconds_list)) | |
if time < transition_times[0]: | |
raise ValueError("Dates before %s are not supported, got %r" % ( | |
transition_times[0], time)) | |
for i, (start, end) in enumerate(zip(transition_times, | |
transition_times[1:])): | |
if start <= time < end: | |
return leapseconds_list[i].dTAI_UTC | |
assert 0 | |
def tai_to_utc(tai_time): | |
"""Convert TAI time given as datetime object to UTC time.""" | |
return tai_time - dTAI_UTC_from_tai(tai_time) | |
def utc_to_tai(utc_time): | |
"""Convert UTC time given as datetime object to TAI time.""" | |
return utc_time + dTAI_UTC_from_utc(utc_time) | |
def gps_to_utc(gps_time): | |
"""Convert GPS time given as datetime object to UTC time.""" | |
return tai_to_utc(gps_to_tai(gps_time)) | |
def utc_to_gps(utc_time): | |
"""Convert UTC time given as datetime object to GPS time.""" | |
return tai_to_gps(utc_to_tai(utc_time)) | |
def tai_to_gps(tai_time): | |
"""Convert TAI time given as datetime object to GPS time.""" | |
return tai_time - dTAI_GPS | |
def gps_to_tai(gps_time): | |
"""Convert GPS time given as datetime object to TAI time.""" | |
return gps_time + dTAI_GPS | |
if __name__ == "__main__": | |
import sys | |
if "--test" in sys.argv: | |
import doctest | |
doctest.testmod() | |
import json | |
assert all(ls.dTAI_UTC == timedelta(seconds=ls.dTAI_UTC.seconds) | |
for ls in leapseconds()) # ~+200 leap second until 2100 | |
print(json.dumps([dict(utc=t.utc, tai=t.utc + t.dTAI_UTC, | |
dTAI_UTC=t.dTAI_UTC.seconds) | |
for t in leapseconds()], | |
default=str, indent=4, sort_keys=True)) |
GPS, TAI, UTC are different time scales Introducing local time zones would complicate the interface. It is unfortunate that stdlib may treat a naive datetime object as if it represents local time (sometimes, but not always). Naive datetime object may represent GPS, TAI, UTC time in the leapseconds
module and nothing else (simple). These times could be represented as timezones e.g., right/UTC
timezone is the TAI scale with 1970-01-01 00:00:10 (TAI) epoch but as experience with pytz
shows the usability of tzinfo objects with a non-fixed UTC offset is poor (it confuses people, bug-prone -- complicated).
Great job! gps_to_utc
works flawlessly!
Hi,
Nice. Could you make it a package with setup.py
?
Oh, use_fallback
isn't accessible from user function call arguments.
This no longer works for Ubuntu 24.04. I tried updating the tzfile to /usr/share/zoneinfo/UTC but it reports no leap seconds in the file. Luckily the fallback should work for some time.
@proximous tzdata package doesn't provide /usr/share/zoneinfo/right/UTC
on Ubuntu 24.04. I've added support for parsing /usr/share/zoneinfo/leap-seconds.list
instead.
@zed Awesome! Thanks!
Would it make sense to support timezone aware datetime objects, or at least return a timezone aware result for the gps_to_utc() function such that gps_to_utc().timestamp() is always correct rather than having to do gps_to_utc().replace(tzinfo=timezone.utc).timestamp()?
Or to put it another way, is there a benefit to not returning at UTC timezoned datetime for the *_to_utc() functions?