chainalysis 0.0.1__py3-none-any.whl

chainalysis/DataSolutions.py

@@ -0,0 +1,22 @@
+from chainalysis.sql.sql import Sql
+from chainalysis.utils.utils import Utils
+
+
+class DataSolutionsClient:
+    """
+    This class provides SDK functions for users to query
+    Data Solutions databases.
+
+    The Analytical class queries the Data Solutions Databricks table.
+    The Transactional class queries the Data Solutions Postgres table.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+    ):
+        self.api_key = api_key
+
+        # Define SDK function classes
+        self.sql = Sql(api_key)
+        self.utils = Utils()

chainalysis/__init__.py

@@ -0,0 +1,3 @@
+from chainalysis import *
+from sql import *
+from utils import *

chainalysis/constants.py

@@ -0,0 +1,12 @@
+BASE_URL = {
+    "base_url": "https://api.transpose.io",
+}
+
+ANALYTICAL_ENDPOINTS = {
+    "async_query_execution": "sql/analytical/async",
+    "async_query_status": "sql/analytical/status",
+}
+
+TRANSACTIONAL_ENDPOINTS = {
+    "query_execution": "sql/transactional",
+}

chainalysis/sql/__init__.py

@@ -0,0 +1 @@
+from chainalysis.sql import *

chainalysis/sql/analytical.py

@@ -0,0 +1,234 @@
+from time import sleep
+
+import pandas as pd
+
+from chainalysis.constants import ANALYTICAL_ENDPOINTS, BASE_URL
+from chainalysis.util_functions.exceptions import (
+    BadRequest,
+    DataSolutionsAPIException,
+    DataSolutionsSDKException,
+    UnhandledException,
+)
+from chainalysis.util_functions.requests import issue_request
+
+
+class Analytical:
+    """
+    This class provides methods to execute SQL queries on Data Solutions
+    DataBricks tables. It supports fetching results as JSON or a
+    pandas DataFrame, and provides query execution statistics.
+    """
+
+    def __init__(self, api_key: str):
+        """
+        Initialize the Analytical class with the provided API key.
+
+        :param api_key: The API key for accessing the analytical service.
+        :type api_key: str
+        """
+
+        self.api_key = api_key
+        self._status_code = 0
+        self.results = {}
+        self._stats = {}
+        self.json_response = {}
+        self.dataframe_data = None
+        self._status = "error"
+        self.next = ""
+        self._total_pages = 0
+        self.query_id = None
+        self.exception = UnhandledException()
+
+    def __call__(
+        self,
+        query: str,
+        parameters: dict[str] = {},
+        polling_interval_sec: int = 5,
+    ):
+        """
+        Execute a SQL query asynchronously using the provided parameters
+        and polling interval.
+
+        :param query: The SQL query to be executed.
+        :type query: str
+        :param parameters: A dictionary of parameters to be used in the query.
+        :type parameters: dict[str], optional
+        :param polling_interval_sec: The interval in seconds between status checks.
+        :type polling_interval_sec: int, optional
+        :return: An instance of the Analytical class with query results.
+        :rtype: Analytical
+        """
+
+        query_execution_url = (
+            f"{BASE_URL['base_url']}/{ANALYTICAL_ENDPOINTS['async_query_execution']}"
+        )
+
+        body = {
+            "sql": query,
+            "parameters": parameters,
+        }
+
+        async_response = issue_request(
+            api_key=self.api_key,
+            url=query_execution_url,
+            body=body,
+            method="POST",
+        )
+
+        self.query_id = async_response.get("query_id")
+        if not self.query_id:
+            raise DataSolutionsAPIException(
+                "Unexpected response. Query ID was not returned."
+            )
+        async_query_status_url = f"{BASE_URL['base_url']}/{ANALYTICAL_ENDPOINTS['async_query_status']}?query_id={self.query_id}"
+
+        try:
+            while True:
+                self.json_response = issue_request(
+                    api_key=self.api_key,
+                    url=async_query_status_url,
+                    method="GET",
+                )
+
+                self._status = self.json_response["status"]
+
+                if self._status == "running" or self._status == "pending":
+                    sleep(polling_interval_sec)
+                elif self._status == "error":
+                    self.error_message = self.json_response["message"]
+                    self.error_details = self.json_response.get("details")
+                    break
+                elif self._status == "success":
+                    self._status_code = 200
+                    self._stats = self.json_response["stats"]
+                    self.results = self.json_response["results"]
+                    self.next_url = self.json_response["next"]
+                    self._total_pages = self._stats["total_pages"]
+                    break
+        except DataSolutionsSDKException as e:
+            self.exception = e.get_exception()
+            self._status_code = e.status_code
+        except Exception as e:
+            self.exception = UnhandledException(
+                details=e,
+            )
+        return self
+
+    def next_page(self):
+        """
+        Fetch the next page of DataBricks query results.
+
+        :return: An instance of the Analytical class with the next page of results.
+        :rtype: Analytical
+        """
+
+        if self.next_url:
+
+            self.json_response = issue_request(
+                api_key=self.api_key,
+                url=self.next_url,
+                method="GET",
+            )
+            self._status = self.json_response["status"]
+
+            if self._status == "error":
+                self.error_message = self.json_response["message"]
+                self.error_details = self.json_response.get("details")
+            elif self._status == "success":
+                self._status = self._status
+                self._stats = self.json_response["stats"]
+                self.results = self.json_response["results"]
+                self.next_url = self.json_response["next"]
+        else:
+            raise BadRequest(
+                "No next page available. Use the method has_next() to check if there is a next page that can be retrieved."
+            )
+        return self
+
+    def json(self):
+        """
+        Return results as a JSON.
+
+        :raises Exception: Raises an exception if the query resulted in an error.
+        :return: Results of the SQL query as a JSON.
+        :rtype: dict
+        """
+
+        if self._status != "error":
+            return self.results
+        else:
+            raise self.exception
+
+    def df(self):
+        """
+        Convert query results into a pandas DataFrame.
+
+        :raises Exception: Raises an exception if the query resulted in an error.
+        :return: DataFrame containing the results of the SQL query.
+        :rtype: pd.DataFrame
+        """
+
+        if self._status != "error":
+            if self.dataframe_data:
+                return self.dataframe_data
+            self.dataframe_data = pd.DataFrame(self.results)
+            return self.dataframe_data
+        else:
+            raise self.exception
+
+    def stats(self):
+        """
+        Get the statistics of the executed query.
+
+        :return: Statistics of the query execution.
+        :rtype: dict
+        """
+
+        if self._status != "error":
+            return self._stats
+        else:
+            raise self.exception
+
+    def status_code(self):
+        """
+        Get the HTTP status code of the response.
+
+        :return: HTTP status code.
+        :rtype: int
+        """
+
+        return self._status_code
+
+    def was_successful(self):
+        """
+        Determine if the query executed successfully.
+
+        :return: True if the query was successful, False otherwise.
+        :rtype: bool
+        """
+
+        if self._status != "error":
+            return True
+        return False
+
+    def total_pages(self) -> int:
+        """
+        Return total number of pages.
+
+        :return: Number of pages.
+        :rtype: int
+        """
+
+        return self._total_pages
+
+    def has_next(self) -> bool:
+        """
+        Return if the next page exists.
+
+        :return: Whether next page exists.
+        :rtype: bool
+        """
+
+        if self.next_url:
+            return True
+        return False

chainalysis/sql/sql.py

@@ -0,0 +1,8 @@
+from chainalysis.sql.analytical import Analytical
+from chainalysis.sql.transactional import Transactional
+
+
+class Sql:
+    def __init__(self, api_key: str):
+        self.transactional = Transactional(api_key)
+        self.analytical = Analytical(api_key)

chainalysis/sql/transactional.py

@@ -0,0 +1,145 @@
+import pandas as pd
+
+from chainalysis.constants import BASE_URL, TRANSACTIONAL_ENDPOINTS
+from chainalysis.util_functions.exceptions import (
+    DataSolutionsSDKException,
+    UnhandledException,
+)
+from chainalysis.util_functions.requests import issue_request
+
+
+class Transactional:
+    """
+    This class provides methods to handle transactional queries.
+    It supports fetching results as JSON or pandas DataFrame,
+    and provides query execution statistics.
+    """
+
+    def __init__(self, api_key: str):
+        """
+        Initialize the Transactional object with an API key.
+
+        :param api_key: API key for authenticating requests.
+        :type api_key: str
+        """
+        self.api_key = api_key
+        self._status_code = 0
+        self.results = {}
+        self._stats = {}
+        self.json_response = {}
+        self.status = "error"
+        self.dataframe_data = None
+
+    def __call__(
+        self, query: str, parameters: dict[str, str] = {}, options: dict[str, str] = {}
+    ) -> "Transactional":
+        """
+        Execute a SQL query using the provided parameters and options.
+
+        :param query: SQL query template with placeholders for parameters.
+        :type query: str
+        :param parameters: Parameters to format the SQL query.
+        :type parameters: dict[str, str]
+        :param options: Additional options for query execution.
+        :type options: dict[str, str]
+        :return: Returns self for chaining or method chaining.
+        :rtype: Transactional
+        """
+
+        query_execution_url = (
+            f"{BASE_URL['base_url']}/{TRANSACTIONAL_ENDPOINTS['query_execution']}"
+        )
+
+        body = {
+            "sql": query,
+            "parameters": parameters,
+            "options": options,
+        }
+
+        try:
+            self.json_response = issue_request(
+                api_key=self.api_key,
+                url=query_execution_url,
+                body=body,
+                method="POST",
+            )
+            self.status = self.json_response["status"]
+            if self.status == "error":
+                self.error_message = self.json_response["message"]
+                self.error_details = self.json_response.get("details")
+                self.exception = DataSolutionsSDKException(self.error_message)
+            else:
+                self._stats = self.json_response["stats"]
+                self.results = self.json_response["results"]
+                self._status_code = 200
+
+        except DataSolutionsSDKException as e:
+            self.exception = e.get_exception()
+            self._status_code = e.status_code
+        except Exception as e:
+            self.exception = UnhandledException(
+                details=e,
+            )
+        return self
+
+    def json(self) -> dict:
+        """
+        Return the JSON data of the results.
+
+        :raises Exception: Raises an exception if the query resulted in an error.
+        :return: JSON results of the SQL query.
+        :rtype: dict
+        """
+
+        if self.status != "error":
+            return self.results
+        else:
+            raise self.exception
+
+    def df(self) -> pd.DataFrame:
+        """
+        Convert query results into a pandas DataFrame.
+
+        :raises Exception: Raises an exception if the query resulted in an error.
+        :return: DataFrame containing the results of the SQL query.
+        :rtype: pd.DataFrame
+        """
+        if self.status != "error":
+            if self.dataframe_data:
+                return self.dataframe_data
+            self.dataframe_data = pd.DataFrame(self.results)
+            return self.dataframe_data
+        elif self.exception:
+            raise self.exception
+
+    def stats(self) -> dict:
+        """
+        Get the statistics of the executed query.
+
+        :return: Statistics of the query execution.
+        :rtype: dict
+        """
+        if self.status != "error":
+            return self._stats
+        else:
+            raise self.exception
+
+    def was_successful(self) -> bool:
+        """
+        Determine if the query executed successfully.
+
+        :return: True if the query was successful, False otherwise.
+        :rtype: bool
+        """
+        if self.status != "error":
+            return True
+        return False
+
+    def status_code(self) -> int:
+        """
+        Return the status code of the query.
+
+        :return: The status code of the query.
+        :rtype: int
+        """
+        return self._status_code

chainalysis/util_functions/check_list_type.py

@@ -0,0 +1,18 @@
+from typing import Any, List, Type
+
+from chainalysis.util_functions.exceptions import BadRequest
+
+
+def get_list_type(my_list: List[Any]) -> Type:
+    """Return the type of list elements if all are the same type, otherwise raise an error."""
+    if not my_list:
+        raise ValueError("The list is empty and has no element type.")
+
+    element_types = {type(item) for item in my_list}
+
+    if len(element_types) > 1:
+        raise BadRequest(
+            f"The list contains multiple types: {element_types}. Enter a list with only numbers, strings, or bools."
+        )
+
+    return element_types.pop()

chainalysis/util_functions/exceptions.py

@@ -0,0 +1,87 @@
+class DataSolutionsSDKException(Exception):
+    """Base class for SDK exceptions."""
+
+    def __init__(
+        self,
+        message=None,
+        status_code=0,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+
+    def get_exception(self):
+        return self
+
+
+class BadRequest(DataSolutionsSDKException):
+    """Exception for Bad Request."""
+
+    def __init__(self, message="Bad Request"):
+        super().__init__(
+            message,
+            status_code=400,
+        )
+
+
+class Unauthorized(DataSolutionsSDKException):
+    """Exception for 401 Unauthorized."""
+
+    def __init__(self, message="Unauthorized"):
+        super().__init__(
+            message,
+            status_code=401,
+        )
+
+
+class Forbidden(DataSolutionsSDKException):
+    """Exception for 403 Forbidden."""
+
+    def __init__(
+        self,
+        message="Forbidden. Contact Data Solutions if you believe you should have access to this endpoint/data.",
+    ):
+        super().__init__(
+            message,
+            status_code=403,
+        )
+
+
+class NotFound(DataSolutionsSDKException):
+    """Exception for 404 Not Found."""
+
+    def __init__(self, message="Not Found. Is your query correct?"):
+        super().__init__(
+            message,
+            status_code=404,
+        )
+
+
+class InternalServerException(DataSolutionsSDKException):
+    """Exception for 500 Internal Server Error."""
+
+    def __init__(self, message="Internal Server Error"):
+        super().__init__(
+            message,
+            status_code=500,
+        )
+
+
+class DataSolutionsAPIException(DataSolutionsSDKException):
+    """Exception for the API returning an unexpected response."""
+
+    def __init__(self, message="Unexpected response from the API"):
+        super().__init__(
+            message,
+            status_code=0,
+        )
+
+
+class UnhandledException(DataSolutionsSDKException):
+    """Unhandled exception."""
+
+    def __init__(
+        self,
+        message="An unhandled exception occured. Please contact the Data Solutions Team.",
+        details="",
+    ):
+        super().__init__((message, details))

chainalysis/util_functions/requests.py

@@ -0,0 +1,87 @@
+from requests import JSONDecodeError, request
+from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+
+from chainalysis.util_functions.exceptions import (
+    BadRequest,
+    DataSolutionsAPIException,
+)
+
+
+def get_headers(api_key: str) -> dict:
+    """
+    Generate headers for an HTTP request.
+
+    This function creates a dictionary of headers required for an HTTP request,
+    including the API key for authorization and JSON content-type headers which
+    indicate what sort of information will be sent with the request.
+
+    :param api_key: The API key used for authenticating the request.
+    :return: A dictionary containing the headers for the HTTP request.
+    """
+
+    return {
+        "X-API-KEY": api_key,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+
+def retry_if_not_bad_request(exception):
+    if isinstance(exception, BadRequest):
+        return False  # Do not retry if it's a BadRequestException
+    return True  # Retry for other exceptions
+
+
+@retry(
+    wait=wait_exponential(multiplier=1, min=4, max=10),
+    retry=retry_if_exception(retry_if_not_bad_request),
+    stop=stop_after_attempt(10),
+)
+def issue_request(
+    url: str,
+    api_key: str,
+    params: dict = {},
+    body: dict = {},
+    method: str = "GET",
+) -> dict:
+    """
+    Helper method to issue a request to the Data Solutions API.
+    This method will automatically retry the request, and handle
+    basic error checking.
+    """
+
+    # Encode params and body into a single variable data
+    data = {**(params or {}), **(body or {})}
+
+    response = request(
+        method,
+        url,
+        headers=get_headers(api_key),
+        json=data,
+    )
+
+    if response.status_code >= 300:
+        try:  # Try to decode the json response of the error
+            json_output = response.json()
+            error_message = json_output.get("message")
+
+        except JSONDecodeError:
+            raise DataSolutionsAPIException(
+                message="Unexpected response from the API - response was not JSON",
+            )
+        if response.status_code == 400:
+            raise BadRequest(
+                message=error_message,
+            )
+        raise DataSolutionsAPIException(
+            message=error_message,
+        )
+
+    try:  # Try to decode the json response of the successful request
+        response_json = response.json()
+    except JSONDecodeError:
+        raise DataSolutionsAPIException(
+            message="Unexpected response from the API - response was not JSON",
+        )
+
+    return response_json

chainalysis/utils/__init__.py

@@ -0,0 +1 @@
+from chainalysis.utils import *

chainalysis/utils/stringify.py

@@ -0,0 +1,79 @@
+import datetime
+import decimal
+
+from chainalysis.util_functions.check_list_type import get_list_type
+from chainalysis.util_functions.exceptions import BadRequest
+
+
+class Stringify:
+    """
+    This class contains functions to transform python objects
+    into formatted string params so they can be used to query
+    Data Solutions' databases without needing to be transformed
+    manually by the user.
+    """
+
+    def lists(self, _list: list) -> str:
+        """
+        Convert a list to a formatted string param.
+
+        :param list: The list to be converted.
+        :type list: list
+
+        :raises Exception: Raises an exception if a list type is not submitted.
+        :raises Exception: If lists do not contain the right types.
+        :return: The converted list.
+        :rtype: str
+        """
+
+        if not isinstance(_list, list):
+            raise BadRequest(
+                "Incorrect type. Supply a list.",
+            )
+
+        type = get_list_type(_list)
+
+        if type == int or type == bool or type == float or type == decimal:
+            return f"({', '.join(map(str, _list))})"
+
+        if type == str:
+            result = "("
+
+            for i, element in enumerate(_list):
+                if i > 0:
+                    result += ", "
+                result += f"'{element}'"
+
+            result += ")"
+            return result
+
+    def columns(self, columns: list) -> str:
+        """
+        Convert a column select list to a formatted string param.
+
+        :param list: The column select list object to be converted.
+        :type list: list
+
+        :return: The converted column select list.
+        :rtype: str
+        """
+        type = get_list_type(columns)
+        if type != str:
+            raise BadRequest("Columns must be a list")
+        return ", ".join(columns)
+
+    def datetimes(self, _datetime: datetime.datetime) -> str:
+        """
+        Convert a datetime object to a formatted string param.
+
+        :param list: The datetime object to be converted.
+        :type list: list
+
+        :return: The converted datetime object.
+        :rtype: str
+        """
+
+        if not isinstance(_datetime, datetime.datetime):
+            raise BadRequest("Incorrect type. Supply a datetime.datetime object.")
+
+        return f"'{_datetime.strftime('%Y-%m-%dT%H:%M:%SZ')}'"

chainalysis/utils/utils.py

@@ -0,0 +1,11 @@
+from chainalysis.utils.stringify import Stringify
+
+
+class Utils:
+    """
+    This class contains util/helper functions for users
+    of the SDK.
+    """
+
+    def __init__(self):
+        self.stringify = Stringify()

chainalysis-0.0.1.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: chainalysis
+Version: 0.0.1
+Summary: SDK functions for users to query Data Solutions databases.
+Project-URL: Homepage, https://github.com/TransposeData/chainalysis-data-solutions-python-sdk
+Author-email: "Rah Tarar (musa-tarar)" <musa.nishat@chainalysis.com>
+License-File: LICENCE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+![Transpose Banner](https://files.readme.io/c019281-Main_Docs_Banners_v1.png)
+
+# Welcome to the Transpose Python SDK
+A modern python wrapper for the Transpose API Suite.
+
+## Installation
+
+```bash
+pip install DataSolutions
+```

chainalysis-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+chainalysis/DataSolutions.py,sha256=qeqKENCyCoJrerfcit7j6yELuY-ePk3gHzT-X6ckDR4,545
+chainalysis/__init__.py,sha256=NnWPLQkHHK52JYDzj5MISZNd0LXVJm0vvop1v-oZGSY,64
+chainalysis/constants.py,sha256=LDSDcwxDaKx0bJC-nXL_3piwMdTynMz2mVOZdVeHgDU,266
+chainalysis/sql/__init__.py,sha256=27BfFf5rFz3kg4ColUnLTOpy0VMEpALJhcZcHh8zu6g,30
+chainalysis/sql/analytical.py,sha256=H8RNXQkl1JMyGsVrDBfp8y9BADWC1XDUECIZL20igmg,7045
+chainalysis/sql/sql.py,sha256=6wpc1_rKqSpF-ULDyVzJ_8h28hb3ncIXps4Pd86ryPQ,255
+chainalysis/sql/transactional.py,sha256=fh-3rgoJAMcSHYj6c2wTvAk5SOgBbaBpHVCxmG_dYYI,4472
+chainalysis/util_functions/check_list_type.py,sha256=_lZmdnEkG0uFQYqPUkZFP8cj1qVXEKaBN-MtzaRw06o,603
+chainalysis/util_functions/exceptions.py,sha256=FQSrVGJu1amQAj1SFYb1p5ZUesRNGUli6JyxdT5VX4U,2120
+chainalysis/util_functions/requests.py,sha256=qDpxtkYbPI0vx5jJBtmik1i7O7J76k1qVe7ExgyoxIc,2589
+chainalysis/utils/__init__.py,sha256=OI-IE3BHkwsChB89cE0wB1TQRL_m4_43Fl09CIdPyaI,32
+chainalysis/utils/stringify.py,sha256=srG1QPj4p3tXvt-yWK7fbOigT0zMrPlFmIhQNFSxgXA,2325
+chainalysis/utils/utils.py,sha256=iVWQ8C-9xOmb83uz8xL9cOHHdigY75qf2ej2nkqKHwE,215
+chainalysis-0.0.1.dist-info/METADATA,sha256=yPKOb1cMRUedkGIT3QHbJ6JUiXGHldRpMG6iPYAW0gc,744
+chainalysis-0.0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+chainalysis-0.0.1.dist-info/licenses/LICENCE,sha256=7EI8xVBu6h_7_JlVw-yPhhOZlpY9hP8wal7kHtqKT_E,1074
+chainalysis-0.0.1.dist-info/RECORD,,

chainalysis-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chainalysis-0.0.1.dist-info/licenses/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.