aplos-nca-saas-sdk 1.0.0__py3-none-any.whl

aplos_nca_saas_sdk/utilities/commandline_args.py

@@ -0,0 +1,332 @@
+import os
+import argparse
+import getpass
+from pathlib import Path
+from typing import List
+from aplos_nca_saas_sdk.utilities.environment_vars import EnvironmentVars
+from dotenv import load_dotenv
+
+# load the environment (.env) file if any
+# this may or may not be the desired results
+load_dotenv(override=True)
+
+
+class CommandlineArgs:
+    def __init__(self) -> None:
+        # command line args
+        self.parser = argparse.ArgumentParser(
+            description="Example script to demonstrate command line argument parsing."
+        )
+
+        # Add the arguments
+        self.parser.add_argument(
+            "-u", "--username", required=False, help="The username"
+        )
+        self.parser.add_argument(
+            "-p", "--password", required=False, help="The password"
+        )
+        self.parser.add_argument(
+            "-c", "--config-file", required=False, help="Path to the configuration file"
+        )
+        self.parser.add_argument(
+            "-f", "--analyis-file", required=False, help="Path to the analysis file"
+        )
+        self.parser.add_argument(
+            "-m", "--metadata-file", required=False, help="Path to the metadata file"
+        )
+
+        self.parser.add_argument("-a", "--api-url", required=False, help="The api url")
+        self.parser.add_argument(
+            "-i", "--client-id", required=False, help="The client id to cognito"
+        )
+
+        self.parser.add_argument(
+            "-v", "--verbose", required=False, help="Detailed logging information"
+        )
+
+        self.parser.add_argument(
+            "-r", "--region", required=False, help="AWS Region. For Cognito Login"
+        )
+
+        self.parser.add_argument(
+            "-s",
+            "--skip",
+            required=False,
+            action="store_true",
+            help="Skip prompts if required values have defaults",
+        )
+        self.parser.add_argument(
+            "-o",
+            "--output-directory",
+            required=False,
+            help="The full path to an output directory",
+        )
+
+        self.parser.add_argument(
+            "-e",
+            "--environment-file",
+            required=False,
+            help="The full path to an environment file (.env file).",
+        )
+
+        self.username: str | None = None
+        self.password: str | None = None
+        self.api_domain: str | None = None
+        self.cognito_client_id: str | None = None
+        self.aws_region: str | None = None
+
+        self.config_file: str | None = None
+        self.config_file_default: str | None = None
+        self.analysis_file: str | None = None
+        self.analysis_file_default: str | None = None
+        self.metadata_file: str | None = None
+        self.metadata_file_default: str | None = None
+        self.skip: bool = False
+        self.output_directory: str | None = None
+        self.output_directory_default: str = ".output"
+        self.environment_file: str | None = None
+
+        self.display_directions: bool = True
+
+    def is_valid(self) -> bool:
+        """
+        Validates and Prompts the user if needed
+        Returns:
+            bool: True if they are all valid
+        """
+        # see if we have any aruments
+        args = self.parser.parse_args()
+
+        self.username = args.username
+        self.password = args.password
+        self.config_file = args.config_file
+        # anything with a dash (in the args) is accessed with an underscore
+        self.analysis_file = args.analyis_file
+        self.api_domain = args.api_domain
+        self.cognito_client_id = args.client_id
+        self.aws_region = args.region
+        self.metadata_file = args.metadata_file
+        self.skip = args.skip
+        self.output_directory = args.output_directory
+        self.environment_file = args.environment_file
+        # no args check to see if they have them in the environmet
+
+        # if we have an environment file we'll want to load it before checking any defaults
+        self.check_for_environment_config()
+
+        env = EnvironmentVars()
+
+        if not self.username:
+            if self.skip and env.username:
+                self.username = env.username
+            else:
+                self.username = self.prompt_for_input("username", env.username)
+        if not self.password:
+            if self.skip and env.password:
+                self.password = env.password
+            else:
+                self.password = self.prompt_for_input(
+                    "password", env.password, is_sensitive=True
+                )
+        if not self.aws_region:
+            if self.skip and env.aws_region:
+                self.aws_region = env.aws_region
+            else:
+                self.aws_region = self.prompt_for_input("AWS Region", env.aws_region)
+        if not self.api_domain:
+            if self.skip and env.api_domain:
+                self.api_domain = env.api_domain
+            else:
+                self.api_domain = self.prompt_for_input("Api Domain", env.api_domain)
+
+        if not self.cognito_client_id:
+            if self.skip and env.client_id:
+                self.cognito_client_id = env.client_id
+            else:
+                self.cognito_client_id = self.prompt_for_input(
+                    "Cognito Client Id", env.client_id
+                )
+
+        if not self.analysis_file:
+            if self.skip and self.analysis_file_default or env.analysis_file:
+                self.analysis_file = self.analysis_file_default or env.analysis_file
+            else:
+                self.analysis_file = self.prompt_for_input(
+                    "Analysis File", self.analysis_file_default or env.analysis_file
+                )
+
+        if not self.config_file:
+            if self.skip and self.config_file_default or env.config_file:
+                self.config_file = self.config_file_default or env.config_file
+            else:
+                self.config_file = self.prompt_for_input(
+                    "Configuration File", self.config_file_default or env.config_file
+                )
+
+        if not self.metadata_file:
+            if self.skip and self.metadata_file_default or env.metadata_file:
+                self.metadata_file = self.metadata_file_default or env.metadata_file
+            else:
+                self.metadata_file = self.prompt_for_input(
+                    "MetaData File",
+                    self.metadata_file_default or env.metadata_file,
+                    required=False,
+                )
+        if not self.output_directory:
+            if self.skip:
+                self.output_directory = self.output_directory_default
+            else:
+                self.output_directory = self.prompt_for_input(
+                    "Output directory (the full path)",
+                    self.output_directory_default,
+                    required=False,
+                )
+
+        # do we have everything we need?
+
+        return self.__check_all_required()
+
+    def __check_all_required(self) -> bool:
+        """
+        Check to see if all the fields are required
+        Returns:
+            bool: True if all required fields are populated, otherwise false
+        """
+        # basically everything except metadata
+        required_fields = [
+            self.username,
+            self.password,
+            self.aws_region,
+            self.cognito_client_id,
+            self.analysis_file,
+            self.config_file,
+            self.api_domain,
+        ]
+        for field in required_fields:
+            if not field:
+                return False
+
+        return True
+
+    def prompt_for_input(
+        self,
+        prompt: str,
+        default: str | None = None,
+        is_sensitive: bool = False,
+        required: bool = True,
+    ) -> str | None:
+        """
+        Create a prompt to display
+        Args:
+            prompt (str): The Prompt
+            default (str | None, optional): Default Value. Defaults to None.
+            is_sensitive (bool, optional): If the data is sensitive it won't be displayed on the screen. Defaults to False.
+            required (bool, optional): If the field is required. Defaults to True.
+
+        Returns:
+            str | None: The result of the prompt
+        """
+        # Construct the prompt message to include the default option if provided
+        if self.display_directions:
+            self.display_directions = False
+            print("Hit enter if you wish to accept a default value (if available)")
+            print("")
+        default_display = default if not is_sensitive else "************"
+        required_display = " - Required" if required else " - Optional"
+
+        display = (
+            f" [{default_display}]: "
+            if default
+            else f" [No Default{required_display}]: "
+        )
+        user_input: str | None = None
+        if is_sensitive:
+            user_input = getpass.getpass(f"{prompt}{display}")
+        else:
+            prompt_message = f"{prompt}{display}"
+
+            # Get user input
+            user_input = input(prompt_message)
+
+        # Return the user input if not empty, otherwise return the default value
+        user_input = user_input if user_input else default
+
+        if not user_input and required:
+            return self.prompt_for_input(
+                prompt=prompt,
+                default=default,
+                is_sensitive=is_sensitive,
+                required=required,
+            )
+
+        return user_input
+
+    def find_file(
+        self, starting_path: str, file_name: str, raise_error_if_not_found: bool = True
+    ) -> str | None:
+        """Searches the project directory structor for a file"""
+        parents = 10
+        starting_path = starting_path or __file__
+
+        paths: List[str] = []
+        for parent in range(parents):
+            path = Path(starting_path).parents[parent].absolute()
+
+            tmp = os.path.join(path, file_name)
+            paths.append(tmp)
+            if os.path.exists(tmp):
+                return tmp
+
+        if raise_error_if_not_found:
+            searched_paths = "\n".join(paths)
+            raise RuntimeError(
+                f"Failed to locate environment file: {file_name} in: \n {searched_paths}"
+            )
+
+        return None
+
+    def check_for_environment_config(self):
+        """Attempts to load an environment file"""
+        if not self.environment_file:
+            return  # Exit early if no environment file is provided
+
+        env_file_path = Path(self.environment_file)
+
+        if not env_file_path.exists():
+            # Try to find the file
+            file = self.find_file(__file__, env_file_path.name)
+            file_path = Path(str(file))
+
+            if not file_path.exists():
+                print("\n\nAn environment file was provided but it doesn't exist.")
+                print(f"\tFile provided: {self.environment_file}")
+                exit()
+            else:
+                self.environment_file = str(file_path)
+
+        load_dotenv(dotenv_path=self.environment_file, override=True)
+
+
+def main():
+    args = CommandlineArgs()
+
+    if args.is_valid():
+        pwd = "************" if args.password else "empty"
+        print(f"username = {args.username}")
+        print(f"password = {pwd}")
+        print(f"aws_region = {args.aws_region}")
+        print(f"api_domain = {args.api_domain}")
+        print(f"cognito_client_id = {args.cognito_client_id}")
+        print(f"config_file = {args.config_file}")
+        print(f"metadata_file = {args.metadata_file}")
+        print(f"analysis_file = {args.analysis_file}")
+        print(f"output_directory = {args.output_directory}")
+
+        print("were good to go")
+
+    else:
+        print("Missing some required fields.")
+
+
+if __name__ == "__main__":
+    main()

aplos_nca_saas_sdk/utilities/environment_services.py

@@ -0,0 +1,81 @@
+"""
+Aplos Analytics
+
+"""
+
+import os
+import json
+from typing import Dict, List, Any
+from pathlib import Path
+from dotenv import load_dotenv
+
+
+class EnvironmentServices:
+    """Environment Services"""
+
+    def load_environment(
+        self,
+        *,
+        starting_path: str | None = None,
+        file_name: str = ".env.dev",
+        override_vars: bool = True,
+        raise_error_if_not_found: bool = True,
+    ):
+        """Loads the local environment"""
+
+        if not starting_path:
+            starting_path = __file__
+
+        environment_file: str | None = self.find_file(
+            starting_path=starting_path,
+            file_name=file_name,
+            raise_error_if_not_found=raise_error_if_not_found,
+        )
+
+        if environment_file:
+            load_dotenv(dotenv_path=environment_file, override=override_vars)
+
+    def load_event_file(self, full_path: str) -> Dict[str, Any]:
+        """Loads an event file"""
+        if not os.path.exists(full_path):
+            raise RuntimeError(f"Failed to locate event file: {full_path}")
+
+        event: Dict = {}
+        with open(full_path, mode="r", encoding="utf-8") as json_file:
+            event = json.load(json_file)
+
+        if "message" in event:
+            tmp = event.get("message")
+            if isinstance(tmp, Dict):
+                event = tmp
+
+        if "event" in event:
+            tmp = event.get("event")
+            if isinstance(tmp, Dict):
+                event = tmp
+
+        return event
+
+    def find_file(
+        self, starting_path: str, file_name: str, raise_error_if_not_found: bool = True
+    ) -> str | None:
+        """Searches the project directory structor for a file"""
+        parents = 10
+        starting_path = starting_path or __file__
+
+        paths: List[str] = []
+        for parent in range(parents):
+            path = Path(starting_path).parents[parent].absolute()
+
+            tmp = os.path.join(path, file_name)
+            paths.append(tmp)
+            if os.path.exists(tmp):
+                return tmp
+
+        if raise_error_if_not_found:
+            searched_paths = "\n".join(paths)
+            raise RuntimeError(
+                f"Failed to locate environment file: {file_name} in: \n {searched_paths}"
+            )
+
+        return None

aplos_nca_saas_sdk/utilities/environment_vars.py

@@ -0,0 +1,23 @@
+import os
+
+
+class EnvironmentVars:
+    """Loading Environment Vars or replace them with runtime values"""
+
+    def __init__(self) -> None:
+        # load defaults
+        self.api_domain = os.getenv("APLOS_API_DOMAIN")
+
+        self.aws_region = os.getenv("COGNITO_REGION")
+        self.client_id = os.getenv("COGNITO_CLIENT_ID")
+        self.username = os.getenv("COGNITO_USER_NAME")
+        self.password = os.getenv("COGNITO_PASSWORD")
+
+        self.config_file = os.getenv("CONFIG_FILE")
+        self.metadata_file = os.getenv("METADATA_FILE")
+        self.analysis_file = os.getenv("ANALYSIS_FILE")
+
+        if "https://" in self.api_domain:
+            self.api_domain = self.api_domain.replace("https://", "")
+
+        self.aplos_api_url = f"https://{self.api_domain}"

aplos_nca_saas_sdk/utilities/http_utility.py

@@ -0,0 +1,30 @@
+class Routes:
+    """NCA Saas Routes"""
+
+    NCA_EXECUTIONS = "nca/executions"
+    NCA_GENERATE_UPLOAD = "nca/files"
+
+
+class HttpUtilities:
+    """Http Utilties"""
+
+    @staticmethod
+    def build_url(domain_name: str) -> str:
+        """Build the url"""
+        domain_name = domain_name.strip()
+        if domain_name.startswith("http"):
+            return domain_name
+        else:
+            return f"https://{domain_name}"
+
+    @staticmethod
+    def get_headers(jwt: str) -> dict:
+        """Get the Http Headers"""
+        headers = {
+            "Content-Type": "application/json",
+        }
+
+        if jwt:
+            headers["Authorization"] = f"Bearer {jwt}"
+
+        return headers

aplos_nca_saas_sdk/version.py

@@ -0,0 +1,4 @@
+# Aplos NCA SaaS SDK Version File
+# This is automatically generated during the build process. 
+# DO NOT UPDATE IT DIRECTLY. IT WILL BE OVERWRITTEN. 
+__version__ = '1.0.0'

aplos_nca_saas_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.3
+Name: aplos_nca_saas_sdk
+Version: 1.0.0
+Summary: Aplos NCA SaaS SDK
+Author-email: Eric Wilson <eric.wilson@aplosanalytics.com>
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: aws-lambda-powertools==2.38.1
+Requires-Dist: boto3==1.34.110
+Requires-Dist: pyjwt==2.9.0
+Requires-Dist: python-dotenv==1.0.1
+Requires-Dist: requests==2.31.0
+Description-Content-Type: text/markdown
+
+# Aplos NCA SaaS SDK for python
+
+You can use 🐍 python to perform analysis with Aplos NCA using API calls via secure HTTPS requests. We have prepared sample scripts to illustrate how this analysis can be performed using python. 
+
+This was created as a reusable library which was wrapped with commandline parsing.  You can use command line switches or simply run it and get prompted for the required input.
+
+All the source code can be downloaded from our [docs repo](https://github.com/AplosAnalytics/docs.aplosanalytics.com/tree/main/docs/samples/python/aplos_nca).
+
+>[!TIP] We use this for our demos
+> We'll keep this maintained as we use it for our customer demos.  So keep coming back for new features.
+
+
+## API Settings
+
+> [!WARNING] A valid Aplos NCA Account is required.
+> In order to run the executions and connect to our system, you will need a valid account with an active subscription.
+>
+> You'll need your username (email address and a password) a Cognito Client Id
+> which allows the USER_PASSWORD_AUTH flow, and your API URL.  
+> 
+> The Client Id (aka Cognito Client Key) and API URL can be found in your user account.
+> Your username is your email address and your password would have been provided to you during your
+> onboarding or with a "forgot password" request and reset.
+
+### Access your settings from the UI
+![API Configuration](/docs/images/API_Configuration_blur.png)
+
+
+## Python Environment
+While it's not required, we suggest setting up a virtual environment with your favorite tool.
+
+Example.  From the project root issue the following command (in mac, linux or windows shell subsystem)
+```shell
+python -m venv .venv
+source ./.venv/bin/activate
+```
+
+Install the required packages 
+```shell
+# (from the project root)
+pip install -r ./docs/samples/python/aplos_nca/requirements.txt
+
+# or if you are in the aplos_nca directory
+pip install -r ./requirements.txt
+```
+
+
+## Required Files for execution (analysis submission)
+To submit something for an analysis, you will need 2 required files and one optional file.  
+- Input File (analysis file)
+- Configuration File (configurations on how to run the analysis)
+- Meta Data (optional)
+
+Technically only the analysis file is submitted as a file.  
+
+The other two (configuration and metadata) are submitted as JSON/dictionary objects.  However to make things easier for this demo they are stored as files, then read in at runtime and submitted in their normal dictionary form.
+
+The files are located `./files` directory of this demo project (`./samples/python/aplos_nca`).
+
+
+## Outputs
+Currently, we are outputting the files in a hidden directory (`.output`) which is also excluded from the git commits.  This can easily be overridden to your choosing.
+
+Located in `./.output`
+
+
+## Run the Execution
+
+In order to run the execution you need to either:
+- Add environment variables for the required parameter see [Environment Vars](/docs/samples/python-overview.html#environment-vars) later in this document
+- Use the command switch arguments
+- Or simply input the values as you are prompted.
+
+> [!TIP] Tip! Use environment vars and override when needed.
+> You can set the environment variables, but still override them during the prompts
+
+From the project you you can 
+`python .<project-path>/main.py`
+
+or navigate to the folder
+`python ./main.py`
+
+## Arguments
+
+|short|long|description|
+|---|---|---|
+|-s|--skip|Skip prompts if required values have defaults|
+|-u|--username|Your login username|
+|-p|--password|Your login password|
+|-f|--analyis-file|Path to the analysis file|
+|-c|--config-file|Path to the configuration file|
+|-m|--metadata-file|Path to the metadata file|
+|-a|--api-url|The api url|
+|-i|--client-id|The client id to cognito|
+|-o|-output-directory|The full path to an output directory. If one isn't provided it will default to a local (.aplos-nca-output) directory one level up from the execution directory. |
+|-e|--environment-file|The full path to an environment file (.env file).|
+
+### The `-s` argument (skipping prompts when defaults are available)
+If you have default values specified in code or a `.env` file, specify the `-s` will skip prompting for any parameters that are required but have an associated matching default value.
+
+
+### Scripting
+You can create scripts to launch several analyses by providing the runtime arguments. WARNING: you should be careful when exposing your username and password to others.
+For automation, it's best to store them as a secret and retrieve the secret at runtime.
+
+
+## Examples:
+Let's assume you have your username, password, and API settings in environment vars.  You can use the `-s` to skip those prompts and supply the config, meta, and analysis for different runs.
+
+> [!TIP]
+> If you have certain values present the command line tool will prompt to see if you want to use the defaults or override them.
+> If you want to skip the prompt, use `-s` as an argument.  This will skip the prompt for any value already set.
+
+### Sample execution
+
+If your username, password, client key and API URL are already set, then the only thing you need to do on each run is supply the configuration and the analysis file.  The meta-data file is optional.  Issuing the `-s` will skip all the extra prompts.
+
+```shell
+# single line execution example
+
+python main.py -s -c <config-file> -f <analysis-file> -m <meta-file>
+
+```
+
+### Same example, on multiple lines and with example files
+
+```shell
+
+# break into multiple lines for easier readability
+# NOTE: a copy paste of this from code samples doesn't always work right
+
+python ./main.py \
+    -s \
+    -f ./files/single_ev.csv \
+    -c ./files/configuration_single_ev.json \
+    -m ./files/meta_data.json
+
+```
+
+## Environment Vars
+
+To save time and typing you can use environment variables to "pre-load" your execution and then any "unknown" value will be asked by the command line utility.
+
+The following environment variables are required for execution.  We're using environment vars so that nothing gets accidentally saved into git.
+
+If executing the functions via the command line, you need to create the environment variables so that they are available at runtime, like the following.
+
+Mac & Linux
+```shell
+export APLOS_API_DOMAIN="<api-gateway-url>"
+export COGNITO_CLIENT_ID="<client-id>"
+export COGNITO_USER_NAME="<email-address>"
+export COGNITO_PASSWORD="<password>"
+export COGNITO_REGION="<region>"
+```
+Windows
+```shell
+SET APLOS_API_DOMAIN="<api-gateway-url>"
+SET COGNITO_CLIENT_ID="<client-id>"
+SET COGNITO_USER_NAME="<email-address>"
+SET COGNITO_PASSWORD="<password>"
+SET COGNITO_REGION="<region>"
+```
+
+> [!TIP]
+> You can also create a `.env` file locally and enter the environment vars there.
+
+```shell
+APLOS_API_DOMAIN="<api-gateway-url>"
+COGNITO_CLIENT_ID="<client-id>"
+COGNITO_USER_NAME="<email-address>"
+COGNITO_PASSWORD="<password>"
+COGNITO_REGION="<region>"
+```
+
+## The Command Line in Action
+In this example, I have all my settings preloaded in environment vars and I just hit enter several times to accept the defaults.
+
+![Commandline App](/docs/images/aplos-nca-commandline-cropped.png)