epicsarchiver.retrieval.client.archiver_retrieval
=================================================

.. py:module:: epicsarchiver.retrieval.client.archiver_retrieval

.. autoapi-nested-parse::

   Archiver Retrieval methods.



Attributes
----------

.. autoapisummary::

   epicsarchiver.retrieval.client.archiver_retrieval.LOG
   epicsarchiver.retrieval.client.archiver_retrieval.ENDPOINT_GET_DATA
   epicsarchiver.retrieval.client.archiver_retrieval.ENDPOINT_GET_MATCHING_PVS


Classes
-------

.. autoapisummary::

   epicsarchiver.retrieval.client.archiver_retrieval.ArchiverRetrieval


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

.. py:data:: LOG
   :type:  logging.Logger

.. py:data:: ENDPOINT_GET_DATA
   :value: '/data/getData.raw'


.. py:data:: ENDPOINT_GET_MATCHING_PVS
   :value: '/bpl/getMatchingPVs'


.. py:class:: ArchiverRetrieval(hostname: str = 'localhost', port: int = DEFAULT_RETRIEVAL_PORT)

   Bases: :py:obj:`epicsarchiver.common.base_archiver.BaseArchiverAppliance`


   Retrieval EPICS Archiver Appliance client.

   Hold a session to the Retrieval Archiver Appliance web application.

   :param hostname: EPICS Archiver Appliance hostname
   :param port: EPICS Archiver Appliance retrieval port

   Examples:

   .. code-block:: python

       from epicsarchiver.archiver.retrieval import ArchiverRetrieval

       archappl = ArchiverRetrieval("archiver-01.tn.esss.lu.se")
       print(archappl.version)
       df = archappl.get_data("my:pv", start="2018-07-04 13:00", end=datetime.utcnow())


   .. py:attribute:: _base_url
      :value: 'http://localhost:17668/retrieval'



   .. py:attribute:: data_url
      :type:  str
      :value: 'http://localhost:17668/retrieval/data/getData.raw'



   .. py:attribute:: matching_pvs_url
      :type:  str
      :value: 'http://localhost:17668/retrieval/bpl/getMatchingPVs'



   .. py:method:: get_data_raw(pv: str, start: datetime.datetime, end: datetime.datetime) -> requests.Response

      Retrieve archived data.

      :param pv: name of the pv.
      :param start: start time. Can be a string or `datetime.datetime`
                    object.
      :param end: end time. Can be a string or `datetime.datetime`
                  object.

      :returns: `Response`



   .. py:method:: _get_matching_pvs(query: str, limit: int) -> list[str]

      Retrieve list of matching pv names for given regex search string.

      :param query: A regex search string.
      :type query: str
      :param limit: Limit of PV names to return.
      :type limit: int

      :returns: List of pv names
      :rtype: list[str]



   .. py:method:: _check_for_pvs_in_time_range(query: list[str], start: datetime.datetime | None = None, end: datetime.datetime | None = None) -> list[str]

      Check if data recorded during the given time range for each PV in list.

      If both start and end given, return only PVs which recorded data during that
      time range.

      If start given and end not, return PVs which recorded data between start and
      now.

      If end given and start not, return PVs which recorded any data before end.

      :param query: List of pvs.
      :type query: list[str]
      :param start: Start of the time range.
      :type start: datetime.datetime | None
      :param end: End of the time range.
      :type end: datetime.datetime | None

      :returns: List of PV names found.
      :rtype: list[str]



   .. py:method:: get_events(pv: str, start: datetime.datetime, end: datetime.datetime, processor: epicsarchiver.retrieval.client.processor.Processor | None = None) -> epicsarchiver.retrieval.archive_event.ArchiveEventsData

      Retrieve archived data.

      :param pv: name of the pv.
      :param start: start time. Can be a string or `datetime.datetime`
                    object.
      :param end: end time. Can be a string or `datetime.datetime`
                  object.
      :param processor: Preprocessor
                        to use. Defaults to None.
      :type processor: Processor | None, optional

      :returns: tuple of (metadata, events).
      :rtype: ArchiveEventsData



   .. py:method:: get_data(pv: str, start: str | datetime.datetime, end: str | datetime.datetime, processor: epicsarchiver.retrieval.client.processor.Processor | None = None) -> polars.DataFrame

      Retrieve archived data.

      :param pv: name of the pv.
      :param start: start time. Can be a string or `datetime.datetime`
                    object.
      :param end: end time. Can be a string or `datetime.datetime`
                  object.
      :param processor: Preprocessor
                        to use. Defaults to None.
      :type processor: Processor | None, optional

      :returns: `polars.DataFrame`

      :raises ImportError: If the polars extra is not installed.



   .. py:method:: search(query: str, *, start: datetime.datetime | None = None, end: datetime.datetime | None = None, limit: int = 500) -> list[str]

      Search for names of PVs matching the given regex search string.

      Optionally specify start and/or end times to only return PVs that recorded data
      in the specified time range.

      :param query: A regex search string.
      :type query: str
      :param start: Start time of the time period.
      :type start: datetime.datetime | None
      :param end: End time of the time period.
      :type end: datetime.datetime | None
      :param limit: Limit of PV names to return for each search string given.
                    To get all the PV names, (potentially in the millions), set limit to -1.
                    [default: 500]
      :type limit: int

      :returns: List of PV names found.
      :rtype: list[str]