LeapSeconds#

class astropy.utils.iers.LeapSeconds(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)[source]#

Bases: QTable

Leap seconds class, holding TAI-UTC differences.

The table should hold columns ‘year’, ‘month’, ‘tai_utc’.

Methods are provided to initialize the table from IERS Leap_Second.dat, IETF/ntp leap-seconds.list, or built-in ERFA/SOFA, and to update the list used by ERFA.

Notes

Astropy has a built-in iers.IERS_LEAP_SECONDS_FILE. Up to date versions can be downloaded from iers.IERS_LEAP_SECONDS_URL or iers.LEAP_SECONDS_LIST_URL. Many systems also store a version of leap-seconds.list for use with ntp (e.g., on Debian/Ubuntu systems, /usr/share/zoneinfo/leap-seconds.list).

To prevent querying internet resources if the available local leap second file(s) are out of date, set iers.conf.auto_download = False. This must be done prior to performing any Time scale transformations related to UTC (e.g. converting from UTC to TAI).

Attributes Summary

expires

The limit of validity of the table.

Methods Summary

`auto_open`([files])	Attempt to get an up-to-date leap-second list.
`from_erfa`([built_in])	Create table from the leap-second list in ERFA.
`from_iers_leap_seconds`([file])	Create a table from a file like the IERS `Leap_Second.dat`.
`from_leap_seconds_list`(file)	Create a table from a file like the IETF `leap-seconds.list`.
`open`([file, cache])	Open a leap-second list.
`update_erfa_leap_seconds`([initialize_erfa])	Add any leap seconds not already present to the ERFA table.

Attributes Documentation

expires#: The limit of validity of the table.

Methods Documentation

classmethod auto_open(files=None)[source]#

Attempt to get an up-to-date leap-second list.

The routine will try the files in sequence until it finds one whose expiration date is “good enough” (see below). If none are good enough, it returns the one with the most recent expiration date, warning if that file is expired.

For remote files that are cached already, the cached file is tried first before attempting to retrieve it again.

Parameters:

fileslist of path-like object, optional: List of files/URLs to attempt to open. By default, uses cls._auto_open_files.

Returns:

leap_secondsLeapSeconds: Up to date leap-second table

Notes

Bulletin C is released about 10 days after a possible leap second is introduced, i.e., mid-January or mid-July. Expiration days are thus generally at least 150 days after the present. We look for a file that expires more than 180 - auto_max_age after the present.

classmethod from_erfa(built_in=False)[source]#

Create table from the leap-second list in ERFA.

Parameters:

built_inbool: If False (default), retrieve the list currently used by ERFA, which may have been updated. If True, retrieve the list shipped with erfa.

classmethod from_iers_leap_seconds(file='/home/docs/checkouts/readthedocs.org/user_builds/astropy/conda/latest/lib/python3.11/site-packages/astropy_iers_data/data/Leap_Second.dat')[source]#

Create a table from a file like the IERS Leap_Second.dat.

Parameters:

filepath-like object, optional: Full local or network path to the file holding leap-second data in a format consistent with that used by IERS. By default, uses iers.IERS_LEAP_SECOND_FILE.

Notes

The file must contain the expiration date in a comment line, like ‘# File expires on 28 June 2020’

classmethod from_leap_seconds_list(file)[source]#

Create a table from a file like the IETF leap-seconds.list.

Parameters:

filepath-like object, optional: Full local or network path to the file holding leap-second data in a format consistent with that used by IETF. Up to date versions can be retrieved from iers.IETF_LEAP_SECOND_URL.

Notes

The file must contain the expiration date in a comment line, like ‘# File expires on: 28 June 2020’

classmethod open(file=None, cache=False)[source]#

Open a leap-second list.

Parameters:

filepath-like object or None: Full local or network path to the file holding leap-second data, for passing on to the various from_ class methods. If ‘erfa’, return the data used by the ERFA library. If None, use default locations from file and configuration to find a table that is not expired.
cachebool: Whether to use cache. Defaults to False, since leap-second files are regularly updated.

Returns:

leap_secondsLeapSeconds: Table with ‘year’, ‘month’, and ‘tai_utc’ columns, plus possibly others.

Notes

Bulletin C is released about 10 days after a possible leap second is introduced, i.e., mid-January or mid-July. Expiration days are thus generally at least 150 days after the present. For the auto-loading, a list comprised of the table shipped with astropy, and files and URLs in Conf are tried, returning the first that is sufficiently new, or the newest among them all.

update_erfa_leap_seconds(initialize_erfa=False)[source]#

Add any leap seconds not already present to the ERFA table.

This method matches leap seconds with those present in the ERFA table, and extends the latter as necessary.

Parameters:

initialize_erfabool, or ‘only’, or ‘empty’: Initialize the ERFA leap second table to its built-in value before trying to expand it. This is generally not needed but can help in case it somehow got corrupted. If equal to ‘only’, the ERFA table is reinitialized and no attempt it made to update it. If ‘empty’, the leap second table is emptied before updating, i.e., it is overwritten altogether (note that this may break things in surprising ways, as most leap second tables do not include pre-1970 pseudo leap-seconds; you were warned).

Returns:

n_updateint: Number of items updated.

Raises:

ValueError: If the leap seconds in the table are not on 1st of January or July, or if the matches are inconsistent. This would normally suggest a corrupted leap second table, but might also indicate that the ERFA table was corrupted. If needed, the ERFA table can be reset by calling this method with an appropriate value for initialize_erfa.