hermpy.net.client_messenger
===========================

.. py:module:: hermpy.net.client_messenger


Classes
-------

.. autoapisummary::

   hermpy.net.client_messenger.ClientMESSENGER


Functions
---------

.. autoapisummary::

   hermpy.net.client_messenger._get_subdir
   hermpy.net.client_messenger._get_timerange_doys


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

.. py:class:: ClientMESSENGER(_PDS_BASE_URL: str = 'https://pds-ppi.igpp.ucla.edu/data/', _PDS_DATA_LOCATION: dict[str, Any] = {'MAG': 'mess-mag-calibrated/data/mso/', 'MAG 1s': 'mess-mag-calibrated/data/mso-avg/', 'MAG 5s': 'mess-mag-calibrated/data/mso-avg/', 'MAG 10s': 'mess-mag-calibrated/data/mso-avg/', 'MAG 60s': 'mess-mag-calibrated/data/mso-avg/', 'MAG RTN 60s': 'mess-mag-calibrated/data/rtn-avg/', 'FIPS': 'mess-epps-fips-calibrated/data/scan/'}, _FILE_PATTERN: dict[str, str] = {'MAG': '{{year:4d}}/{subdir}/MAGMSOSCI{{year:2d}}{{day_of_year:3d}}_V{{version}}.TAB', 'MAG 1s': '{{year:4d}}/{subdir}/MAGMSOSCIAVG{{year:2d}}{{day_of_year:3d}}_01_V{{version}}.TAB', 'MAG 5s': '{{year:4d}}/{subdir}/MAGMSOSCIAVG{{year:2d}}{{day_of_year:3d}}_05_V{{version}}.TAB', 'MAG 10s': '{{year:4d}}/{subdir}/MAGMSOSCIAVG{{year:2d}}{{day_of_year:3d}}_10_V{{version}}.TAB', 'MAG 60s': '{{year:4d}}/{subdir}/MAGMSOSCIAVG{{year:2d}}{{day_of_year:3d}}_60_V{{version}}.TAB', 'MAG RTN 60s': '{{year:4d}}/{subdir}/MAGRTNSCIAVG{{year:2d}}{{day_of_year:3d}}_60_V{{version}}.TAB', 'FIPS': '{{year:4d}}/{subdir}/FIPS_R{{year:4d}}{{day_of_year:3d}}CDR_V{{version}}.TAB'})

   Client for querying and downloading MESSENGER spacecraft data from the
   NASA Planetary Data System (PDS).

   Supports multiple instruments and data products, including magnetometer
   (MAG) data at various cadences and the Fast Imaging Plasma Spectrometer
   (FIPS). Data is retrieved from the PDS Planetary Plasma Interactions
   Node and downloaded locally on request.

   :param PDS_BASE_URL: Base URL for the PDS data server.
   :param PDS_DATA_LOCATION: Mapping from instrument name to its path
       relative to ``PDS_BASE_URL``. Supported keys include ``"MAG"``,
       ``"MAG 1s"``, ``"MAG 5s"``, ``"MAG 10s"``, ``"MAG 60s"``,
       ``"MAG RTN 60s"``, and ``"FIPS"``.
   :param FILE_PATTERN: Mapping from instrument name to the filename
       pattern used by :class:`sunpy.net.Scraper` to resolve individual
       files. Patterns may contain ``{subdir}``, ``{year}``,
       ``{day_of_year}``, and ``{version}`` placeholders.

   Example usage::

       from sunpy.time import TimeRange
       client = ClientMESSENGER()
       time_range = TimeRange("2012-01-01", "2012-01-02")
       urls = client.query(time_range, "MAG 1s")
       files = client.fetch()


   .. py:attribute:: PDS_BASE_URL
      :value: 'https://pds-ppi.igpp.ucla.edu/data/'



   .. py:attribute:: PDS_DATA_LOCATION


   .. py:attribute:: FILE_PATTERN


   .. py:attribute:: _query_buffer
      :type:  list[str]
      :value: []



   .. py:property:: instruments
      :type: list[str]


      The instrument names supported by this client.

      Derived from the keys of ``PDS_DATA_LOCATION``.



   .. py:method:: query(time_range: sunpy.time.TimeRange, instrument: str) -> list[str]

      Query the PDS for available files for a given instrument and time range.

      Resolves the appropriate monthly subdirectory structure, uses
      :class:`sunpy.net.Scraper` to build candidate URLs, and filters
      the results to only those matching the day-of-year values spanned
      by ``time_range``. Matched URLs are appended to the internal query
      buffer, making them available to :meth:`fetch`.

      :param time_range: The time range over which to search for data.
      :param instrument: The instrument to query. Must be one of the keys
          in :attr:`instruments`.
      :raises KeyError: If ``instrument`` is not a recognised key.



   .. py:method:: fetch() -> list[pathlib.Path]

      Download all files currently held in the query buffer.

      Files that have already been downloaded locally are retrieved from
      disk rather than re-downloaded. Clears the query buffer after
      completion, so subsequent calls to :meth:`fetch` without an
      intervening :meth:`query` will return an empty list.



.. py:function:: _get_subdir(time_range: sunpy.time.TimeRange) -> str | list[str]

   Determine the MAG subdirectories required for a given time range.


.. py:function:: _get_timerange_doys(time_range: sunpy.time.TimeRange) -> list[int]

   For a given TimeRange return the day-of-years it spans. Can result in a
   list of length one, this is wanted behaviour.