Better Team and Folder support (#1373)

normanrz · web-flow · commit dc4eb1676d93 · 2025-10-06T12:01:26.000+02:00
* CLI fixes

* docs + overwrite

* changelog

* wip

* wip

* pr feedback

* no-downsample

* wip

* tests

* lint

* changelog

* typing

* pr feedback

* pr feedback
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -275,6 +275,7 @@ nav:
         - Layer: api/webknossos/dataset/layer.md
         - MagView: api/webknossos/dataset/mag_view.md
         - View: api/webknossos/dataset/view.md
+        - RemoteFolder: api/webknossos/dataset/remote_folder.md
       - Annotation: api/webknossos/annotation/annotation.md
       - Skeleton:
         - Skeleton: api/webknossos/skeleton/skeleton.md
@@ -284,6 +285,7 @@ nav:
       - Authentication & Server Context: api/webknossos/client/context.md
       - Administration:
         - User: api/webknossos/administration/user.md
+        - Team: api/webknossos/administration/team.md
         - Project: api/webknossos/administration/project.md
         - Task: api/webknossos/administration/task.md
     - CLI Reference:
diff --git a/webknossos/Changelog.md b/webknossos/Changelog.md
@@ -20,8 +20,12 @@ For upgrade instructions, please check the respective _Breaking Changes_ section
 - Added `downsample`, `max-mag`, `interpolation-mode`, `sampling-mode` args to `convert`, `convert-raw` and `convert-zarr` CLI commands, where it was missing, for consistency. [#1372](https://github.com/scalableminds/webknossos-libs/pull/1372)
 - Added value rescaling to `convert-raw` CLI command through `source-dtype` and `rescale-min-max` args. [#1372](https://github.com/scalableminds/webknossos-libs/pull/1372)
 - Added `interpolation_mode` and `compress` kwargs to `Dataset.downsample` method. [#1372](https://github.com/scalableminds/webknossos-libs/pull/1372)
+- Added `Team.get_by_id`, `Team.add_user` and `Team.delete` methods. [#1373](https://github.com/scalableminds/webknossos-libs/pull/1373)
+- Added `RemoteFolder.get_root`, `RemoteFolder.get_subfolders`, `RemoteFolder.get_datasets`, `RemoteFolder.add_subfolder`, `RemoteFolder.move_to`, `RemoteFolder.delete` methods and `RemoteFolder.allowed_teams`, `RemoteFolder.name` properties. [#1373](https://github.com/scalableminds/webknossos-libs/pull/1373)
 
 ### Changed
+- `Team.add` now returns the created team object. [#1373](https://github.com/scalableminds/webknossos-libs/pull/1373)
+- Moved `Team` to `webknossos.administration.team` module. [#1373](https://github.com/scalableminds/webknossos-libs/pull/1373)
 
 ### Fixed
 
diff --git a/webknossos/tests/cassettes/test_dataset_download_upload_remote/test_folders_and_teams.yml b/webknossos/tests/cassettes/test_dataset_download_upload_remote/test_folders_and_teams.yml
diff --git a/webknossos/tests/dataset/test_dataset_download_upload_remote.py b/webknossos/tests/dataset/test_dataset_download_upload_remote.py
@@ -135,6 +135,29 @@ def test_remote_dataset(tmp_path: Path) -> None:
     assert remote_ds.folder.name == "A subfolder!"
 
 
+def test_folders_and_teams() -> None:
+    folder_name = "test_folder"
+    team_name = "test_team"
+
+    remote_folder = wk.RemoteFolder.get_root().add_subfolder(folder_name)
+    assert remote_folder.name == folder_name
+
+    remote_team = wk.Team.add(team_name)
+    remote_folder.allowed_teams = (remote_team,)
+    assert remote_folder.allowed_teams == (remote_team,)
+
+    remote_folder.name = f"{folder_name}_renamed"
+    assert remote_folder.name == f"{folder_name}_renamed"
+
+    subfolder = remote_folder.add_subfolder(f"{folder_name}_subfolder")
+    assert remote_folder.get_subfolders() == (subfolder,)
+    subfolder.delete()
+    assert remote_folder.get_subfolders() == ()
+
+    remote_folder.delete()
+    remote_team.delete()
+
+
 def test_upload_download_roundtrip(tmp_path: Path) -> None:
     ds_original = get_sample_dataset(tmp_path)
     uploaded_dataset = ds_original.upload(
diff --git a/webknossos/webknossos/__init__.py b/webknossos/webknossos/__init__.py
@@ -18,7 +18,7 @@
 
 Additionally, we provide the various geometrical primitives, e.g. `Vec3Int`, `BoundingBox` and `Mag`.
 
-The `User`, `Project` and `Task` classes provide WEBKNOSSOS server interactions for administration purposes.
+The `User`, `Team`, `Project` and `Task` classes provide WEBKNOSSOS server interactions for administration purposes.
 Server interactions may require [authentication](webknossos/client/context.html) e.g. via `webknossos_context`.
 """
 
diff --git a/webknossos/webknossos/administration/__init__.py b/webknossos/webknossos/administration/__init__.py
@@ -1,4 +1,5 @@
 # ruff: noqa: F401 imported but unused
 from .project import Project
 from .task import Task, TaskType
-from .user import Team, User
+from .team import Team
+from .user import User
diff --git a/webknossos/webknossos/administration/project.py b/webknossos/webknossos/administration/project.py
@@ -6,7 +6,8 @@
 from ..client.api_client.errors import UnexpectedStatusError
 from ..client.api_client.models import ApiProject, ApiProjectCreate
 from ..client.context import _get_api_client
-from .user import Team, User
+from .team import Team
+from .user import User
 
 if TYPE_CHECKING:
     from .task import Task
diff --git a/webknossos/webknossos/administration/task.py b/webknossos/webknossos/administration/task.py
@@ -21,7 +21,7 @@
 from ..geometry import BoundingBox, Vec3Int
 from ..utils import warn_deprecated
 from .project import Project
-from .user import Team
+from .team import Team
 
 logger = logging.getLogger(__name__)
 
diff --git a/webknossos/webknossos/administration/team.py b/webknossos/webknossos/administration/team.py
@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+import attr
+
+from ..client.api_client.models import ApiTeamAdd
+from ..client.context import _get_api_client
+
+if TYPE_CHECKING:
+    from .user import User
+
+
+@attr.frozen
+class Team:
+    id: str
+    name: str
+    organization_id: str
+
+    @classmethod
+    def get_by_name(cls, name: str) -> "Team":
+        """Returns the Team specified by the passed name if your token authorizes you to see it."""
+        client = _get_api_client(enforce_auth=True)
+        api_teams = client.team_list()
+        for api_team in api_teams:
+            if api_team.name == name:
+                return cls(api_team.id, api_team.name, api_team.organization)
+        raise KeyError(f"Could not find team {name}.")
+
+    @classmethod
+    def get_by_id(cls, team_id: str) -> "Team":
+        """Returns the Team specified by the passed ID."""
+        client = _get_api_client(enforce_auth=True)
+        api_teams = client.team_list()
+        for api_team in api_teams:
+            if api_team.id == team_id:
+                return cls(api_team.id, api_team.name, api_team.organization)
+        raise KeyError(f"Could not find team {team_id}.")
+
+    @classmethod
+    def get_list(cls) -> list["Team"]:
+        """Returns all teams of the current user."""
+        client = _get_api_client(enforce_auth=True)
+        api_teams = client.team_list()
+        return [
+            cls(api_team.id, api_team.name, api_team.organization)
+            for api_team in api_teams
+        ]
+
+    @classmethod
+    def add(cls, team_name: str) -> "Team":
+        """Adds a new team with the specified name."""
+        client = _get_api_client(enforce_auth=True)
+        client.team_add(team=ApiTeamAdd(team_name))
+        return cls.get_by_name(team_name)
+
+    def add_user(self, user: "User", *, is_team_manager: bool = False) -> None:
+        """Adds a user to the team."""
+        user.assign_team_roles(self, is_team_manager=is_team_manager)
+
+    def delete(self) -> None:
+        """Deletes the team."""
+        client = _get_api_client(enforce_auth=True)
+        client.team_delete(team_id=self.id)
diff --git a/webknossos/webknossos/administration/user.py b/webknossos/webknossos/administration/user.py
@@ -2,11 +2,11 @@
 
 from ..client.api_client.models import (
     ApiLoggedTimeGroupedByMonth,
-    ApiTeamAdd,
     ApiTeamMembership,
     ApiUser,
 )
 from ..client.context import _get_api_client
+from .team import Team
 
 
 @attr.frozen
@@ -21,7 +21,7 @@ class User:
     last_name: str
     created: int
     last_activity: int
-    teams: tuple["Team", ...]
+    teams: tuple[Team, ...]
     experiences: dict[str, int]
     is_active: bool
     is_admin: bool
@@ -84,59 +84,26 @@ def get_all_managed_users(cls) -> list["User"]:
         api_users = client.user_list()
         return [cls._from_api_user(i) for i in api_users]
 
-    def assign_team_roles(self, team_name: str, is_team_manager: bool) -> None:
+    def assign_team_roles(self, team: "str | Team", is_team_manager: bool) -> None:
         """Assigns the specified roles to the user for the specified team."""
         client = _get_api_client(enforce_auth=True)
         api_user = client.user_by_id(user_id=self.user_id)
-        if team_name in [team.name for team in api_user.teams]:
+        team_obj = Team.get_by_name(team) if isinstance(team, str) else team
+        if team_obj.id in [t.id for t in api_user.teams]:
+            # updates tean membership
             api_user.teams = [
-                team
-                if team.name != team_name
-                else ApiTeamMembership(team.id, team.name, is_team_manager)
-                for team in api_user.teams
+                t
+                if t.id != team_obj.id
+                else ApiTeamMembership(t.id, t.name, is_team_manager)
+                for t in api_user.teams
             ]
         else:
             api_user.teams.append(
-                ApiTeamMembership(
-                    Team.get_by_name(team_name).id, team_name, is_team_manager
-                )
+                ApiTeamMembership(team_obj.id, team_obj.name, is_team_manager)
             )
         client.user_update(user=api_user)
 
 
-@attr.frozen
-class Team:
-    id: str
-    name: str
-    organization_id: str
-
-    @classmethod
-    def get_by_name(cls, name: str) -> "Team":
-        """Returns the Team specified by the passed name if your token authorizes you to see it."""
-        client = _get_api_client(enforce_auth=True)
-        api_teams = client.team_list()
-        for api_team in api_teams:
-            if api_team.name == name:
-                return cls(api_team.id, api_team.name, api_team.organization)
-        raise KeyError(f"Could not find team {name}.")
-
-    @classmethod
-    def get_list(cls) -> list["Team"]:
-        """Returns all teams of the current user."""
-        client = _get_api_client(enforce_auth=True)
-        api_teams = client.team_list()
-        return [
-            cls(api_team.id, api_team.name, api_team.organization)
-            for api_team in api_teams
-        ]
-
-    @classmethod
-    def add(cls, team_name: str) -> None:
-        """Adds a new team with the specified name."""
-        client = _get_api_client(enforce_auth=True)
-        client.team_add(team=ApiTeamAdd(team_name))
-
-
 @attr.frozen
 class LoggedTime:
     duration_in_seconds: int
diff --git a/webknossos/webknossos/client/api_client/_abstract_api_client.py b/webknossos/webknossos/client/api_client/_abstract_api_client.py
@@ -134,8 +134,20 @@ def _get_file(
         response = self._get(route, query, retry_count=retry_count)
         return response.content, self._parse_filename_from_header(response)
 
-    def _post_with_json_response(self, route: str, response_type: type[T]) -> T:
-        response = self._post(route)
+    def _post_with_json_response(
+        self,
+        route: str,
+        response_type: type[T],
+        query: Query | None = None,
+        retry_count: int = 0,
+        timeout_seconds: float | None = None,
+    ) -> T:
+        response = self._post(
+            route,
+            query=query,
+            retry_count=retry_count,
+            timeout_seconds=timeout_seconds,
+        )
         return self._parse_json(response, response_type)
 
     def _post_json_with_json_response(
diff --git a/webknossos/webknossos/client/api_client/models.py b/webknossos/webknossos/client/api_client/models.py
@@ -377,6 +377,12 @@ class ApiAnnotationUploadResult:
     messages: list[str]
 
 
+@attr.s(auto_attribs=True)
+class ApiFolderAdd:
+    parent_id: str
+    name: str
+
+
 @attr.s(auto_attribs=True)
 class ApiFolderWithParent:
     id: str
@@ -394,6 +400,13 @@ class ApiFolder:
     metadata: list[ApiMetadata] | None = None
 
 
+@attr.s(auto_attribs=True)
+class ApiFolderUpdate:
+    name: str
+    allowed_teams: list[str]
+    metadata: list[ApiMetadata] | None = None
+
+
 @attr.s(auto_attribs=True)
 class ApiPrecomputedMeshInfo:
     lod: int
diff --git a/webknossos/webknossos/client/api_client/wk_api_client.py b/webknossos/webknossos/client/api_client/wk_api_client.py
@@ -10,6 +10,8 @@
     ApiDatasetId,
     ApiDatasetIsValidNewNameResponse,
     ApiDataStore,
+    ApiFolder,
+    ApiFolderUpdate,
     ApiFolderWithParent,
     ApiLoggedTimeGroupedByMonth,
     ApiNmlTaskParameters,
@@ -235,10 +237,42 @@ def task_list(self) -> list[ApiTask]:
         route = "/tasks/list"
         return self._post_json_with_json_response(route, {}, list[ApiTask])
 
+    def folder_root(self) -> ApiFolderWithParent:
+        route = "/folders/root"
+        return self._get_json(route, ApiFolderWithParent)
+
+    def folder_get(self, *, folder_id: str) -> ApiFolder:
+        route = f"/folders/{folder_id}"
+        return self._get_json(route, ApiFolder)
+
+    def folder_update(self, *, folder_id: str, folder: ApiFolderUpdate) -> None:
+        route = f"/folders/{folder_id}"
+        self._put_json(route, folder)
+
     def folder_tree(self) -> list[ApiFolderWithParent]:
         route = "/folders/tree"
         return self._get_json(route, list[ApiFolderWithParent])
 
+    def folder_add(self, *, folder_name: str, parent_id: str) -> ApiFolderWithParent:
+        route = "/folders/create"
+        return self._post_with_json_response(
+            route,
+            ApiFolderWithParent,
+            query={"parentId": parent_id, "name": folder_name},
+        )
+
+    def folder_move(self, *, folder_id: str, new_parent_id: str) -> ApiFolderWithParent:
+        route = "/folders/create"
+        return self._post_with_json_response(
+            route,
+            ApiFolderWithParent,
+            query={"newParentId": new_parent_id, "id": folder_id},
+        )
+
+    def folder_delete(self, *, folder_id: str) -> None:
+        route = f"/folders/{folder_id}"
+        self._delete(route)
+
     def user_by_id(self, *, user_id: str) -> ApiUser:
         route = f"/users/{user_id}"
         return self._get_json(route, ApiUser)
@@ -267,6 +301,10 @@ def team_add(self, *, team: ApiTeamAdd) -> None:
         route = "/teams"
         self._post_json(route, team)
 
+    def team_delete(self, *, team_id: str) -> None:
+        route = f"/teams/{team_id}"
+        self._delete(route)
+
     def tasks_create(
         self, *, task_parameters: list[ApiTaskParameters]
     ) -> ApiTaskCreationResult:
diff --git a/webknossos/webknossos/dataset/dataset.py b/webknossos/webknossos/dataset/dataset.py
@@ -61,7 +61,7 @@
 if TYPE_CHECKING:
     import pims
 
-    from ..administration.user import Team
+    from ..administration.team import Team
     from ..client._upload_dataset import LayerToLink
     from ..client.context import webknossos_context
 
@@ -3468,7 +3468,7 @@ def allowed_teams(self) -> tuple["Team", ...]:
             - An empty list makes the dataset private
         """
 
-        from ..administration.user import Team
+        from ..administration.team import Team
 
         return tuple(
             Team(id=i.id, name=i.name, organization_id=i.organization)
@@ -3478,7 +3478,7 @@ def allowed_teams(self) -> tuple["Team", ...]:
     @allowed_teams.setter
     def allowed_teams(self, allowed_teams: Sequence[Union[str, "Team"]]) -> None:
         """Assign the teams that are allowed to access the dataset. Specify the teams like this `[Team.get_by_name("Lab_A"), ...]`."""
-        from ..administration.user import Team
+        from ..administration.team import Team
         from ..client.context import _get_api_client
 
         team_ids = [i.id if isinstance(i, Team) else i for i in allowed_teams]
diff --git a/webknossos/webknossos/dataset/remote_folder.py b/webknossos/webknossos/dataset/remote_folder.py
