"""Nextcloud API for working with user groups."""
import dataclasses
from ._misc import kwargs_to_params
from ._session import AsyncNcSessionBasic, NcSessionBasic
[docs]
@dataclasses.dataclass
class GroupDetails:
"""User Group information."""
def __init__(self, raw_data: dict):
self._raw_data = raw_data
@property
def group_id(self) -> str:
"""ID of the group."""
return self._raw_data["id"]
@property
def display_name(self) -> str:
"""A display name of the group."""
return self._raw_data["displayname"]
@property
def user_count(self) -> int:
"""Number of users in the group."""
return self._raw_data["usercount"]
@property
def disabled(self) -> bool:
"""Flag indicating is group disabled."""
return bool(self._raw_data["disabled"])
@property
def can_add(self) -> bool:
"""Flag indicating the caller has enough rights to add users to this group."""
return bool(self._raw_data["canAdd"])
@property
def can_remove(self) -> bool:
"""Flag indicating the caller has enough rights to remove users from this group."""
return bool(self._raw_data["canRemove"])
def __repr__(self):
return f"<{self.__class__.__name__} id={self.group_id}, user_count={self.user_count}, disabled={self.disabled}>"
[docs]
class _UsersGroupsAPI:
"""Class providing an API for managing user groups on the Nextcloud server.
.. note:: In NextcloudApp mode, only ``get_list`` and ``get_details`` methods are available.
"""
_ep_base: str = "/ocs/v1.php/cloud/groups"
def __init__(self, session: NcSessionBasic):
self._session = session
[docs]
def get_list(self, mask: str | None = None, limit: int | None = None, offset: int | None = None) -> list[str]:
"""Returns a list of user groups IDs."""
data = kwargs_to_params(["search", "limit", "offset"], search=mask, limit=limit, offset=offset)
response_data = self._session.ocs("GET", self._ep_base, params=data)
return response_data["groups"] if response_data else []
[docs]
def get_details(
self, mask: str | None = None, limit: int | None = None, offset: int | None = None
) -> list[GroupDetails]:
"""Returns a list of user groups with detailed information."""
data = kwargs_to_params(["search", "limit", "offset"], search=mask, limit=limit, offset=offset)
response_data = self._session.ocs("GET", f"{self._ep_base}/details", params=data)
return [GroupDetails(i) for i in response_data["groups"]] if response_data else []
[docs]
def create(self, group_id: str, display_name: str | None = None) -> None:
"""Creates the users group."""
params = {"groupid": group_id}
if display_name is not None:
params["displayname"] = display_name
self._session.ocs("POST", f"{self._ep_base}", params=params)
[docs]
def edit(self, group_id: str, display_name: str) -> None:
"""Edits users group information."""
params = {"key": "displayname", "value": display_name}
self._session.ocs("PUT", f"{self._ep_base}/{group_id}", params=params)
[docs]
def delete(self, group_id: str) -> None:
"""Removes the users group."""
self._session.ocs("DELETE", f"{self._ep_base}/{group_id}")
[docs]
def get_members(self, group_id: str) -> list[str]:
"""Returns a list of group users."""
response_data = self._session.ocs("GET", f"{self._ep_base}/{group_id}")
return response_data["users"] if response_data else {}
[docs]
def get_subadmins(self, group_id: str) -> list[str]:
"""Returns list of users who is subadmins of the group."""
return self._session.ocs("GET", f"{self._ep_base}/{group_id}/subadmins")
class _AsyncUsersGroupsAPI:
"""Class provides an async API for managing user groups on the Nextcloud server.
.. note:: In NextcloudApp mode, only ``get_list`` and ``get_details`` methods are available.
"""
_ep_base: str = "/ocs/v1.php/cloud/groups"
def __init__(self, session: AsyncNcSessionBasic):
self._session = session
async def get_list(self, mask: str | None = None, limit: int | None = None, offset: int | None = None) -> list[str]:
"""Returns a list of user groups IDs."""
data = kwargs_to_params(["search", "limit", "offset"], search=mask, limit=limit, offset=offset)
response_data = await self._session.ocs("GET", self._ep_base, params=data)
return response_data["groups"] if response_data else []
async def get_details(
self, mask: str | None = None, limit: int | None = None, offset: int | None = None
) -> list[GroupDetails]:
"""Returns a list of user groups with detailed information."""
data = kwargs_to_params(["search", "limit", "offset"], search=mask, limit=limit, offset=offset)
response_data = await self._session.ocs("GET", f"{self._ep_base}/details", params=data)
return [GroupDetails(i) for i in response_data["groups"]] if response_data else []
async def create(self, group_id: str, display_name: str | None = None) -> None:
"""Creates the users group."""
params = {"groupid": group_id}
if display_name is not None:
params["displayname"] = display_name
await self._session.ocs("POST", f"{self._ep_base}", params=params)
async def edit(self, group_id: str, display_name: str) -> None:
"""Edits users group information."""
params = {"key": "displayname", "value": display_name}
await self._session.ocs("PUT", f"{self._ep_base}/{group_id}", params=params)
async def delete(self, group_id: str) -> None:
"""Removes the users group."""
await self._session.ocs("DELETE", f"{self._ep_base}/{group_id}")
async def get_members(self, group_id: str) -> list[str]:
"""Returns a list of group users."""
response_data = await self._session.ocs("GET", f"{self._ep_base}/{group_id}")
return response_data["users"] if response_data else {}
async def get_subadmins(self, group_id: str) -> list[str]:
"""Returns list of users who is subadmins of the group."""
return await self._session.ocs("GET", f"{self._ep_base}/{group_id}/subadmins")