curryer.spicetime.leapsecond
============================

.. py:module:: curryer.spicetime.leapsecond

.. autoapi-nested-parse::

   Leapsecond kernel methods.

   Importing this module will load the default leapsecond kernel that is included
   with this library. If the kernel pool is cleared, `load()` should be called to
   reload the leapsecond kernel. The included kernel can be updated using
   `update_file()`; if a new kernel is available, it will be downloaded to the
   package's "data" directory.

   The last leapsecond kernel that is loaded takes the highest precedence.

   @author: Brandon Stone



Attributes
----------

.. autoapisummary::

   curryer.spicetime.leapsecond.logger
   curryer.spicetime.leapsecond._LEAPSECOND_FILE_PATH
   curryer.spicetime.leapsecond._LEAPSECOND_FILE_GLOB
   curryer.spicetime.leapsecond.LEAPSECOND_BASE_URL
   curryer.spicetime.leapsecond.LEAPSECOND_USER_FILE_PATH
   curryer.spicetime.leapsecond.cache


Classes
-------

.. autoapisummary::

   curryer.spicetime.leapsecond.LeapsecondCache


Functions
---------

.. autoapisummary::

   curryer.spicetime.leapsecond.find_default_file
   curryer.spicetime.leapsecond.are_loaded
   curryer.spicetime.leapsecond.load
   curryer.spicetime.leapsecond.check_for_update
   curryer.spicetime.leapsecond.update_file
   curryer.spicetime.leapsecond.read_leapseconds


Module Contents
---------------

.. py:data:: logger

.. py:data:: _LEAPSECOND_FILE_PATH
   :value: '../../data/generic'


.. py:data:: _LEAPSECOND_FILE_GLOB
   :value: 'naif*.tls'


.. py:data:: LEAPSECOND_BASE_URL
   :value: 'https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/'


.. py:data:: LEAPSECOND_USER_FILE_PATH
   :value: None


.. py:function:: find_default_file()

   Find the library's default leapsecond kernel file.

   :returns: Path object for the default leapsecond kernel.
   :rtype: pathlib.Path


.. py:function:: are_loaded()

   List the loaded leapsecond kernels (LSK), if any.

   :returns: List of the loaded leapsecond kernels. The last file has precedence.
   :rtype: list of str


.. py:function:: load(filename=None)

   Load a leapsecond kernel.

   :param filename: Leapsecond kernel to load. If omitted, attempt to load the included
                    kernel. Do not reload it if it has already been loaded.
   :type filename: str or pathlib.Path, optional

   :rtype: None


.. py:function:: check_for_update()

   Check for updated leapsecond kernels from NAIF.

   This should be run at least twice a year.

   :returns: If an update is available, returns the file name of the latest
             leapsecond kernel (e.g., "naif0012.tls"), otherwise None.
   :rtype: str or None


.. py:function:: update_file()

   Update the leapsecond kernel from NAIF.

   :returns: Path to the updated leapsecond file, or None if the current leapsecond
             file was already up-to-date. Note: If an update was found, then the
             module constant `LEAPSECOND_FILE` will be updated and the kernel will
             be loaded into memory (overriding any existing leapsecond kernels).
   :rtype: pathlib.Path or None


.. py:function:: read_leapseconds(filename=None)

   Determine the current leapseconds.

   :param filename: Leapsecond file to read. Default=library leapsecond file.
   :type filename: str, optional

   :returns:

             Leapsecond data. Index is the time a leapsecond was added. Columns:
                 nsec : int, cumulative number of leapseconds
                 linux_offset : int, microsecond offset between unix time and uGPS.
                 ugps : int, GPS microsecond time a leapsecond was added.
   :rtype: pd.DataFrame


.. py:class:: LeapsecondCache

   Simply class for storing leapsecond data in-memory.


   .. py:attribute:: _data
      :value: None



   .. py:method:: get()

      Get the leapsecond information.

      The first call will trigger a read, otherwise a cached copy is used.

      :returns: Leapsecond data. See method: `read_leapseconds`
      :rtype: pandas.DataFrame



.. py:data:: cache