DOC: Add '/project' route documentation

mferrera · mferrera · commit 81bea7bcdd6d · 2025-05-26T11:48:36.000+02:00
diff --git a/src/fmu_settings_api/session.py b/src/fmu_settings_api/session.py
@@ -80,7 +80,15 @@ async def create_session(
         user_fmu_directory: UserFMUDirectory,
         expire_seconds: int = settings.SESSION_EXPIRE_SECONDS,
     ) -> str:
-        """Creates a new session and stores it to the storage backend."""
+        """Creates a new session and stores it to the storage backend.
+
+        Params:
+            user_fmu_directory: The user .fmu directory instance
+            expire_seconds: How long the session should be valid. Optional, defaulted.
+
+        Returns:
+            The session id of the newly created session
+        """
         session_id = str(uuid4())
         now = datetime.now(UTC)
         expiration_duration = timedelta(seconds=expire_seconds)
@@ -96,18 +104,26 @@ async def create_session(
 
         return session_id
 
-    async def get_session(
-        self: Self, session_id: str
-    ) -> Session | ProjectSession | None:
-        """Get the session data for a session id."""
+    async def get_session(self: Self, session_id: str) -> Session | ProjectSession:
+        """Get the session data for a session id.
+
+        Params:
+            session_id: The session id being requested
+
+        Returns:
+            The session, if it exists and is valid
+
+        Raises:
+            SessionNotFoundError: If the session does not exist or is invalid
+        """
         session = await self._retrieve_session(session_id)
         if not session:
-            return None
+            raise SessionNotFoundError("No active session found")
 
         now = datetime.now(UTC)
         if session.expires_at < now:
             await self.destroy_session(session_id)
-            return None
+            raise SessionNotFoundError("Invalid or expired session")
 
         session.last_accessed = now
         await self._update_session(session_id, session)
@@ -135,11 +151,9 @@ async def add_fmu_project_to_session(
         The updated ProjectSession
 
     Raises:
-        SessionNotFoundError: If no session was found
+        SessionNotFoundError: If no valid session was found
     """
     session = await session_manager.get_session(session_id)
-    if not session:
-        raise SessionNotFoundError(f"No session with id {session_id} found")
 
     if isinstance(session, ProjectSession):
         project_session = session
@@ -159,12 +173,10 @@ async def remove_fmu_project_from_session(session_id: str) -> Session:
         The updates session
 
     Raises:
-        SessionNotFoundError: If no session was found
+        SessionNotFoundError: If no valid session was found
     """
     maybe_project_session = await session_manager.get_session(session_id)
 
-    if maybe_project_session is None:
-        raise SessionNotFoundError(f"No session with id {session_id} found")
     if isinstance(maybe_project_session, Session):
         return maybe_project_session
 
diff --git a/src/fmu_settings_api/v1/responses.py b/src/fmu_settings_api/v1/responses.py
@@ -12,7 +12,11 @@
         ),
         "content": {
             "application/json": {
-                "example": {"detail": "Not authorized"},
+                "example": {
+                    "examples": [
+                        {"detail": "Not authorized"},
+                    ],
+                },
             },
         },
     },
@@ -24,7 +28,11 @@
         ),
         "content": {
             "application/json": {
-                "example": {"detail": "Permission denied creating user .fmu"},
+                "example": {
+                    "examples": [
+                        {"detail": "Permission denied creating user .fmu"},
+                    ],
+                },
             },
         },
     },
@@ -55,7 +63,11 @@
         "description": "Something unexpected has happened",
         "content": {
             "application/json": {
-                "example": {"detail": "{string content of exception}"},
+                "example": {
+                    "examples": [
+                        {"detail": "{string content of exception}"},
+                    ],
+                },
             },
         },
     },
@@ -80,7 +92,12 @@
         "description": "Something unexpected has happened",
         "content": {
             "application/json": {
-                "example": {"detail": "Session error: {string content of exception}"},
+                "example": {
+                    "examples": [
+                        {"detail": "Session error: {string content of exception}"},
+                        {"detail": "{string content of exception}"},
+                    ],
+                },
             },
         },
     },
diff --git a/src/fmu_settings_api/v1/routes/project.py b/src/fmu_settings_api/v1/routes/project.py
@@ -1,6 +1,7 @@
 """Routes to add an FMU project to an existing session."""
 
 from pathlib import Path
+from typing import Final
 
 from fastapi import APIRouter, HTTPException, Response
 from fmu.settings import find_nearest_fmu_directory, get_fmu_directory
@@ -17,13 +18,82 @@
     add_fmu_project_to_session,
     remove_fmu_project_from_session,
 )
+from fmu_settings_api.v1.responses import GetSessionResponses, Responses
 
 router = APIRouter(prefix="/project", tags=["project"])
 
+ProjectResponses: Final[Responses] = {
+    403: {
+        "description": (
+            "The OS returned a permissions error while locating or creating .fmu"
+        ),
+        "content": {
+            "application/json": {
+                "example": {
+                    "examples": [
+                        {"detail": "Permission denied locating .fmu"},
+                        {"detail": "Permission denied accessing .fmu at {path}"},
+                        {"detail": "Permission denied creating .fmu at {path}"},
+                    ],
+                },
+            },
+        },
+    },
+    404: {
+        "description": (
+            "The .fmu directory was unable to be found at or above a given path, or "
+            "the requested path to create a project .fmu directory at does not exist."
+        ),
+        "content": {
+            "application/json": {
+                "example": {
+                    "examples": [
+                        {"detail": "No .fmu directory found from {path}"},
+                        {"detail": "No .fmu directory found at {path}"},
+                        {"detail": "Path {path} does not exist"},
+                    ],
+                },
+            },
+        },
+    },
+}
 
-@router.get("/", response_model=FMUProject)
+ProjectExistsResponses: Final[Responses] = {
+    409: {
+        "description": (
+            "A project .fmu directory already exist at a given location, or may "
+            "possibly not be a directory, i.e. it may be a .fmu file."
+        ),
+        "content": {
+            "application/json": {
+                "example": {
+                    "examples": [
+                        {"detail": ".fmu exists at {path} but is not a directory"},
+                        {"detail": ".fmu already exists at {path}"},
+                    ],
+                },
+            },
+        },
+    },
+}
+
+
+@router.get(
+    "/",
+    response_model=FMUProject,
+    summary="Returns the paths and configuration of the nearest project .fmu directory",
+    description=(
+        "If a project is not already attached to the session id it will be "
+        "attached after a call to this route. If one is already attached this "
+        "route will return data for the project .fmu directory again."
+    ),
+    responses={
+        **GetSessionResponses,
+        **ProjectResponses,
+    },
+)
 async def get_project(session: SessionDep) -> FMUProject:
-    """Returns the paths and configuration for the nearest project .fmu directory.
+    """Returns the paths and configuration of the nearest project .fmu directory.
 
     This directory is searched for above the current working directory.
 
@@ -62,7 +132,24 @@ async def get_project(session: SessionDep) -> FMUProject:
         raise HTTPException(status_code=500, detail=str(e)) from e
 
 
-@router.post("/", response_model=FMUProject)
+@router.post(
+    "/",
+    response_model=FMUProject,
+    summary=(
+        "Returns the path and configuration of the project .fmu directory at 'path'"
+    ),
+    description=(
+        "Used for when a user selects a project .fmu directory in a directory not "
+        "found above the user's current working directory. Will overwrite the "
+        "project .fmu directory attached to a session if one exists. If not, it is "
+        "added to the session."
+    ),
+    responses={
+        **GetSessionResponses,
+        **ProjectResponses,
+        **ProjectExistsResponses,
+    },
+)
 async def post_project(session: SessionDep, fmu_dir_path: FMUDirPath) -> FMUProject:
     """Returns the paths and configuration for the project .fmu directory at 'path'."""
     path = fmu_dir_path.path
@@ -91,26 +178,23 @@ async def post_project(session: SessionDep, fmu_dir_path: FMUDirPath) -> FMUProj
         raise HTTPException(status_code=500, detail=str(e)) from e
 
 
-@router.delete("/", response_model=Message)
-async def delete_project_session(
-    session: ProjectSessionDep, response: Response
-) -> Message:
-    """Deletes a project .fmu session if it exists."""
-    try:
-        await remove_fmu_project_from_session(session.id)
-        return Message(
-            message=(
-                f"FMU directory {session.project_fmu_directory.path} closed "
-                "successfully"
-            ),
-        )
-    except SessionNotFoundError as e:
-        raise HTTPException(status_code=401, detail=str(e)) from e
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e)) from e
-
-
-@router.post("/init", response_model=FMUProject)
+@router.post(
+    "/init",
+    response_model=FMUProject,
+    summary=(
+        "Initializes a project .fmu directory at 'path' and returns its paths and "
+        "configuration"
+    ),
+    description=(
+        "If a project .fmu directory is already attached to the session, this will "
+        "switch to use the newly created .fmu directory."
+    ),
+    responses={
+        **GetSessionResponses,
+        **ProjectResponses,
+        **ProjectExistsResponses,
+    },
+)
 async def init_project(
     session: SessionDep,
     fmu_dir_path: FMUDirPath,
@@ -142,3 +226,33 @@ async def init_project(
         ) from e
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.delete(
+    "/",
+    response_model=Message,
+    summary="Removes a project .fmu directory from a session",
+    description=(
+        "This route simply removes an opened project .fmu directory from a session. "
+        "It does not affect the user other aside from that."
+    ),
+    responses={
+        **GetSessionResponses,
+    },
+)
+async def delete_project_session(
+    session: ProjectSessionDep, response: Response
+) -> Message:
+    """Deletes a project .fmu session if it exists."""
+    try:
+        await remove_fmu_project_from_session(session.id)
+        return Message(
+            message=(
+                f"FMU directory {session.project_fmu_directory.path} closed "
+                "successfully"
+            ),
+        )
+    except SessionNotFoundError as e:
+        raise HTTPException(status_code=401, detail=str(e)) from e
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
diff --git a/tests/test_session.py b/tests/test_session.py
@@ -5,11 +5,13 @@
 from pathlib import Path
 from unittest.mock import patch
 
+import pytest
 from fmu.settings._init import init_user_fmu_directory
 
 from fmu_settings_api.config import settings
 from fmu_settings_api.session import (
     SessionManager,
+    SessionNotFoundError,
     create_fmu_session,
     destroy_fmu_session,
     session_manager,
@@ -50,7 +52,8 @@ async def test_get_non_existing_session(
     """Tests getting an existing session."""
     user_fmu_dir = init_user_fmu_directory()
     await session_manager.create_session(user_fmu_dir)
-    assert await session_manager.get_session("no") is None
+    with pytest.raises(SessionNotFoundError, match="No active session found"):
+        await session_manager.get_session("no")
     assert len(session_manager.storage) == 1
 
 
@@ -77,7 +80,8 @@ async def test_get_existing_session_expiration(
 
     # Pretend it expired a second ago.
     orig_session.expires_at = datetime.now(UTC) - timedelta(seconds=1)
-    assert await session_manager.get_session(session_id) is None
+    with pytest.raises(SessionNotFoundError, match="Invalid or expired session"):
+        assert await session_manager.get_session(session_id)
     # It should also be destroyed.
     assert session_id not in session_manager.storage
     assert len(session_manager.storage) == 0
