curryer.tle
===========

.. py:module:: curryer.tle

.. autoapi-nested-parse::

   TLE related logic.

   @author: Brandon Stone



Attributes
----------

.. autoapisummary::

   curryer.tle.logger


Classes
-------

.. autoapisummary::

   curryer.tle.TLERemoteAccessor


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

.. py:data:: logger

.. py:class:: TLERemoteAccessor(user, pswd, keep_duplicates=False)

   Access TLE data from SpaceTrack.org.


   .. py:attribute:: URL_BASE
      :value: 'https://www.space-track.org'



   .. py:attribute:: URL_AUTH
      :value: 'https://www.space-track.org/ajaxauth/login'



   .. py:attribute:: MAIN_COLUMNS
      :value: ('object_name', 'norad_cat_id', 'epoch', 'creation_date', 'file', 'tle_line1', 'tle_line2')



   .. py:attribute:: __prev_request_time
      :value: 0



   .. py:attribute:: __spacetrack_user


   .. py:attribute:: __spacetrack_pswd


   .. py:attribute:: keep_duplicates
      :value: False



   .. py:attribute:: __cookies
      :value: None



   .. py:method:: limiter()

      Check API limits and sleep if necessary.

      Must self limit API requests or risk server-side errors (to limit).
      Limits: 30 per minute, 300 per hour.

      :returns: Number of seconds that it paused for (0=not API limited).
      :rtype: float



   .. py:method:: authenticate()

      Authenticate, storing cookie for later queries.



   .. py:method:: is_authenticated()

      Check if queries are authenticated.



   .. py:method:: _as_str(value)
      :staticmethod:


      Convert misc. data types to a string.



   .. py:method:: render_query(norad_cat_id, columns=None, query_args=None)

      Render a query string.

      :param norad_cat_id: NORAD catalog ID.
      :type norad_cat_id: int
      :param columns: Columns to request. Default is `MAIN_COLUMNS`.
      :type columns: list[str], optional
      :param query_args: List of query arguments (field, comparison, value). Default is
                         to get latest TLE entry.
      :type query_args: list[tuple[str, str, any]], optional

      :returns: URL to query data from.
      :rtype: str



   .. py:method:: query(query_url)

      Query for TLE data using a pre-rendered URL.

      :param query_url: URL to query data from. Expected to be generated using
                        `render_query`, otherwise it set JSON and metadata args.
      :type query_url: str

      :returns:

                Dictionary response. If empty, the dict will be:
                    `{'request_metadata': {'ReturnedRows': 0}, 'data': []}`
      :rtype: dict



   .. py:method:: read(norad_cat_id, columns=None, query_args=None, index_col=None)

      Get TLE data and format it into a table.

      :param norad_cat_id: NORAD catalog ID.
      :type norad_cat_id: int
      :param columns: Columns to request. Default is `MAIN_COLUMNS`.
      :type columns: list[str], optional
      :param query_args: List of query arguments (field, comparison, value). Default is
                         to get the latest TLE entry.
      :type query_args: list[tuple], optional
      :param index_col: Column to set as the table's index.
      :type index_col: str, optional

      :returns: Table of data. Will always contain the columns, even if no data
                was returned.
      :rtype: pd.DataFrame



   .. py:method:: write(tle_table, filename, overwrite=False, append=False, header=True)
      :staticmethod:


      Write TLE data to a file.

      :param tle_table: TLE data in table form. Must contain the columns "tle_line1" and
                        "tle_line2". An empty table will cause a warning log.
      :type tle_table: pd.DataFrame
      :param filename: File path to write to or function to send the text. If None,
                       returns the text.
      :type filename: str or Path or func, optional
      :param overwrite: Option to overwrite an existing file. Can not use with `append`.
      :type overwrite: bool, optional
      :param append: Option to append to an existing file. It will create a new file if
                     one does not already exist. Can not use with `overwrite`.
      :type append: bool, optional
      :param header: Option to include a header in the file as the `table` name.
      :type header: bool, optional

      :returns: TLE file text if `filename` was None, otherwise None is returned.
      :rtype: str or None