Add ds.jobs.list() and standardize docs to use ds variable

Add list_jobs() to fetch Tapis jobs as a pandas DataFrame with
optional filtering by app_id and status. Includes 14 tests.
Rename client variable to ds across all documentation examples.

Author: kks32

dapi/client.py

@@ -40,21 +40,21 @@ class DSClient:
     Example:
         Basic usage with automatic authentication:
 
-        >>> client = DSClient()
+        >>> ds = DSClient()
         Enter DesignSafe Username: myuser
         Enter DesignSafe Password: [hidden]
         Authentication successful.
 
         Using explicit credentials:
 
-        >>> client = DSClient(username="myuser", password="mypass")
+        >>> ds = DSClient(username="myuser", password="mypass")
         Authentication successful.
 
         Using a pre-authenticated Tapis client:
 
         >>> tapis = Tapis(base_url="https://designsafe.tapis.io", ...)
         >>> tapis.get_tokens()
-        >>> client = DSClient(tapis_client=tapis)
+        >>> ds = DSClient(tapis_client=tapis)
     """
 
     def __init__(self, tapis_client: Optional[Tapis] = None, **auth_kwargs):
@@ -196,7 +196,7 @@ def translate_uri_to_path(self, *args, **kwargs) -> str:
             str: The corresponding DesignSafe local path (e.g., /home/jupyter/MyData/path).
 
         Example:
-            >>> local_path = client.files.translate_uri_to_path("tapis://designsafe.storage.default/user/data")
+            >>> local_path = ds.files.translate_uri_to_path("tapis://designsafe.storage.default/user/data")
             >>> print(local_path)  # "/home/jupyter/MyData/data"
         """
         return files_module.tapis_uri_to_local_path(*args, **kwargs)
@@ -453,7 +453,7 @@ def generate_request(
             JobSubmissionError: If job request generation fails.
 
         Example:
-            >>> job_request = client.jobs.generate_request(
+            >>> job_request = ds.jobs.generate_request(
             ...     app_id="matlab-r2023a",
             ...     input_dir_uri="tapis://designsafe.storage.default/username/input/",
             ...     script_filename="run_analysis.m",
@@ -506,8 +506,8 @@ def submit_request(self, job_request: Dict[str, Any]) -> SubmittedJob:
             JobSubmissionError: If the Tapis submission fails or encounters an error.
 
         Example:
-            >>> job_request = client.jobs.generate_request(...)
-            >>> submitted_job = client.jobs.submit_request(job_request)
+            >>> job_request = ds.jobs.generate_request(...)
+            >>> submitted_job = ds.jobs.submit_request(job_request)
             >>> print(f"Job submitted with UUID: {submitted_job.uuid}")
         """
         return jobs_module.submit_job_request(self._tapis, job_request)
@@ -523,7 +523,7 @@ def get(self, job_uuid: str) -> SubmittedJob:
             SubmittedJob: A SubmittedJob object for monitoring and managing the job.
 
         Example:
-            >>> job = client.jobs.get("12345678-1234-1234-1234-123456789abc")
+            >>> job = ds.jobs.get("12345678-1234-1234-1234-123456789abc")
             >>> status = job.status
         """
         return SubmittedJob(self._tapis, job_uuid)
@@ -541,7 +541,7 @@ def get_status(self, job_uuid: str) -> str:
             JobMonitorError: If status retrieval fails.
 
         Example:
-            >>> status = client.jobs.get_status("12345678-1234-1234-1234-123456789abc")
+            >>> status = ds.jobs.get_status("12345678-1234-1234-1234-123456789abc")
             >>> print(f"Job status: {status}")
         """
         return jobs_module.get_job_status(self._tapis, job_uuid)
@@ -555,7 +555,7 @@ def get_runtime_summary(self, job_uuid: str, verbose: bool = False):
                 Defaults to False.
 
         Example:
-            >>> client.jobs.get_runtime_summary("12345678-1234-1234-1234-123456789abc")
+            >>> ds.jobs.get_runtime_summary("12345678-1234-1234-1234-123456789abc")
             Runtime Summary
             ---------------
             QUEUED  time: 00:05:30
@@ -572,7 +572,44 @@ def interpret_status(self, final_status: str, job_uuid: Optional[str] = None):
             job_uuid (str, optional): The job UUID for context in the message.
 
         Example:
-            >>> client.jobs.interpret_status("FINISHED", "12345678-1234-1234-1234-123456789abc")
+            >>> ds.jobs.interpret_status("FINISHED", "12345678-1234-1234-1234-123456789abc")
             Job 12345678-1234-1234-1234-123456789abc completed successfully.
         """
         jobs_module.interpret_job_status(final_status, job_uuid)
+
+    def list(
+        self,
+        app_id: Optional[str] = None,
+        status: Optional[str] = None,
+        limit: int = 100,
+        verbose: bool = False,
+    ):
+        """List jobs as a pandas DataFrame with optional filtering.
+
+        Fetches jobs from Tapis ordered by creation date (newest first)
+        and returns them as a DataFrame. Filters are applied client-side.
+
+        Args:
+            app_id (str, optional): Filter by application ID.
+            status (str, optional): Filter by job status (e.g., "FINISHED").
+                Case-insensitive.
+            limit (int, optional): Maximum jobs to fetch. Defaults to 100.
+            verbose (bool, optional): Print job count. Defaults to False.
+
+        Returns:
+            pd.DataFrame: Job metadata with formatted datetime columns.
+
+        Raises:
+            JobMonitorError: If the Tapis API call fails.
+
+        Example:
+            >>> df = ds.jobs.list(app_id="matlab-r2023a", status="FINISHED")
+            >>> print(df[["name", "uuid", "status", "created_dt"]])
+        """
+        return jobs_module.list_jobs(
+            self._tapis,
+            app_id=app_id,
+            status=status,
+            limit=limit,
+            verbose=verbose,
+        )

dapi/jobs.py

@@ -10,6 +10,7 @@
 from tapipy.errors import BaseTapyException
 from dataclasses import dataclass, field, asdict
 from tqdm.auto import tqdm
+import pandas as pd
 from .apps import get_app_details
 from .exceptions import (
     JobSubmissionError,
@@ -1340,3 +1341,87 @@ def interpret_job_status(final_status: str, job_uuid: Optional[str] = None):
         print(f"{job_id_str} ended with status: {final_status}")
     else:
         print(f"{job_id_str} ended with an unexpected status: {final_status}")
+
+
+def list_jobs(
+    tapis_client: Tapis,
+    app_id: Optional[str] = None,
+    status: Optional[str] = None,
+    limit: int = 100,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    """Fetch Tapis jobs and return them as a pandas DataFrame.
+
+    Retrieves jobs from Tapis ordered by creation date (newest first)
+    and optionally filters by app ID and/or status. Filters are applied
+    client-side after fetching.
+
+    Args:
+        tapis_client: Authenticated Tapis client instance.
+        app_id: Filter by application ID (e.g., "opensees-mp-s3").
+        status: Filter by job status (e.g., "FINISHED", "FAILED").
+            Case-insensitive.
+        limit: Maximum number of jobs to fetch from Tapis. Defaults to 100.
+        verbose: If True, prints the number of jobs found.
+
+    Returns:
+        DataFrame with job metadata and formatted datetime columns.
+        Priority columns appear first: name, uuid, status, appId, appVersion,
+        created_dt, ended_dt. Additional datetime columns include _dt
+        (timezone-aware) and _date (date only) variants for created, ended,
+        remoteStarted, and lastUpdated.
+
+    Raises:
+        JobMonitorError: If the Tapis API call fails.
+
+    Example:
+        >>> df = list_jobs(t, app_id="matlab-r2023a", status="FINISHED")
+        >>> print(df[["name", "uuid", "status", "created_dt"]])
+    """
+    try:
+        jobs_list = tapis_client.jobs.getJobList(
+            limit=limit,
+            orderBy="created(desc)",
+        )
+    except BaseTapyException as e:
+        raise JobMonitorError(f"Failed to list jobs: {e}") from e
+    except Exception as e:
+        raise JobMonitorError(f"Unexpected error listing jobs: {e}") from e
+
+    if not jobs_list:
+        if verbose:
+            print("Found 0 jobs.")
+        return pd.DataFrame()
+
+    # Convert TapisResult objects to dicts
+    jobs_dicts = [job.__dict__ for job in jobs_list]
+    df = pd.DataFrame(jobs_dicts)
+
+    # Apply client-side filters
+    if app_id and "appId" in df.columns:
+        df = df[df["appId"] == app_id]
+    if status and "status" in df.columns:
+        df = df[df["status"] == status.upper()]
+
+    # Add formatted datetime columns
+    time_cols = ["created", "ended", "remoteStarted", "lastUpdated"]
+    for col in time_cols:
+        if col in df.columns:
+            df[f"{col}_dt"] = pd.to_datetime(df[col], utc=True, errors="coerce")
+            df[f"{col}_date"] = df[f"{col}_dt"].dt.date
+
+    # Reorder: priority columns first
+    priority = [
+        "name", "uuid", "status", "appId", "appVersion",
+        "created_dt", "ended_dt",
+    ]
+    priority_present = [c for c in priority if c in df.columns]
+    remaining = [c for c in df.columns if c not in priority_present]
+    df = df[priority_present + remaining]
+
+    df = df.reset_index(drop=True)
+
+    if verbose:
+        print(f"Found {len(df)} jobs.")
+
+    return df

docs/api/index.md

@@ -29,20 +29,20 @@ The DAPI package is organized into several core modules:
 from dapi import DSClient
 
 # Initialize client
-client = DSClient()
+ds = DSClient()
 
 # Access different services
-client.jobs.generate_request(...)
-client.files.upload(...)
-client.db.ngl.read_sql(...)
+ds.jobs.generate_request(...)
+ds.files.upload(...)
+ds.db.ngl.read_sql(...)
 ```
 
 ### **Common Operations**
-- **Submit Jobs**: `client.jobs.submit_request(job_dict)`
+- **Submit Jobs**: `ds.jobs.submit_request(job_dict)`
 - **Monitor Jobs**: `submitted_job.monitor()`
-- **File Upload**: `client.files.upload(local_path, remote_uri)`
-- **File Download**: `client.files.download(remote_uri, local_path)`
-- **Database Query**: `client.db.ngl.read_sql("SELECT * FROM table")`
+- **File Upload**: `ds.files.upload(local_path, remote_uri)`
+- **File Download**: `ds.files.download(remote_uri, local_path)`
+- **Database Query**: `ds.db.ngl.read_sql("SELECT * FROM table")`
 
 ### **Advanced Features**
 - **Archive Management**: Custom job result organization

docs/api/jobs.md

@@ -28,6 +28,12 @@ Job submission, monitoring, and management functionality for DesignSafe computat
 .. autofunction:: dapi.jobs.interpret_job_status
 ```
 
+## Listing Jobs
+
+```{eval-rst}
+.. autofunction:: dapi.jobs.list_jobs
+```
+
 ## SubmittedJob Class
 
 ```{eval-rst}