docs: added docstring on Keycloak returned institutions full path, up…

…dated test to include nested institutions.

src/entities/models/dto.py

@@ -62,8 +62,20 @@ def from_claim(cls, claims: Dict[str, Any]) -> "AuthenticatedUser":
 
     @classmethod
     def parse_institutions(cls, institutions: List[str] | None) -> List[str]:
+        """
+        Parse out the list of institutions returned by Keycloak
+
+        Args:
+            institutions(List[str]): list of full institution paths provided by keycloak,
+            it is possible to have nested paths, though we may not use the feature.
+            e.g. ["/ROOT_INSTITUTION/CHILD_INSTITUTION/GRAND_CHILD_INSTITUTION"]
+
+        Returns:
+            List[str]: List of cleaned up institutions.
+            e.g. ["GRAND_CHILD_INSTITUTION"]
+        """
         if institutions:
-            return list(map(lambda institution: institution.split("/")[-1], institutions))
+            return [institution.split("/")[-1] for institution in institutions]
         else:
             return []
 

tests/api/routers/test_admin_api.py

@@ -27,7 +27,7 @@ def test_get_me_authed_with_institutions(self, app_fixture: FastAPI, auth_mock:
             "preferred_username": "test_user",
             "email": "[email protected]",
             "sub": "testuser123",
-            "institutions": ["/TEST1LEI", "/TEST2LEI"],
+            "institutions": ["/TEST1LEI", "/TEST2LEI/TEST2CHILDLEI"],
         }
         auth_mock.return_value = (
             AuthCredentials(["authenticated"]),
@@ -36,7 +36,7 @@ def test_get_me_authed_with_institutions(self, app_fixture: FastAPI, auth_mock:
         client = TestClient(app_fixture)
         res = client.get("/v1/admin/me")
         assert res.status_code == 200
-        assert res.json().get("institutions") == ["TEST1LEI", "TEST2LEI"]
+        assert res.json().get("institutions") == ["TEST1LEI", "TEST2CHILDLEI"]
 
     def test_update_me_unauthed(self, app_fixture: FastAPI, unauthed_user_mock: Mock):
         client = TestClient(app_fixture)