Skip to main content
`Ctrl`+`K`

# 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)

  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)

    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:
      files `python:list` of python:path-like object, optional

        List of files/URLs to attempt to open. By default, uses `cls._auto_open_files`.

    Returns:
      leap_seconds `LeapSeconds`

        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)

    Create table from the leap-second list in ERFA.

    Parameters:
      built_in bool

        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='/usr/lib/python3/dist-packages/astropy_iers_data/data/Leap_Second.dat')

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

    Parameters:
      file python:path-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)

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

    Parameters:
      file python:path-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)

    Open a leap-second list.

    Parameters:
      file python:path-like object or `python: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.

      cache bool

        Whether to use cache. Defaults to False, since leap-second files are regularly updated.

    Returns:
      leap_seconds `LeapSeconds`

        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)

    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_erfa bool, 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_update `python:int`

        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`.