synkit 1.6.5__py3-none-win_amd64.whl

synkit/CRN/Query/kegg_api.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+
+@dataclass(slots=True)
+class KEGGClient:
+    """Lightweight REST client for the KEGG API.
+
+    This client provides a minimal wrapper around the KEGG REST interface and
+    returns raw response text for a requested endpoint.
+
+    :param base_url:
+        Base KEGG REST endpoint.
+    :type base_url: str
+    :param timeout:
+        Request timeout in seconds.
+    :type timeout: float
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        client = KEGGClient(
+            base_url="https://rest.kegg.jp",
+            timeout=30.0,
+        )
+        text = client.get_text("get/hsa00010")
+    """
+
+    base_url: str = "https://rest.kegg.jp"
+    timeout: float = 60.0
+
+    def get_text(self, path: str) -> str:
+        """Send ``GET <base_url>/<path>`` and return the response body as text.
+
+        :param path:
+            Relative KEGG REST path, for example ``"get/hsa00010"``.
+        :type path: str
+
+        :return:
+            Raw text returned by the KEGG REST API.
+        :rtype: str
+
+        :raises requests.HTTPError:
+            Raised when the server responds with an HTTP error status.
+        :raises requests.RequestException:
+            Raised for transport-level request failures.
+
+        .. rubric:: Example
+
+        .. code-block:: python
+
+            client = KEGGClient()
+            entry_text = client.get_text("get/hsa00010")
+        """
+        response: requests.Response = requests.get(
+            f"{self.base_url}/{path}",
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return response.text
+
+    def get_optional_text(self, path: str) -> Optional[str]:
+        """Send a GET request and return the response text when available.
+
+        Unlike :meth:`get_text`, this method suppresses
+        :class:`requests.HTTPError` and returns ``None`` for HTTP-level
+        failures such as ``404 Not Found``.
+
+        :param path:
+            Relative KEGG REST path.
+        :type path: str
+
+        :return:
+            Response text if the request succeeds, otherwise ``None`` when an
+            HTTP error occurs.
+        :rtype: Optional[str]
+
+        :raises requests.RequestException:
+            Raised for non-HTTP request failures, such as connection errors or
+            timeouts.
+
+        .. rubric:: Example
+
+        .. code-block:: python
+
+            client = KEGGClient()
+            maybe_text = client.get_optional_text("get/hsa00010")
+            if maybe_text is not None:
+                print(maybe_text[:200])
+        """
+        try:
+            return self.get_text(path)
+        except requests.HTTPError:
+            return None