aplos-nca-saas-sdk 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

aplos_nca_saas_sdk/{aws_resources → nca_resources}/aws_s3_presigned_upload.py

@@ -1,5 +1,5 @@
 """
-Copyright 2024 Aplos Analytics
+Copyright 2024-2025 Aplos Analytics
 All Rights Reserved.   www.aplosanalytics.com   LICENSED MATERIALS
 Property of Aplos Analytics, Utah, USA
 """
@@ -9,20 +9,23 @@ import os
 from typing import Any, Dict
 
 import requests
-from aplos_nca_saas_sdk.aws_resources.aws_s3_presigned_payload import (
-    S3PresignedPayload,
+from aplos_nca_saas_sdk.nca_resources.aws_s3_presigned_payload import (
+    S3PresignedUrlPayload,
 )
-from aplos_nca_saas_sdk.utilities.http_utility import HttpUtilities, Routes
+from aplos_nca_saas_sdk.utilities.http_utility import HttpUtilities
+from aplos_nca_saas_sdk.nca_resources._api_base import NCAApiBaseClass
 
 
-class S3PresignedUpload:
-    """S3PresignedUpload"""
+class S3PresignedUrlUpload(NCAApiBaseClass):
+    """S3PresignedUrlUpload"""
 
-    def __init__(self, jwt: str, api_url: str) -> None:
-        self.api_url = api_url
-        self.jwt = jwt
+    def __init__(self, host: str) -> None:
+        super().__init__(host)
 
-    def upload_file(self, input_file: str) -> Dict[str, Any]:
+    def upload_file(
+        self,
+        input_file: str,
+    ) -> Dict[str, Any]:
         """
         Uploads a file to your Aplos Cloud Account in AWS
 
@@ -34,15 +37,17 @@ class S3PresignedUpload:
         """
 
         # get the presigned url for uploading
-        paylod: S3PresignedPayload = self.__get_presigned_upload_info(
-            input_file=input_file
+        paylod: S3PresignedUrlPayload = self.__get_presigned_upload_info(
+            input_file=input_file, jwt=self.authenticator.cognito.jwt
         )
         # upload the files
         upload_response = self.__upload_file_to_s3(paylod, input_file=input_file)
 
         return upload_response
 
-    def __get_presigned_upload_info(self, input_file: str) -> S3PresignedPayload:
+    def __get_presigned_upload_info(
+        self, input_file: str, jwt: str
+    ) -> S3PresignedUrlPayload:
         """
         Performs all the necessary steps for creating a presigned url to upload a file to S3.
         We're using AWS S3 presigned urls for security as well as allowing for very large files if required.
@@ -50,11 +55,11 @@ class S3PresignedUpload:
             input_file (str): the path to the input (analysis) file
 
         Returns:
-            S3PresignedPayload: instance of S3PresignedPayload
+            S3PresignedUrlPayload: instance of S3PresignedUrlPayload
         """
 
-        url = f"{self.api_url}/{Routes.NCA_GENERATE_UPLOAD}"
-        headers = HttpUtilities.get_headers(self.jwt)
+        url = self.endpoints.files
+        headers = HttpUtilities.get_headers(jwt)
 
         body = {"file_name": input_file, "method_type": "post"}
         response = requests.post(
@@ -64,29 +69,29 @@ class S3PresignedUpload:
         if response.status_code == 403:
             raise PermissionError(
                 "Failed to get a presigned url. "
-                f"Status Code: {response.status_code }"
+                f"Status Code: {response.status_code}"
                 f"Reason: {response.reason} "
                 f"403 Errors can also occur if you have an invalid path."
             )
         elif response.status_code != 200:
             raise RuntimeError(
                 "Failed to get a presigned url. "
-                f"Status Code: {response.status_code }"
+                f"Status Code: {response.status_code}"
                 f"Reason: {response.reason}"
             )
         result = response.json()
 
-        payload: S3PresignedPayload = S3PresignedPayload(result)
+        payload: S3PresignedUrlPayload = S3PresignedUrlPayload(result)
 
         return payload
 
     def __upload_file_to_s3(
-        self, payload: S3PresignedPayload, input_file: str
+        self, payload: S3PresignedUrlPayload, input_file: str
     ) -> Dict[str, Any]:
         """
         Peforms the actual uploading via a presigned url for S3 bucket storage
         Args:
-            payload (S3PresignedPayload): instance of S3PresignedPayload with all the data needed
+            payload (S3PresignedUrlPayload): instance of S3PresignedUrlPayload with all the data needed
             input_file (str): the path to a file being uploaded
 
         Raises:
@@ -104,8 +109,9 @@ class S3PresignedUpload:
         with open(input_file, "rb") as file:
             files = {"file": (input_file, file)}
             # upload to s3 with the presigned url
+            # authentication is built into the url
             upload_response = requests.post(
-                str(payload.url), data=payload.form_data, files=files, timeout=30
+                str(payload.url), data=payload.form_data, files=files, timeout=60
             )
 
         # Check the response: 204 is a success in this case

aplos_nca_saas_sdk/nca_resources/nca_analysis.py

@@ -0,0 +1,304 @@
+"""
+Copyright 2024-2025 Aplos Analytics
+All Rights Reserved.   www.aplosanalytics.com   LICENSED MATERIALS
+Property of Aplos Analytics, Utah, USA
+"""
+
+import json
+import os
+import time
+import zipfile
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict
+
+import requests
+from aws_lambda_powertools import Logger
+
+from aplos_nca_saas_sdk.nca_resources._api_base import NCAApiBaseClass
+from aplos_nca_saas_sdk.nca_resources.aws_s3_presigned_upload import (
+    S3PresignedUrlUpload,
+)
+from aplos_nca_saas_sdk.utilities.environment_vars import EnvironmentVars
+from aplos_nca_saas_sdk.utilities.http_utility import HttpUtilities
+
+logger = Logger()
+
+
+class NCAAnalysis(NCAApiBaseClass):
+    """NCA Analysis API"""
+
+    def __init__(self, host: str) -> None:
+        super().__init__(host)
+
+        self.verbose: bool = False
+
+    def execute(
+        self,
+        username: str,
+        password: str,
+        input_file_path: str,
+        config_data: dict,
+        *,
+        meta_data: str | dict | None = None,
+        wait_for_results: bool = True,
+        max_wait_in_seconds: int = 900,
+        output_directory: str | None = None,
+        unzip_after_download: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Executes an analsysis.
+            - Uploads an analysis file.
+            - Adds the execution to the queue.
+
+        Args:
+            username (str): the username
+            password (str): the users password
+            input_file_path (str): the path to the input (analysis) file
+            config_data (dict): analysis configuration information
+            meta_data (str | dict | None, optional): meta data attached to the execution. Defaults to None.
+            wait_for_results (bool, optional): should the program wait for results. Defaults to True.
+            max_wait_in_seconds (int optional): the max time to wait for a download
+            output_directory (str, optional): the output directory. Defaults to None (the local directory is used)
+            unzip_after_download (bool): Results are downloaded as a zip file, this option will unzip them automatically.  Defaults to False
+
+        Returns:
+            Dict[str, Any]: The execution response.  If you wait for the completion
+        """
+
+        self.log(f"\tLogging into {self.host}.")
+
+        self.authenticator.authenticate(username=username, password=password)
+
+        self.log("\tUploading the analysis file.")
+        uploader: S3PresignedUrlUpload = S3PresignedUrlUpload(str(self.host))
+        uploader.authenticator = self.authenticator
+        upload_response: Dict[str, Any] = uploader.upload_file(input_file_path)
+
+        file_id: str = upload_response.get("file_id", "")
+        if not file_id:
+            raise RuntimeError(
+                "Unexpected empty file_id when attempting to upload file."
+            )
+
+        self.log("\tAdding analyis to the queue.")
+        execution_response: Dict[str, Any] = self.__add_to_queue(
+            file_id=file_id,
+            config_data=config_data,
+            meta_data=meta_data,
+        )
+
+        execution_id: str = execution_response.get("execution_id", "")
+
+        response = {
+            "execution": execution_response,
+            "upload": upload_response,
+            "results": {"file": None},
+        }
+
+        if not execution_id:
+            raise RuntimeError(
+                "Unexpected empty execution_id when attempting to execute analysis."
+            )
+
+        if wait_for_results:
+            # wait for it
+            download_url = self.wait_for_results(
+                execution_id=execution_id, max_wait_in_seconds=max_wait_in_seconds
+            )
+            # download the files
+            if download_url is None:
+                raise RuntimeError(
+                    "Unexpected empty download_url when attempting to download results."
+                )
+            else:
+                self.log("\tDownloading the results.")
+                file_path = self.download_file(
+                    download_url,
+                    output_directory=output_directory,
+                    do_unzip=unzip_after_download,
+                )
+
+                response["results"]["file"] = file_path
+        else:
+            self.log("Bypassed results download.")
+
+        return response
+
+    def __add_to_queue(
+        self,
+        file_id: str,
+        config_data: dict,
+        meta_data: str | dict | None = None,
+    ) -> Dict[str, Any]:
+        """
+        Adds the analysis to the execution queue.
+
+        Args:
+            bucket_name (str): s3 bucket name for your organization. this is returned to you
+            object_key (str): 3s object key for the file you are running an analysis on.
+            config_data (dict): the config_data for the analysis file
+            meta_data (str | dict): Optional.  Any meta data you'd like attached to this execution
+        Returns:
+            Dict[str, Any]: the api response
+        """
+
+        if not file_id:
+            raise ValueError("Missing file_id.  Please provide a valid file_id.")
+
+        if not config_data:
+            raise ValueError(
+                "Missing config_data.  Please provide a valid config_data."
+            )
+        headers = HttpUtilities.get_headers(self.authenticator.cognito.jwt)
+        # to start a new execution we need the location of the file (s3 bucket and object key)
+        # you basic configuration
+        # optional meta data
+
+        submission = {
+            "file": {"id": file_id},
+            "configuration": config_data,
+            "meta_data": meta_data,
+        }
+
+        response: requests.Response = requests.post(
+            self.endpoints.executions,
+            headers=headers,
+            data=json.dumps(submission),
+            timeout=30,
+        )
+        json_response: dict = response.json()
+
+        if response.status_code == 403:
+            raise PermissionError(
+                "Failed to execute.  A 403 response occured.  "
+                "This could a token issue or a url path issue  "
+                "By default unknown gateway calls return 403 errors. "
+            )
+        elif response.status_code != 200:
+            raise RuntimeError(
+                f"Unknown Error occured during executions: {response.status_code}. "
+                f"Reason: {response.reason}"
+            )
+
+        execution_id = str(json_response.get("execution_id"))
+
+        self.log(f"\tExecution {execution_id} started.")
+
+        return json_response
+
+    def wait_for_results(
+        self, execution_id: str, max_wait_in_seconds: float = 900
+    ) -> str | None:
+        """
+        Wait for results
+        Args:
+            execution_id (str): the analysis execution id
+
+        Returns:
+            str | None: on success: a url for download, on failure: None
+        """
+
+        url = f"{self.endpoints.execution(execution_id)}"
+
+        headers = HttpUtilities.get_headers(self.authenticator.cognito.jwt)
+        current_time = datetime.now()
+        # Create a timedelta object representing 15 minutes
+        time_delta = timedelta(seconds=max_wait_in_seconds)
+
+        # Add the timedelta to the current time
+        max_time = current_time + time_delta
+
+        complete = False
+        while not complete:
+            response = requests.get(url, headers=headers, timeout=30)
+            json_response: dict = response.json()
+            status = json_response.get("status")
+            complete = status == "complete"
+            elapsed = (
+                json_response.get("times", {}).get("elapsed", "0:00:00") or "--:--"
+            )
+            if status == "failed" or complete:
+                break
+            if not complete:
+                self.log(f"\t\twaiting for results.... {status}: {elapsed}")
+                time.sleep(5)
+            if datetime.now() > max_time:
+                status = "timeout"
+                break
+            if status is None and elapsed is None:
+                # we have a problem
+                status = "unknown issue"
+                break
+
+        if status == "complete":
+            self.log("\tExecution complete.")
+            self.log(f"\tExecution duration = {elapsed}.")
+            return json_response["presigned"]["url"]
+        else:
+            raise RuntimeError(
+                f"\tExecution failed. Execution ID = {execution_id}. reason: {json_response.get('errors')}"
+            )
+
+    def download_file(
+        self,
+        presigned_download_url: str,
+        output_directory: str | None = None,
+        do_unzip: bool = False,
+    ) -> str | None:
+        """
+        # Step 5
+        Download completed analysis files
+
+        Args:
+            presigned_download_url (str): presigned download url
+            output_directory (str | None): optional output directory
+
+        Returns:
+            str: file path to results or None
+        """
+        if output_directory is None:
+            output_directory = str(Path(__file__).parent.parent)
+            output_directory = os.path.join(output_directory, ".aplos-nca-output")
+
+        if EnvironmentVars.is_running_in_aws_lambda():
+            # /tmp is the only directory we can write to unless we mount an external drive
+            # TODO: allow for external mapped drives, perhaps test if we can write to it
+
+            output_directory = os.path.join("/tmp", ".aplos-nca-output")
+
+            self.log(
+                f"\t\tRunning in AWS Lambda.  Setting output directory to {output_directory}"
+            )
+
+        output_file = f"results-{time.strftime('%Y-%m-%d-%Hh%Mm%Ss')}.zip"
+
+        output_file = os.path.join(output_directory, output_file)
+        os.makedirs(output_directory, exist_ok=True)
+
+        response = requests.get(presigned_download_url, timeout=60)
+        # write the zip to a file
+        with open(output_file, "wb") as f:
+            f.write(response.content)
+
+        # optionally, extract all the files from the zip
+        if do_unzip:
+            with zipfile.ZipFile(output_file, "r") as zip_ref:
+                zip_ref.extractall(output_file.replace(".zip", ""))
+
+        unzipped_state = "and unzipped" if do_unzip else "in zip format"
+
+        self.log(f"\tResults file downloaded {unzipped_state}.")
+        self.log(f"\t\tResults are available in: {output_directory}")
+
+        return output_file
+
+    def log(self, message: str | Dict[str, Any]):
+        """Log the message"""
+        logger.debug(message)
+
+        if isinstance(message, dict):
+            message = json.dumps(message, indent=2)
+
+        if self.verbose:
+            print(message)

aplos_nca_saas_sdk/nca_resources/nca_app_configuration.py

@@ -1,5 +1,5 @@
 """
-Copyright 2024 Aplos Analytics
+Copyright 2024-2025 Aplos Analytics
 All Rights Reserved.   www.aplosanalytics.com   LICENSED MATERIALS
 Property of Aplos Analytics, Utah, USA
 """
@@ -30,8 +30,8 @@ class NCAAppConfiguration:
 
     """
 
-    def __init__(self, aplos_saas_domain: str):
-        self.endpoints: NCAEndpoints = NCAEndpoints(aplos_saas_domain=aplos_saas_domain)
+    def __init__(self, host: str):
+        self.__endpoints: NCAEndpoints = NCAEndpoints(host=host)
         self.__response: requests.Response | None = None
 
     def get(self) -> requests.Response:
@@ -40,7 +40,7 @@ class NCAAppConfiguration:
         if self.__response is not None:
             return self.__response
 
-        url = self.endpoints.app_configuration()
+        url = self.__endpoints.app_configuration
         self.__response = requests.get(url, timeout=30)
         if self.__response.status_code != 200:
             raise RuntimeError("App configuration url is not working.")

aplos_nca_saas_sdk/nca_resources/{nca_login.py → nca_authenticator.py}

@@ -1,25 +1,25 @@
 """
-Copyright 2024 Aplos Analytics
+Copyright 2024-2025 Aplos Analytics
 All Rights Reserved.   www.aplosanalytics.com   LICENSED MATERIALS
 Property of Aplos Analytics, Utah, USA
 """
 
 from typing import Optional
-from aplos_nca_saas_sdk.aws_resources.aws_cognito import CognitoAuthenication
+from aplos_nca_saas_sdk.nca_resources.aws_cognito import CognitoAuthentication
 from aplos_nca_saas_sdk.nca_resources.nca_app_configuration import (
     NCAAppConfiguration,
 )
 
 
-class NCALogin:
-    """NCA Login"""
+class NCAAuthenticator:
+    """NCA Authenticator"""
 
     def __init__(
         self,
         *,
         cognito_client_id: Optional[str] = None,
         cognito_region: Optional[str] = None,
-        aplos_saas_domain: Optional[str] = None,
+        host: Optional[str] = None,
     ) -> None:
         """
         NCA SaaS Login
@@ -27,45 +27,43 @@ class NCALogin:
         Args:
             cognito_client_id (Optional[str], optional): Cognito Client Id. Defaults to None.
             cognito_region (Optional[str], optional): Cognito Region. Defaults to None.
-            aplos_saas_domain (Optional[str], optional): Aplos NCA SaaS domain. Defaults to None.
+            host (Optional[str], optional): Aplos NCA SaaS host. Defaults to None.
 
         Requirements:
             Either pass in the cognito_client_id and cognito_region.
-            or set the aplos_saas_domain to automatically get the client_id and region.
+            or set the host to automatically get the client_id and region.
         """
-        self.jwt: str
-        self.access_token: Optional[str] = None
-        self.refresh_token: Optional[str] = None
+
         self.__cognito_client_id = cognito_client_id
         self.__region = cognito_region
-        self.__domain: Optional[str] = aplos_saas_domain
-        self.__cognito: Optional[CognitoAuthenication] = None
+        self.__host: Optional[str] = host
+        self.__cognito: Optional[CognitoAuthentication] = None
         self.__config: Optional[NCAAppConfiguration] = None
 
     @property
-    def cognito(self) -> CognitoAuthenication:
+    def cognito(self) -> CognitoAuthentication:
         """
         Cognito Authentication
         Returns:
             CognitoAuthenication: object to handle cognito authentication
         """
         if self.__cognito is None:
-            self.__cognito = CognitoAuthenication(
+            self.__cognito = CognitoAuthentication(
                 client_id=self.__cognito_client_id,
                 region=self.__region,
-                aplos_domain=self.__domain,
+                aplos_domain=self.__host,
             )
 
         return self.__cognito
 
     @property
-    def domain(self) -> str | None:
+    def host(self) -> str | None:
         """
         Domain
         Returns:
-            str: the domain
+            str: the host
         """
-        return self.__domain
+        return self.__host
 
     @property
     def config(self) -> NCAAppConfiguration:
@@ -75,13 +73,13 @@ class NCALogin:
             NCAAppConfiguration: object to handle the NCA App Configuration
         """
         if self.__config is None:
-            if self.__domain is None:
+            if self.__host is None:
                 raise RuntimeError(
                     "Failed to get Aplos Configuration.  The Domain is not set."
                 )
 
             self.__config = NCAAppConfiguration(
-                aplos_saas_domain=self.__domain,
+                host=self.__host,
             )
 
         return self.__config
@@ -96,9 +94,14 @@ class NCALogin:
         Args:
             username (str): the username
             password (str): the users password
-
+        Returns:
+            str: JWT (JSON Web Token)
         """
+        if not username:
+            raise ValueError("Missing username.  Please provide a valid username.")
+        if not password:
+            raise ValueError("Missing password.  Please provide a valid password.")
 
-        self.jwt = self.cognito.login(username=username, password=password)
+        self.cognito.login(username=username, password=password)
 
-        return self.jwt
+        return self.cognito.jwt

aplos_nca_saas_sdk/nca_resources/nca_endpoints.py

@@ -1,5 +1,5 @@
 """
-Copyright 2024 Aplos Analytics
+Copyright 2024-2025 Aplos Analytics
 All Rights Reserved.   www.aplosanalytics.com   LICENSED MATERIALS
 Property of Aplos Analytics, Utah, USA
 """
@@ -8,51 +8,77 @@ Property of Aplos Analytics, Utah, USA
 class NCAEndpoints:
     """Aplos NCA SaaS Endpoints"""
 
-    def __init__(self, *, aplos_saas_domain: str):
-        self.__domain: str = aplos_saas_domain
+    def __init__(
+        self, *, host: str, tenant_id: str | None = None, user_id: str | None = None
+    ):
+        self.__host: str = host
         self.__protocal: str = "https://"
+        self.tenant_id: str | None = tenant_id
+        self.user_id: str | None = user_id
 
-    def __base(self, tenant_id: str | None = None, user_id: str | None = None) -> str:
-        """Returns the base endpoint"""
-        route = f"{self.__protocal}{self.__domain}"
+    @property
+    def origin(self) -> str:
+        """The origin path e.g. https://api.aplos-nca.com"""
+        base = f"{self.__protocal}{self.__host}"
+        return base
 
-        if tenant_id:
-            route = f"{route}/tenants/{tenant_id}"
-        if user_id:
-            if not tenant_id:
-                raise ValueError("Tenant ID is required on the users path")
-            route = f"{route}/users/{user_id}"
+    @property
+    def tenant_path(self) -> str:
+        """Returns the tenant path"""
 
-        return route
+        if not self.tenant_id:
+            raise ValueError("Missing Tenant Id")
 
-    def tenant(self, tenant_id: str) -> str:
+        return f"{self.origin}/tenants/{self.tenant_id}"
+
+    @property
+    def user_path(self) -> str:
+        """Returns the user path"""
+
+        if not self.user_id:
+            raise ValueError("Missing User Id")
+        return f"{self.tenant_path}/users/{self.user_id}"
+
+    @property
+    def tenant(self) -> str:
         """Returns the tenant endpoint"""
-        return f"{self.__base(tenant_id=tenant_id)}"
+        return f"{self.tenant_path}"
 
+    @property
     def app_configuration(self) -> str:
-        """Returns the configuration endpoint"""
-        return f"{self.__base()}/app/configuration"
+        """
+        Returns the configuration endpoint.  This is a public endpoint.
+        """
+        return f"{self.origin}/app/configuration"
 
-    def user(self, tenant_id: str, user_id: str) -> str:
+    @property
+    def user(self) -> str:
         """Returns the user endpoint"""
-        return f"{self.__base(tenant_id=tenant_id, user_id=user_id)}"
+        return f"{self.user_path}"
 
-    def executions(self, tenant_id: str, user_id: str) -> str:
+    @property
+    def executions(self) -> str:
         """Returns the executions endpoint"""
-        return f"{self.__base(tenant_id=tenant_id, user_id=user_id)}/nca/executions"
+        return f"{self.user_path}/nca/executions"
 
-    def execution(self, tenant_id: str, user_id: str, execution_id: str) -> str:
+    def execution(self, execution_id: str) -> str:
         """Returns the executions endpoint"""
-        return f"{self.executions(tenant_id=tenant_id, user_id=user_id)}/{execution_id}"
+        return f"{self.executions}/{execution_id}"
 
-    def files(self, tenant_id: str, user_id: str) -> str:
+    @property
+    def validations(self) -> str:
+        """Returns the validations endpoint"""
+        return f"{self.user_path}/nca/validations"
+
+    @property
+    def files(self) -> str:
         """Returns the files endpoint"""
-        return f"{self.__base(tenant_id=tenant_id, user_id=user_id)}/nca/files"
+        return f"{self.user_path}/nca/files"
 
-    def file(self, tenant_id: str, user_id: str, file_id: str) -> str:
+    def file(self, file_id: str) -> str:
         """Returns the file endpoint"""
-        return f"{self.files(tenant_id=tenant_id, user_id=user_id)}/{file_id}"
-    
-    def file_data(self, tenant_id: str, user_id: str, file_id: str) -> str:
+        return f"{self.files}/{file_id}"
+
+    def file_data(self, file_id: str) -> str:
         """Returns get file data endpoint"""
-        return f"{self.__base(tenant_id=tenant_id, user_id=user_id)}/nca/files/{file_id}/data"
+        return f"{self.files}/{file_id}/data"