Refactor abstraction for Dapi

Author: kks32

dapi/__init__.py

@@ -1,46 +1,19 @@
 """
-dapi` is a library that simplifies the process of submitting, running, and monitoring [TAPIS v3](https://tapis.readthedocs.io/en/latest/) jobs on [DesignSafe](https://designsafe-ci.org) via [Jupyter Notebooks](https://jupyter.designsafe-ci.org).
-
-## Features
-
-### Jobs
-
-* Get TAPIS v3 templates for jobs: No need to fiddle with complex API requests. `dapi` abstracts away the complexities.
-
-* Seamless Integration with DesignSafe Jupyter Notebooks: Launch DesignSafe applications directly from the Jupyter environment.
-
-### Database
-
-Connects to SQL databases on DesignSafe:
-
-| Database | dbname | env_prefix |
-|----------|--------|------------|
-| NGL | `ngl`| `NGL_` |
-| Earthake Recovery | `eq` | `EQ_` |
-| Vp | `vp` | `VP_` |
-
-Define the following environment variables:
-```
-{env_prefix}DB_USER
-{env_prefix}DB_PASSWORD
-{env_prefix}DB_HOST
-{env_prefix}DB_PORT
-```
-
-For e.g., to add the environment variable `NGL_DB_USER` edit `~/.bashrc`, `~/.zshrc`, or a similar shell-specific configuration file for the current user and add `export NGL_DB_USER="dspublic"`.
-
-## Installation
-
-```shell
-pip3 install dapi
-```
-
+Dapi - A Python wrapper for interacting with DesignSafe resources via the Tapis API.
 """
-# from . import apps
-# from . import auth
-# from . import db
-# from . import jobs
-
-from .core import DesignSafeAPI
-
-__all__ = ["DesignSafeAPI", "apps", "auth", "db", "jobs", "core"]
+# Import the renamed client class
+from .client import DSClient
+from .exceptions import DapiException, FileOperationError, JobSubmissionError, JobMonitorError
+# Import JobDefinition here too for easier access like dapi.JobDefinition
+from .jobs import JobDefinition
+
+__version__ = "1.1.0" # Example version
+
+__all__ = [
+    "DSClient", # Export the renamed class
+    "JobDefinition", # Export JobDefinition
+    "DapiException",
+    "FileOperationError",
+    "JobSubmissionError",
+    "JobMonitorError",
+]

dapi/apps.py

@@ -0,0 +1,90 @@
+from tapipy.tapis import Tapis
+from tapipy.errors import BaseTapyException
+from typing import List, Any, Optional
+from .exceptions import AppDiscoveryError
+
+def find_apps(
+    t: Tapis, search_term: str, list_type: str = "ALL", verbose: bool = True
+) -> List[Tapis]:
+    """
+    Search for Tapis apps matching a search term.
+
+    Args:
+        t: Authenticated Tapis client instance.
+        search_term: Name or partial name to search for. Use "" for all.
+        list_type: One of 'OWNED', 'SHARED_PUBLIC', 'SHARED_DIRECT', 'READ_PERM', 'MINE', 'ALL'.
+        verbose: If True, prints summary of found apps.
+
+    Returns:
+        List of matching Tapis app objects.
+
+    Raises:
+        AppDiscoveryError: If the search fails.
+    """
+    try:
+        # Use id.like for partial matching, ensure search term is handled
+        search_query = f"(id.like.*{search_term}*)" if search_term else None
+        results = t.apps.getApps(search=search_query, listType=list_type, select="id,version,owner") # Select fewer fields for speed
+
+        if verbose:
+            if not results:
+                print(f"No apps found matching '{search_term}' with listType '{list_type}'")
+            else:
+                print(f"\nFound {len(results)} matching apps:")
+                for app in results:
+                    print(f"- {app.id} (Version: {app.version}, Owner: {app.owner})")
+                print()
+        return results
+    except BaseTapyException as e:
+        raise AppDiscoveryError(f"Failed to search for apps matching '{search_term}': {e}") from e
+    except Exception as e:
+        raise AppDiscoveryError(f"An unexpected error occurred while searching for apps: {e}") from e
+
+
+def get_app_details(t: Tapis, app_id: str, app_version: Optional[str] = None, verbose: bool = True) -> Optional[Tapis]:
+    """
+    Get detailed information for a specific app ID and version (or latest).
+
+    Args:
+        t: Authenticated Tapis client instance.
+        app_id: Exact app ID to look up.
+        app_version: Specific app version. If None, fetches the latest version.
+        verbose: If True, prints basic app info.
+
+    Returns:
+        Tapis app object with full details, or None if not found.
+
+    Raises:
+        AppDiscoveryError: If fetching the app details fails.
+    """
+    try:
+        if app_version:
+            app_info = t.apps.getApp(appId=app_id, appVersion=app_version)
+        else:
+            app_info = t.apps.getAppLatestVersion(appId=app_id)
+
+        if verbose:
+            print(f"\nApp Details:")
+            print(f"  ID: {app_info.id}")
+            print(f"  Version: {app_info.version}")
+            print(f"  Owner: {app_info.owner}")
+            if hasattr(app_info, 'jobAttributes') and hasattr(app_info.jobAttributes, 'execSystemId'):
+                 print(f"  Execution System: {app_info.jobAttributes.execSystemId}")
+            else:
+                 print("  Execution System: Not specified in jobAttributes")
+            print(f"  Description: {app_info.description}")
+        return app_info
+    except BaseTapyException as e:
+        # Check for 404 specifically
+        if hasattr(e, 'response') and e.response and e.response.status_code == 404:
+             print(f"App '{app_id}' (Version: {app_version or 'latest'}) not found.")
+             # Optionally, try searching for similar apps
+             # print("\nAttempting to find similar apps:")
+             # find_apps(t, app_id, verbose=True)
+             return None
+        else:
+             print(f"Error getting app info for '{app_id}' (Version: {app_version or 'latest'}): {e}")
+             raise AppDiscoveryError(f"Failed to get details for app '{app_id}': {e}") from e
+    except Exception as e:
+        print(f"An unexpected error occurred getting app info for '{app_id}': {e}")
+        raise AppDiscoveryError(f"Unexpected error getting details for app '{app_id}': {e}") from e

dapi/apps/__init__.py

@@ -0,0 +1,77 @@
+import os
+from getpass import getpass
+from tapipy.tapis import Tapis
+from tapipy.errors import BaseTapyException
+from dotenv import load_dotenv
+from .exceptions import AuthenticationError
+
+def init(base_url: str = "https://designsafe.tapis.io",
+         username: str = None,
+         password: str = None,
+         env_file: str = None) -> Tapis:
+    """
+    Initialize and authenticate a Tapis client for DesignSafe.
+
+    Tries credentials in this order:
+    1. Explicitly passed username/password arguments.
+    2. Environment variables (DESIGNSAFE_USERNAME, DESIGNSAFE_PASSWORD).
+       Loads from `env_file` (e.g., '.env') if specified, otherwise checks system env.
+    3. Prompts user for username/password if none found.
+
+    Args:
+        base_url: The Tapis base URL for DesignSafe.
+        username: Explicit DesignSafe username.
+        password: Explicit DesignSafe password.
+        env_file: Path to a .env file to load credentials from.
+
+    Returns:
+        An authenticated tapipy.Tapis object.
+
+    Raises:
+        AuthenticationError: If authentication fails.
+    """
+    # Load environment variables if a file path is provided
+    if env_file:
+        load_dotenv(dotenv_path=env_file)
+    else:
+        # Try loading from default .env if it exists, but don't require it
+        load_dotenv()
+
+    # Determine credentials
+    final_username = username or os.getenv("DESIGNSAFE_USERNAME")
+    final_password = password or os.getenv("DESIGNSAFE_PASSWORD")
+
+    # Prompt if still missing
+    if not final_username:
+        final_username = input("Enter DesignSafe Username: ")
+    if not final_password:
+        # Use getpass for secure password entry in terminals
+        try:
+            final_password = getpass("Enter DesignSafe Password: ")
+        except (EOFError, KeyboardInterrupt):
+             raise AuthenticationError("Password input cancelled.")
+        except Exception: # Fallback for non-terminal environments
+             final_password = input("Enter DesignSafe Password: ")
+
+
+    if not final_username or not final_password:
+        raise AuthenticationError("Username and password are required.")
+
+    # Initialize Tapis object
+    try:
+        t = Tapis(base_url=base_url,
+                  username=final_username,
+                  password=final_password,
+                  download_latest_specs=False) # Avoid slow spec downloads by default
+
+        # Attempt to get tokens to verify credentials
+        t.get_tokens()
+        print("Authentication successful.")
+        return t
+
+    except BaseTapyException as e:
+        # Catch Tapis-specific errors during init or get_tokens
+        raise AuthenticationError(f"Tapis authentication failed: {e}") from e
+    except Exception as e:
+        # Catch other potential errors
+        raise AuthenticationError(f"An unexpected error occurred during authentication: {e}") from e