Add store_tools/basestore.py

modules/store_tools/basestore.py

+""" basestore.py
+
+"""
+import requests
+
+from .exception import CdsException
+from requests.adapters import HTTPAdapter
+
+MSG_HTTP_DECODE = "Fail to decode HTTP response"
+MSG_HTTP_ERROR = "HTTP Error"
+MSG_INVALID_RESPONSE = "Invalid response"
+MSG_NO_IDS = "Invalid list of record identifiers"
+MSG_NOT_IMPLEMENTED = "Method not implemented"
+
+
+class BaseStore(object):
+    """Base class defining the interface to a publication store.
+
+    Args:
+        host (str):
+            for example ``cds.cern.ch`` or ``inspirehep.net``
+
+        api_search (str):
+            template URL to search publication, *e.g.*
+            "https://inspirehep.net/api/literature/?q="
+
+        api_record (str):
+            template URL to retrieve a publication, *e.g.*
+            "https://inspirehep.net/api/literature
+
+        max_retries (int):
+            HTTP requests are performed several time in case of failure.
+            Define the maximum number of trial
+
+        shelf (str):
+            section of the store containing records, *e.g.*
+            ``None``, ``literature``, ``conferences`` and ``institutions``
+
+    """
+
+    def __init__(self,
+                 api_record=None,
+                 api_search=None,
+                 host=None,
+                 max_retries=3,
+                 shelf=None):
+
+        self._api_search = api_search
+        self._api_record = api_record
+        self._host = host
+        self._shelf = shelf
+        self._url = None
+
+        # start a session, a persistent connection with the server
+        # let the session handle the number of retry
+        session = requests.Session()
+        session.mount(f"https://{host}", HTTPAdapter(max_retries=max_retries))
+        self._session = session
+
+    def __del__(self):
+        # close the session
+        if getattr(self, "_session", None) is not None:
+            self._session.close()
+
+    def get_field(self, rec_id, *args):
+        """Retrieve the field value for the record identified by
+        its *record id*.
+
+        Args:
+            rec_id (int):
+                record identifier in the store.
+
+            args (list):
+                list of fields to be return in the JSON record.
+
+        Returns:
+            * value for a single field
+            * dict for a list of fields
+            * None when the field is not found
+
+        Raises:
+            CdsException:
+                * the server return an HTTP error.
+                * JSON object could not be decoded.
+
+        """
+        raise CdsException(MSG_NOT_IMPLEMENTED)
+
+    def get_ids(self, **kwargs):
+        """Return a list of *record id* matching search criteria.
+
+        Keyword Args:
+            define the search criteria
+
+        Returns:
+            list:
+                * A list of numbers.
+                * The list is empty when the request failed on the server.
+
+        Raises:
+            CdsException::
+                * the server return an HTTP error;
+                * JSON object can't be decoded;
+                * not well formed list of ids.
+
+        """
+        raise CdsException(MSG_NOT_IMPLEMENTED)
+
+    def get_record(self, rec_id):
+        """Retrieve a record defined by its *record id*.
+
+        Args:
+            rec_id (int):
+                record identifier in the store.
+
+        Returns:
+            dict:
+                the record data (recjson).
+
+        Raises:
+            CdsException:
+                * the server return an HTTP error.
+                * JSON object could not be decoded.
+                * more than one record
+
+        """
+        raise CdsException(MSG_NOT_IMPLEMENTED)
+
+    def interrogate(self, url, timeout=10, **kwargs):
+        """Interrogate the store using the *URL*.
+        It is retry several time when the service is not available.
+
+        Args:
+            url (str):
+                the URL string depends on the store
+
+            timeout (float):
+                timeout for the HTTP request
+
+        Keyword Args:
+            additional parameters append to the URL
+
+        Returns:
+            requests.Response:
+
+        Raises:
+            RequestException:
+                something went wrong within the HTTP dialog
+
+        """
+        self._url = url
+
+        r = self._session.get(url, timeout=timeout, params=kwargs)
+        r.raise_for_status()
+
+        return r
+
+    def last_search_url(self):
+        return self._url
+
+    def search(self, query, **kwargs):
+        """Return a list of *JSON record* matching search criteria.
+
+        Args:
+            query (str):
+                query for the store.
+
+        Keyword Args:
+            additional parameters append to the URL
+
+        Returns:
+            * list of JSON records
+
+        Raises:
+            CdsException:
+                * the server return an HTTP error.
+                * JSON object could not be decoded.
+
+        """
+        raise CdsException(MSG_NOT_IMPLEMENTED)