heurist-api 0.1.2__py3-none-any.whl

heurist/__init__.py

@@ -0,0 +1 @@
+PACKAGE_NAME = "heurist-api"

heurist/api/client.py

@@ -0,0 +1,122 @@
+"""Heurist API client"""
+
+import json
+from typing import ByteString, Literal
+
+import requests
+from heurist.api.constants import MAX_RETRY, READTIMEOUT
+from heurist.api.exceptions import APIException, ReadTimeout
+from heurist.api.url_builder import URLBuilder
+from heurist.api.utils import log_attempt_number
+from tenacity import (
+    RetryError,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+)
+
+
+class HeuristAPIClient:
+    """
+    Client for Heurist API.
+    """
+
+    def __init__(
+        self,
+        database_name: str,
+        session: requests.Session,
+        timeout_seconds: int | None = READTIMEOUT,
+    ) -> None:
+        self.database_name = database_name
+        self.url_builder = URLBuilder(database_name=database_name)
+        self.session = session
+        self.timeout = timeout_seconds
+
+    @retry(
+        retry=retry_if_exception_type(requests.exceptions.ReadTimeout),
+        stop=stop_after_attempt(MAX_RETRY),
+        after=log_attempt_number,
+    )
+    def call_heurist_api(self, url: str) -> ByteString | None:
+        response = self.session.get(url, timeout=(self.timeout))
+        return response
+
+    def get_response_content(self, url: str) -> ByteString | None:
+        """Request resources from the Heurist server.
+
+        Args:
+            url (str): Heurist API entry point.
+
+        Returns:
+            ByteString | None: Binary response returned from Heurist server.
+        """
+
+        try:
+            response = self.call_heurist_api(url=url)
+        except RetryError:
+            e = ReadTimeout(url=url, timeout=self.timeout)
+            raise SystemExit(e)
+        if not response:
+            e = APIException("No response.")
+            raise SystemExit(e)
+        elif response.status_code != 200:
+            e = APIException(f"Status {response.status_code}")
+            raise SystemExit(e)
+        elif "Cannot connect to database" == response.content.decode("utf-8"):
+            e = APIException("Could not connect to database.")
+            raise SystemExit(e)
+        else:
+            return response.content
+
+    def get_records(
+        self,
+        record_type_id: int,
+        form: Literal["xml", "json"] = "json",
+        users: tuple[int] = (),
+    ) -> bytes | list | None:
+        """Request all records of a certain type and in a certain data format.
+
+        Args:
+            record_type_id (int): Heurist ID of targeted record type.
+            form (Literal["xml", "json"], optional): Data format for requested
+                records. Defaults to "json".
+            users (tuple): Array of IDs of users who added the target records.
+
+        Returns:
+            bytes | list | None: If XML, binary response returned from Heurist
+                server, else JSON array.
+        """
+
+        url = self.url_builder.get_records(
+            record_type_id=record_type_id, form=form, users=users
+        )
+        if form == "json":
+            content = self.get_response_content(url)
+            json_string = content.decode("utf-8")
+            all_records = json.loads(json_string)["heurist"]["records"]
+            # Filter out linked records of a not the target type
+            correct_ids = [
+                r for r in all_records if r["rec_RecTypeID"] == str(record_type_id)
+            ]
+            # Filter out records by non-targeted users
+            if users and len(users) > 0:
+                return [r for r in correct_ids if int(r["rec_AddedByUGrpID"]) in users]
+            else:
+                return correct_ids
+        else:
+            return self.get_response_content(url)
+
+    def get_structure(self) -> bytes | None:
+        """Request the Heurist database's overall structure in XML format.
+
+        Returns:
+            bytes | list | None: If XML, binary response returned from Heurist server,
+            else JSON array.
+        """
+        url = self.url_builder.get_db_structure()
+        return self.get_response_content(url)
+
+    def get_relationship_markers(
+        self, form: Literal["xml", "json"] = "xml"
+    ) -> bytes | list | None:
+        return self.get_records(record_type_id=1, form=form)

heurist/api/connection.py

@@ -0,0 +1,71 @@
+"""Heurist API session"""
+
+import requests
+from heurist.api.client import HeuristAPIClient
+from heurist.api.constants import READTIMEOUT
+from heurist.api.exceptions import AuthenticationError
+from requests import Session
+
+
+class HeuristAPIConnection:
+    def __init__(
+        self,
+        db: str,
+        login: str,
+        password: str,
+        read_timeout: int = READTIMEOUT,
+        post_timeout: int = 10,
+    ) -> None:
+        """
+        Session context for a connection to the Heurist server.
+
+        Args:
+            db (str): Heurist database name.
+            login (str): Username.
+            password (str): User's password.
+            read_timeout (int): Seconds to wait before raising a ReadTimeout.
+            post_timeout (int): Seconds to wait before raising an error when \
+                establishing a login connection.
+
+        Raises:
+            e: If the requests method fails, raise that exception.
+            AuthenticationError: If the Heurist server returns a bad status code, \
+                raise an exception.
+        """
+
+        self.db = db
+        self.__login = login
+        self.__password = password
+        self._readtimeout = read_timeout
+        self._posttimeout = post_timeout
+
+    def __enter__(self) -> Session:
+        self.session = requests.Session()
+        url = "https://heurist.huma-num.fr/heurist/api/login"
+
+        body = {
+            "db": self.db,
+            "login": self.__login,
+            "password": self.__password,
+        }
+        try:
+            response = self.session.post(url=url, data=body, timeout=self._posttimeout)
+        except requests.exceptions.ConnectTimeout as e:
+            print(
+                "\nUnable to log in to Heurist Huma-Num server. \
+                  Connection timed out."
+            )
+            raise e
+        if response.status_code != 200:
+            message = response.json()["message"]
+            e = AuthenticationError(message)
+            raise SystemExit(e)
+
+        return HeuristAPIClient(
+            database_name=self.db,
+            session=self.session,
+            timeout_seconds=self._readtimeout,
+        )
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.session.close()

heurist/api/constants.py

@@ -0,0 +1,19 @@
+"""Constant text variables for Heurist API."""
+
+import os
+
+HUMA_NUM_SERVER = "https://heurist.huma-num.fr/heurist"
+
+RECORD_XML_EXPORT_PATH = "/export/xml/flathml.php"
+
+RECORD_JSON_EXPORT_PATH = "/hserv/controller/record_output.php"
+
+STRUCTURE_EXPORT_PATH = "/hserv/structure/export/getDBStructureAsXML.php"
+
+timeout_var = os.environ.get("READTIMEOUT", 10)
+if isinstance(timeout_var, str):
+    timeout_var = int(timeout_var)
+
+READTIMEOUT = timeout_var
+
+MAX_RETRY = 3

heurist/api/credentials.py

@@ -0,0 +1,71 @@
+import os
+
+from dotenv import find_dotenv, load_dotenv
+from heurist.api.connection import HeuristAPIConnection
+from heurist.api.exceptions import MissingParameterException
+
+
+class CredentialHandler:
+    env_file = find_dotenv()
+    db_key = "DB_NAME"
+    login_key = "DB_LOGIN"
+    password_key = "DB_PASSWORD"
+
+    def __init__(
+        self,
+        database_name: str | None = None,
+        login: str | None = None,
+        password: str | None = None,
+        debugging: bool = False,
+    ):
+        if not debugging:
+            load_dotenv(self.env_file)
+
+        params = [
+            (self.db_key, database_name),
+            (self.login_key, login),
+            (self.password_key, password),
+        ]
+
+        # Set all the secret variables in the environment
+        for key, var in params:
+            if var:
+                self.set_var(key=key, var=var)
+            # Confirm that the environment variable is set
+            v = self.get_var(key=key)
+            if not v or v == "":
+                e = MissingParameterException(parameter=key, env_file=self.env_file)
+                raise SystemExit(e)
+
+    def test_connection(self) -> None:
+        with HeuristAPIConnection(
+            db=self.get_database(), login=self.get_login(), password=self.get_password()
+        ) as _:
+            pass
+
+    @classmethod
+    def _reset_envvars(cls) -> None:
+        keys = [cls.db_key, cls.login_key, cls.password_key]
+        for key in keys:
+            if os.environ.get(key):
+                os.environ.pop(key)
+
+    @classmethod
+    def set_var(cls, key: str, var: str) -> None:
+        os.environ[key] = var
+
+    @classmethod
+    def get_var(cls, key: str) -> str | KeyError:
+        return os.getenv(key)
+
+    @classmethod
+    def get_database(cls) -> str:
+        return cls.get_var(key="DB_NAME")
+
+    @classmethod
+    def get_login(cls) -> str:
+        return cls.get_var(key="DB_LOGIN")
+
+    @classmethod
+    def get_password(cls) -> str:
+        return cls.get_var(key="DB_PASSWORD")

heurist/api/exceptions.py

@@ -0,0 +1,45 @@
+from .constants import MAX_RETRY
+
+
+class APIException(Exception):
+    """Problem calling Heurist API."""
+
+
+class AuthenticationError(Exception):
+    """Error raised when unable to authenticate Heurist login."""
+
+    def __init__(self, message):
+        self.message = """Authentication Error.
+\tFailed to authenticate Heurist user login.
+"""
+        super().__init__(self.message)
+
+
+class MissingParameterException(Exception):
+    """Exception raised for a missing parameter."""
+
+    def __init__(self, parameter: str, env_file: str):
+        self.message = f"""MissingParameter Exception.
+\tMissing the variable '{parameter}'.
+\tTried looking in the env file '{env_file}'.
+"""
+        super().__init__(self.message)
+
+
+class ReadTimeout(Exception):
+    """Exception raised because the data returned by the Heurist \
+        server took too long to receive.
+    """
+
+    def __init__(self, url: str, timeout: int):
+        message = f"""ReadTimeout Error.
+\tOn all {MAX_RETRY} tries, Heurist's server took too long (> {timeout} seconds) to \
+send data from the following URL:
+{url}
+Solutions:
+\t1. Try running the command again and hope the server / your internet is faster.
+\t2. Set the READTIMEOUT environment variable immediately before the command and run it\
+ again, i.e. 'READTIMEOUT=20 heurist download'.
+"""
+        self.message = message
+        super().__init__(self.message)

heurist/api/url_builder.py

@@ -0,0 +1,148 @@
+"""Class to compose URIs for calling the Heurist API."""
+
+from typing import Literal
+
+from heurist.api.constants import (
+    HUMA_NUM_SERVER,
+    RECORD_JSON_EXPORT_PATH,
+    RECORD_XML_EXPORT_PATH,
+    STRUCTURE_EXPORT_PATH,
+)
+
+COMMA = "%2C"
+COLON = "%3A"
+
+
+class URLBuilder:
+    """Class to construct endpoints for the Heurist API (on Huma-Num's server)."""
+
+    def __init__(self, database_name: str, server: str = HUMA_NUM_SERVER) -> None:
+        self.server = server
+        self.database_name = database_name
+
+    @property
+    def db_api(self) -> str:
+        return f"{self.server}{STRUCTURE_EXPORT_PATH}"
+
+    @property
+    def xml_record_api(self) -> str:
+        return f"{self.server}{RECORD_XML_EXPORT_PATH}"
+
+    @property
+    def json_record_api(self) -> str:
+        return f"{self.server}{RECORD_JSON_EXPORT_PATH}"
+
+    @classmethod
+    def _join_queries(cls, *args) -> str:
+        """Join 1 or more queries together with an ampersand.
+
+        Returns:
+            str: Fragment of a path for the URL.
+        """
+        return "&".join([a for a in args if a is not None])
+
+    @classmethod
+    def _join_list_items(cls, *args) -> str:
+        """Join 1 or more items in a list of queries.
+
+        Examples:
+            >>> item1 = '{"filter"%3A"value"}'
+            >>> item2 = '{"filter"%3A"value"}'
+            >>> item3 = '{"filter"%3A"value"}'
+            >>> URLBuilder._join_list_items(item1, item2, item3)
+            '[{"filter"%3A"value"}%2C{"filter"%3A"value"}%2C{"filter"%3A"value"}]'
+
+        Returns:
+            str: Fragment of a path for the URL.
+        """
+        start = "["
+        end = "]"
+        items = COMMA.join([a for a in args if a is not None])
+        return f"{start}{items}{end}"
+
+    @classmethod
+    def _make_filter_obj(cls, filter: str, value: str | int) -> str:
+        start = "{"
+        end = "}"
+        return f'{start}"{filter}"{COLON}"{value}"{end}'
+
+    @classmethod
+    def _join_comma_separated_values(cls, *args) -> str:
+        return COMMA.join([str(a) for a in args if a is not None])
+
+    def get_db_structure(self) -> str:
+        """
+        URL to retrieve the database structure.
+
+        Examples:
+            >>> db = "mock_db"
+            >>> builder = URLBuilder(db)
+            >>> builder.get_db_structure()
+            'https://heurist.huma-num.fr/heurist/hserv/structure/export/getDBStructureAsXML.php?db=mock_db'
+
+        Returns:
+            str: URL to retrieve the database structure.
+        """
+        db = f"?db={self.database_name}"
+        return f"{self.db_api}{db}"
+
+    def get_records(
+        self,
+        record_type_id: int,
+        form: Literal["xml", "json"] = "xml",
+        users: tuple = (),
+    ) -> str:
+        """Build a URL to retrieve records of a certain type.
+
+        Examples:
+            >>> db = "mock_db"
+            >>> builder = URLBuilder(db)
+            >>> builder.get_records(101)
+            'https://heurist.huma-num.fr/heurist/export/xml/flathml.php?q=[{"t"%3A"101"}%2C{"sortby"%3A"t"}]&a=1&db=mock_db&depth=all&linkmode=direct_links'
+
+            >>> db = "mock_db"
+            >>> builder = URLBuilder(db)
+            >>> builder.get_records(102, form="json")
+            'https://heurist.huma-num.fr/heurist/hserv/controller/record_output.php?q=[{"t"%3A"102"}%2C{"sortby"%3A"t"}]&a=1&db=mock_db&depth=all&linkmode=direct_links&format=json&defs=0&extended=2'
+
+            >>> db = "mock_db"
+            >>> builder = URLBuilder(db)
+            >>> builder.get_records(102, users=(2,16,))
+            'https://heurist.huma-num.fr/heurist/export/xml/flathml.php?q=[{"t"%3A"102"}%2C{"sortby"%3A"t"}%2C{"addedby"%3A"2%2C16"}]&a=1&db=mock_db&depth=all&linkmode=direct_links'
+
+
+        Args:
+            record_type_id (int): Heurist ID of the record type.
+            form (Literal["xml", "json"]): The format of the exported data.
+
+        Returns:
+            str: URL to retrieve records of a certain type.
+        """
+
+        a = "a=1"
+        db = "db=%s" % (self.database_name)
+        depth = "depth=all"
+        link_mode = "linkmode=direct_links"
+
+        if form == "json":
+            api = self.json_record_api
+            format_args = "format=json&defs=0&extended=2"
+        else:
+            api = self.xml_record_api
+            format_args = None
+
+        # Make the query based on parameters
+        record_type_filter = self._make_filter_obj(filter="t", value=record_type_id)
+        sortby_filter = self._make_filter_obj(filter="sortby", value="t")
+        if len(users) > 0:
+            user_string = self._join_comma_separated_values(*users)
+            users_filter = self._make_filter_obj(filter="addedby", value=user_string)
+        else:
+            users_filter = None
+        query_path = self._join_list_items(
+            record_type_filter, sortby_filter, users_filter
+        )
+        query = f"?q={query_path}"
+
+        path = self._join_queries(query, a, db, depth, link_mode, format_args)
+        return f"{api}{path}"

heurist/api/utils.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+
+from .constants import MAX_RETRY
+
+
+def log_attempt_number(retry_state) -> None:
+    """Simple logger for tenacity retry.
+
+    Args:
+        retry_state (tenacity.RetryCallState): Retry result from tenacity.
+    """
+
+    # Get the attempt number from the RetryCallState
+    attempt_number = retry_state.attempt_number
+
+    # Compose the console message
+    time = datetime.now().strftime("%H:%M:%S")
+    message = (
+        f"[{time}] ReadTimeout error when receiving data from the Heurist API. "
+        f"Retrying {attempt_number} / {MAX_RETRY} times..."
+    )
+
+    # Print the error message
+    print(message)