leapseconddata – main namespace for the project

For example, to retrieve the UTC-TAI offset on January 1, 2011:

>>> import datetime
>>> import leapseconddata
>>> ls = leapseconddata.LeapSecondData.from_standard_source()
>>> when = datetime.datetime(2011, 1, 1, tzinfo=datetime.timezone.utc)
>>> ls.tai_offset(when).total_seconds()
34.0

class leapseconddata.LeapSecondInfo

Bases: object

Information about a particular leap second

start: datetime

The UTC timestamp just after the insertion of the leap second.

The leap second is actually the 61th second of the previous minute (xx:xx:60)

tai_offset: timedelta

The new TAI-UTC offset. Positive numbers indicate that TAI is ahead of UTC

exception leapseconddata.ValidityError

Bases: ValueError

The leap second information is not valid for the given timestamp

exception leapseconddata.InvalidHashError

Bases: ValueError

The file hash could not be verified

exception leapseconddata.InvalidContentError

Bases: ValueError

A line in the file was not valid

leapseconddata.datetime_is_tai(when)

Return true if the datetime is in the TAI timescale

Parameters:

when (datetime)

Return type:

bool

class leapseconddata.LeapSecondData

Bases: object

Represent the list of known and scheduled leapseconds

Parameters:

• leap_seconds (List[LeapSecondInfo]) – A list of leap seconds

• valid_until (Optional[datetime.datetime]) – The expiration of the data

• updated (Optional[datetime.datetime]) – The last update time of the data

standard_file_sources: ClassVar[list[str]] = ['file:///usr/share/zoneinfo/leap-seconds.list', 'file:///var/db/ntpd.leap-seconds.list']

When using LeapSecondData.from_standard_source, these local sources are checked first.

Locations for Debian Linux & FreeBSD are supported.

standard_network_sources: ClassVar[list[str]] = ['https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list', 'https://data.iana.org/time-zones/tzdb/leap-seconds.list', 'https://raw.githubusercontent.com/eggert/tz/main/leap-seconds.list', 'ftp://ftp.boulder.nist.gov/pub/time/leap-seconds.list', 'https://www.meinberg.de/download/ntp/leap-seconds.list']

When using LeapSecondData.from_standard_source, these network sources are checked second.

Remote sources are checked in the following order until a suitable file is found:

• The International Earth Rotation Service (IERS) is the international body charged with various duties including scheduling leap seconds.

• The Internet Assigned Numbers Authority (IANA) publishes the IANA timezone database, used by many major operating sytsems for handling the world’s time zones. As part of this activity they publish a version of the leap second list.

• eggert/tz is the canonical github home of the IANA timezone database, and updated versions of the leap second list can appear here before they are part of an official IANA timezone database release.

• The National Institute of Standards and Technology (NIST)’s Time Realization and Distribution Group is a US federal organization that publishes a version of the leap second database.

• Meinberg Funkuhren GmbH & Co. KG is a Germany-based company that published a helpful article in its knowledge base including URLs of sites that disseminate the leap second list. They state that the version they distribute is frequently more up to date than other sources, including IANA, NIST, and tzdb.

leap_seconds: list[LeapSecondInfo]

All known and scheduled leap seconds

valid_until: datetime | None = None

The list is valid until this UTC time

last_updated: datetime | None = None

The last time the list was updated to add a new upcoming leap second

valid(when=None)

Return True if the data is valid at given datetime

If when is none, the validity for the current moment is checked.

Parameters:

when (datetime | None) – Moment to check for validity

Return type:

bool

tai_offset(when, *, check_validity=True)

For a given datetime, return the TAI-UTC offset

Parameters:

• when (datetime) – Moment in time to find offset for

• check_validity (bool) – Check whether the database is valid for the given moment

Return type:

timedelta

For times before the first leap second, a zero offset is returned. For times after the end of the file’s validity, an exception is raised unless check_validity=False is passed. In this case, it will return the offset of the last list entry.

to_tai(when, *, check_validity=True)

Convert the given datetime object to TAI.

A TAI timestamp is returned unchanged.

A naive timestamp is assumed to be UTC. This behavior is deprecated, and a future release will raise an exception when when is naive.

Parameters:

• when (datetime) – Moment in time to convert.

• check_validity (bool) – Check whether the database is valid for the given moment

Return type:

datetime

tai_to_utc(when, *, check_validity=True)

Convert the given datetime object to UTC

For a leap second, the fold property of the returned time is True.

A naive timestamp is assumed to be TAI. This behavior is deprecated, and a future release will raise an exception when when is naive.

Parameters:

• when (datetime) – Moment in time to convert. Its tzinfo must be tai.

• check_validity (bool) – Check whether the database is valid for the given moment

Return type:

datetime

is_leap_second(when, *, check_validity=True)

Return True if the given timestamp is the leap second.

A naive timestamp is assumed to be UTC. This behavior is deprecated, and a future release will raise an exception when when is naive.

Parameters:

• when (datetime) – Moment in time to check.

• check_validity (bool) – Check whether the database is valid for the given moment

Return type:

bool

For a TAI timestamp, it returns True for the leap second (the one that would be shown as :60 in UTC). For a UTC timestamp, it returns True for the :59 second if fold, since the :60 second cannot be represented.

classmethod from_standard_source(when=None, *, check_hash=True, custom_sources=(), timeout=60)

Get the list of leap seconds from a standard source.

Parameters:

• when (datetime.datetime | None) – Check that the data is valid for this moment

• check_hash (bool) – Whether to check the embedded hash

• custom_sources (Sequence[str])

• timeout (float | None)

Return type:

LeapSecondData

Using a list of standard sources, including network sources, find a leap-second.list data valid for the given timestamp, or the current time (if unspecified)

If custom_sources is specified, this list of URLs is checked before the hard-coded sources.

classmethod from_file(filename='/usr/share/zoneinfo/leap-seconds.list', *, check_hash=True)

Retrieve the leap second list from a local file.

Parameters:

• filename (str) – Local filename to read leap second data from. The default is the standard location for the file on Debian systems.

• check_hash (bool) – Whether to check the embedded hash

Return type:

LeapSecondData

classmethod from_url(url, *, check_hash=True, timeout=60)

Retrieve the leap second list from a local file

Parameters:

• filename – URL to read leap second data from

• check_hash (bool) – Whether to check the embedded hash

• url (str)

• timeout (float | None)

Return type:

LeapSecondData | None

classmethod from_data(data, *, check_hash=True)

Retrieve the leap second list from local data

Parameters:

• data (bytes | str) – Data to parse as a leap second list

• check_hash (bool) – Whether to check the embedded hash

Return type:

LeapSecondData

classmethod from_open_file(open_file, *, check_hash=True)

Retrieve the leap second list from an open file-like object

Parameters:

• open_file (BinaryIO) – Binary IO object containing the leap second list

• check_hash (bool) – Whether to check the embedded hash

Return type:

LeapSecondData