Add docstring docs

Author: kks32

dapi/__init__.py

@@ -1,5 +1,56 @@
-"""
-Dapi - A Python wrapper for interacting with DesignSafe resources via the Tapis API.
+"""Dapi - A Python wrapper for interacting with DesignSafe resources via the Tapis API.
+
+This package provides a high-level, user-friendly interface for working with DesignSafe 
+resources through the Tapis V3 API. It simplifies complex operations and provides 
+organized access to different service areas including authentication, file operations,
+job submission and monitoring, application discovery, system information, and database access.
+
+Key Features:
+    - Simplified authentication with credential resolution hierarchy
+    - DesignSafe path translation (MyData, projects, etc.) to Tapis URIs  
+    - High-level job submission with automatic app parameter mapping
+    - Job monitoring with progress bars and status interpretation
+    - File upload/download with automatic directory creation
+    - Application discovery and detailed retrieval
+    - System queue information and resource limits
+    - Database access for DesignSafe research databases
+    - Comprehensive error handling with descriptive exceptions
+
+Main Components:
+    DSClient: Main client class providing organized access to all services
+    SubmittedJob: Class for managing and monitoring submitted Tapis jobs
+    Exception classes: Specific exceptions for different error types
+
+Example:
+    Basic usage with automatic authentication:
+    
+    >>> from dapi import DSClient
+    >>> client = DSClient()
+    Enter DesignSafe Username: myuser
+    Enter DesignSafe Password: [hidden]
+    Authentication successful.
+    
+    >>> # File operations
+    >>> client.files.upload("/local/file.txt", "/MyData/uploads/file.txt")
+    >>> files = client.files.list("/MyData/uploads/")
+    
+    >>> # Job submission and monitoring
+    >>> job_request = client.jobs.generate_request(
+    ...     app_id="matlab-r2023a",
+    ...     input_dir_uri="/MyData/analysis/input/",
+    ...     script_filename="run_analysis.m"
+    ... )
+    >>> job = client.jobs.submit_request(job_request)
+    >>> final_status = job.monitor()
+    
+    >>> # Database access
+    >>> df = client.db.ngl.read_sql("SELECT * FROM earthquake_data LIMIT 10")
+
+Attributes:
+    __version__ (str): The version number of the dapi package.
+    DSClient: Main client class for DesignSafe API interactions.
+    SubmittedJob: Class for managing submitted Tapis jobs.
+    Exception classes: Custom exceptions for specific error conditions.
 """
 from .client import DSClient
 

dapi/apps.py

@@ -7,20 +7,35 @@
 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.
+    """Search for Tapis apps matching a search term.
+
+    Searches through available Tapis applications using partial name matching.
+    This function helps discover applications available for job submission.
 
     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.
+        t (Tapis): Authenticated Tapis client instance.
+        search_term (str): Name or partial name to search for. Use empty string
+            for all apps. Supports partial matching with wildcards.
+        list_type (str, optional): Type of apps to list. Must be one of:
+            'OWNED', 'SHARED_PUBLIC', 'SHARED_DIRECT', 'READ_PERM', 'MINE', 'ALL'.
+            Defaults to "ALL".
+        verbose (bool, optional): If True, prints summary of found apps including
+            ID, version, and owner information. Defaults to True.
 
     Returns:
-        List of matching Tapis app objects.
+        List[Tapis]: List of matching Tapis app objects with selected fields
+            (id, version, owner).
 
     Raises:
-        AppDiscoveryError: If the search fails.
+        AppDiscoveryError: If the Tapis API search fails or an unexpected
+            error occurs during the search operation.
+
+    Example:
+        >>> find_apps(client, "matlab", verbose=True)
+        Found 3 matching apps:
+        - matlab-r2023a (Version: 1.0, Owner: designsafe)
+        - matlab-parallel (Version: 2.1, Owner: tacc)
+        - matlab-desktop (Version: 1.5, Owner: designsafe)
     """
     try:
         # Use id.like for partial matching, ensure search term is handled
@@ -53,20 +68,35 @@ def find_apps(
 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).
+    """Get detailed information for a specific app ID and version.
+
+    Retrieves comprehensive details about a specific Tapis application,
+    including job attributes, execution system, and parameter definitions.
 
     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.
+        t (Tapis): Authenticated Tapis client instance.
+        app_id (str): Exact app ID to look up. Must match exactly.
+        app_version (Optional[str], optional): Specific app version to retrieve.
+            If None, fetches the latest available version. Defaults to None.
+        verbose (bool, optional): If True, prints basic app information including
+            ID, version, owner, execution system, and description. Defaults to True.
 
     Returns:
-        Tapis app object with full details, or None if not found.
+        Optional[Tapis]: Tapis app object with full details including jobAttributes,
+            parameterSet, and other configuration. Returns None if the app is not found.
 
     Raises:
-        AppDiscoveryError: If fetching the app details fails.
+        AppDiscoveryError: If the Tapis API call fails (except for 404 not found)
+            or an unexpected error occurs during retrieval.
+
+    Example:
+        >>> app = get_app_details(client, "matlab-r2023a", "1.0")
+        App Details:
+          ID: matlab-r2023a
+          Version: 1.0
+          Owner: designsafe
+          Execution System: frontera
+          Description: MATLAB R2023a runtime environment
     """
     try:
         if app_version:

dapi/auth.py

@@ -12,26 +12,54 @@ def init(
     password: str = None,
     env_file: str = None,
 ) -> Tapis:
-    """
-    Initialize and authenticate a Tapis client for DesignSafe.
+    """Initialize and authenticate a Tapis client for DesignSafe.
+
+    Creates and authenticates a Tapis client instance for interacting with
+    DesignSafe resources. The function follows a credential resolution hierarchy
+    and handles secure password input when needed.
 
-    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.
+    Credential Resolution Order:
+        1. Explicitly passed username/password arguments
+        2. Environment variables (DESIGNSAFE_USERNAME, DESIGNSAFE_PASSWORD)
+           - Loads from env_file if specified, otherwise checks system environment
+        3. Interactive prompts for missing credentials
 
     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.
+        base_url (str, optional): The Tapis base URL for DesignSafe API endpoints.
+            Defaults to "https://designsafe.tapis.io".
+        username (str, optional): Explicit DesignSafe username. If None, will
+            attempt to load from environment or prompt user. Defaults to None.
+        password (str, optional): Explicit DesignSafe password. If None, will
+            attempt to load from environment or prompt user securely. Defaults to None.
+        env_file (str, optional): Path to a .env file containing credentials.
+            If None, attempts to load from default .env file if it exists.
+            Defaults to None.
 
     Returns:
-        An authenticated tapipy.Tapis object.
+        Tapis: An authenticated tapipy.Tapis client object ready for API calls.
 
     Raises:
-        AuthenticationError: If authentication fails.
+        AuthenticationError: If authentication fails due to invalid credentials,
+            network issues, or if required credentials cannot be obtained.
+
+    Example:
+        >>> # Using explicit credentials
+        >>> client = init(username="myuser", password="mypass")
+        Authentication successful.
+
+        >>> # Using environment variables or .env file
+        >>> client = init(env_file=".env")
+        Authentication successful.
+
+        >>> # Interactive authentication
+        >>> client = init()
+        Enter DesignSafe Username: myuser
+        Enter DesignSafe Password: [hidden]
+        Authentication successful.
+
+    Note:
+        The function disables automatic spec downloads for faster initialization.
+        Password input uses getpass for secure entry in terminal environments.
     """
     # Load environment variables if a file path is provided
     if env_file: