Return DataFrames from ds.projects.list() and ds.projects.files()

- list_projects returns DataFrame by default (output="df"|"list")
- list_project_files returns DataFrame by default (output="df"|"raw")
- get_project returns dict with pi as display name string
- Update tests (142 passing) and example notebook
- Update docs/projects.md

Author: kks32

dapi/client.py

@@ -266,22 +266,25 @@ class ProjectMethods:
     def __init__(self, tapis_client: Tapis):
         self._tapis = tapis_client
 
-    def list(self, limit: int = 100, offset: int = 0) -> List[Dict]:
+    def list(self, limit: int = 100, offset: int = 0, output: str = "df"):
         """List DesignSafe projects you have access to.
 
         Args:
             limit (int, optional): Maximum projects to return. Defaults to 100.
             offset (int, optional): Number of projects to skip. Defaults to 0.
+            output (str, optional): "df" for DataFrame (default), "list" for
+                list of dicts.
 
         Returns:
-            List[Dict]: List of project dicts with uuid, projectId, title, pi, etc.
+            DataFrame or List[Dict]: Projects with projectId, title, pi, type, etc.
 
         Example:
-            >>> projects = ds.projects.list()
-            >>> for p in projects[:3]:
-            ...     print(f"{p['projectId']} - {p['title']}")
+            >>> ds.projects.list()  # returns a DataFrame
+            >>> ds.projects.list(output="list")  # returns list of dicts
         """
-        return projects_module.list_projects(self._tapis, limit=limit, offset=offset)
+        return projects_module.list_projects(
+            self._tapis, limit=limit, offset=offset, output=output
+        )
 
     def get(self, project_id: str) -> Dict:
         """Get detailed metadata for a project.
@@ -300,24 +303,27 @@ def get(self, project_id: str) -> Dict:
         """
         return projects_module.get_project(self._tapis, project_id)
 
-    def files(self, project_id: str, path: str = "/", limit: int = 100) -> List:
+    def files(
+        self, project_id: str, path: str = "/", limit: int = 100, output: str = "df"
+    ):
         """List files in a project.
 
         Args:
             project_id (str): Project ID (e.g., "PRJ-1305").
             path (str, optional): Path within the project. Defaults to "/".
             limit (int, optional): Max items to return. Defaults to 100.
+            output (str, optional): "df" for DataFrame (default), "raw" for
+                Tapis file objects.
 
         Returns:
-            List: List of Tapis file objects.
+            DataFrame or List: Files with name, type, size, lastModified, path.
 
         Example:
-            >>> files = ds.projects.files("PRJ-1305", "/Training/")
-            >>> for f in files[:5]:
-            ...     print(f"{f.name} ({f.type})")
+            >>> ds.projects.files("PRJ-1305", "/Training/")
+            >>> ds.projects.files("PRJ-1305", output="raw")
         """
         return projects_module.list_project_files(
-            self._tapis, project_id, path=path, limit=limit
+            self._tapis, project_id, path=path, limit=limit, output=output
         )
 
 

dapi/projects.py

@@ -1,9 +1,10 @@
 # dapi/projects.py
 import requests
+import pandas as pd
 from tapipy.tapis import Tapis
 from tapipy.errors import BaseTapyException
 from .exceptions import FileOperationError
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Union
 
 
 _DS_PROJECTS_API = "https://designsafe-ci.org/api/projects/v2/"
@@ -15,26 +16,44 @@ def _get_auth_headers(t: Tapis) -> Dict[str, str]:
     return {"X-Tapis-Token": token, "Authorization": f"Bearer {token}"}
 
 
-def list_projects(t: Tapis, limit: int = 100, offset: int = 0) -> List[Dict]:
+def _extract_pi(users: List[Dict]) -> Optional[Dict]:
+    """Extract the PI from a project's users list."""
+    return next((u for u in users if u.get("role") == "pi"), None)
+
+
+def _pi_display(pi: Optional[Dict]) -> str:
+    """Format PI dict as display name."""
+    if not pi:
+        return ""
+    return f"{pi.get('fname', '')} {pi.get('lname', '')}".strip()
+
+
+def list_projects(
+    t: Tapis,
+    limit: int = 100,
+    offset: int = 0,
+    output: str = "df",
+) -> Union[pd.DataFrame, List[Dict]]:
     """List DesignSafe projects the authenticated user has access to.
 
     Args:
         t (Tapis): Authenticated Tapis client instance.
         limit (int, optional): Maximum number of projects to return. Defaults to 100.
         offset (int, optional): Number of projects to skip. Defaults to 0.
+        output (str, optional): Output format. "df" returns a pandas DataFrame
+            (default), "list" returns a list of dicts.
 
     Returns:
-        List[Dict]: List of project dictionaries with keys:
-            - uuid (str): Project UUID
-            - projectId (str): Project ID (e.g., "PRJ-1305")
-            - title (str): Project title
-            - pi (dict): Principal investigator info (username, fname, lname)
-            - created (str): Creation timestamp
-            - lastUpdated (str): Last update timestamp
+        Union[pd.DataFrame, List[Dict]]: Projects in the requested format.
+            DataFrame columns: projectId, title, pi, type, created, lastUpdated, uuid.
 
     Raises:
         FileOperationError: If the API request fails.
+        ValueError: If output format is invalid.
     """
+    if output not in ("df", "list"):
+        raise ValueError(f"output must be 'df' or 'list', got '{output}'")
+
     headers = _get_auth_headers(t)
     try:
         resp = requests.get(
@@ -52,18 +71,28 @@ def list_projects(t: Tapis, limit: int = 100, offset: int = 0) -> List[Dict]:
     for p in data.get("result", []):
         val = p.get("value", {})
         users = val.get("users", [])
-        pi = next((u for u in users if u.get("role") == "pi"), None)
+        pi = _extract_pi(users)
         projects.append(
             {
-                "uuid": p.get("uuid"),
                 "projectId": val.get("projectId"),
                 "title": val.get("title"),
-                "pi": pi,
+                "pi": _pi_display(pi),
+                "type": val.get("projectType"),
                 "created": p.get("created"),
                 "lastUpdated": p.get("lastUpdated"),
+                "uuid": p.get("uuid"),
             }
         )
-    return projects
+
+    if output == "list":
+        return projects
+
+    df = pd.DataFrame(projects)
+    if not df.empty:
+        for col in ("created", "lastUpdated"):
+            if col in df.columns:
+                df[col] = pd.to_datetime(df[col], errors="coerce")
+    return df
 
 
 def get_project(t: Tapis, project_id: str) -> Dict:
@@ -79,7 +108,7 @@ def get_project(t: Tapis, project_id: str) -> Dict:
             - projectId (str): Project ID
             - title (str): Project title
             - description (str): Project description
-            - pi (dict): Principal investigator info
+            - pi (str): Principal investigator name
             - coPis (list): Co-PIs
             - teamMembers (list): Team members
             - awardNumbers (list): Award/grant numbers
@@ -108,15 +137,15 @@ def get_project(t: Tapis, project_id: str) -> Dict:
     bp = data.get("baseProject", {})
     val = bp.get("value", {})
     users = val.get("users", [])
-    pi = next((u for u in users if u.get("role") == "pi"), None)
+    pi = _extract_pi(users)
     uuid = bp.get("uuid", "")
 
     return {
         "uuid": uuid,
         "projectId": val.get("projectId"),
         "title": val.get("title"),
         "description": val.get("description"),
-        "pi": pi,
+        "pi": _pi_display(pi),
         "coPis": val.get("coPis", []),
         "teamMembers": val.get("teamMembers", []),
         "awardNumbers": val.get("awardNumbers", []),
@@ -130,24 +159,33 @@ def get_project(t: Tapis, project_id: str) -> Dict:
 
 
 def list_project_files(
-    t: Tapis, project_id: str, path: str = "/", limit: int = 100
-) -> List:
+    t: Tapis,
+    project_id: str,
+    path: str = "/",
+    limit: int = 100,
+    output: str = "df",
+) -> Union[pd.DataFrame, List]:
     """List files in a DesignSafe project.
 
-    Resolves the project ID to a Tapis system and lists files at the given path.
-
     Args:
         t (Tapis): Authenticated Tapis client instance.
         project_id (str): Project ID (e.g., "PRJ-1305").
         path (str, optional): Path within the project. Defaults to "/".
         limit (int, optional): Maximum number of items to return. Defaults to 100.
+        output (str, optional): Output format. "df" returns a pandas DataFrame
+            (default), "raw" returns Tapis file objects.
 
     Returns:
-        List: List of Tapis file objects with name, type, size, etc.
+        Union[pd.DataFrame, List]: Files in the requested format.
+            DataFrame columns: name, type, size, lastModified, path.
 
     Raises:
         FileOperationError: If the project is not found or file listing fails.
+        ValueError: If output format is invalid.
     """
+    if output not in ("df", "raw"):
+        raise ValueError(f"output must be 'df' or 'raw', got '{output}'")
+
     project = get_project(t, project_id)
     system_id = project["systemId"]
     if not system_id:
@@ -160,12 +198,30 @@ def list_project_files(
 
     try:
         results = t.files.listFiles(systemId=system_id, path=path, limit=limit)
-        return results
     except BaseTapyException as e:
         raise FileOperationError(
             f"Failed to list files in project '{project_id}' at path '{path}': {e}"
         ) from e
 
+    if output == "raw":
+        return results
+
+    rows = []
+    for f in results:
+        rows.append(
+            {
+                "name": getattr(f, "name", ""),
+                "type": getattr(f, "type", ""),
+                "size": getattr(f, "size", 0),
+                "lastModified": getattr(f, "lastModified", ""),
+                "path": getattr(f, "path", ""),
+            }
+        )
+    df = pd.DataFrame(rows)
+    if not df.empty and "lastModified" in df.columns:
+        df["lastModified"] = pd.to_datetime(df["lastModified"], errors="coerce")
+    return df
+
 
 def resolve_project_uuid(t: Tapis, project_id: str) -> str:
     """Resolve a DesignSafe project ID (e.g., PRJ-1305) to its Tapis system ID.