"""
Groups API
"""
import datetime
from collections.abc import Generator
from typing import Optional
from pydantic import Field
from ..api_child import ApiChild
from ..base import ApiModel, to_camel
__all__ = ['GroupMember', 'Group', 'GroupsApi']
[docs]
class GroupMember(ApiModel):
#: Person ID of the group member.
member_id: Optional[str] = Field(alias='id', default=None)
#: Member type.
member_type: Optional[str] = Field(alias='type', default=None)
display_name: Optional[str] = None
# only used in updates. 'delete' to delete a member
operation: Optional[str] = None
[docs]
class Group(ApiModel):
#: A unique identifier for the group.
group_id: Optional[str] = Field(alias='id', default=None)
#: The name of the group.
display_name: Optional[str] = None
#: An array of members
members: Optional[list[GroupMember]] = None
#: The ID of the organization to which this group belongs.
org_id: Optional[str] = None
description: Optional[str] = None
#: The timestamp indicating creation date/time of group
created: Optional[datetime.datetime] = None
#: The timestamp indicating lastModification time of group
last_modified: Optional[datetime.datetime] = None
member_size: Optional[int] = None
usage: Optional[str] = None
[docs]
class GroupsApi(ApiChild, base='groups'):
"""
Groups contain a collection of members in Webex. A member represents a Webex user. A group is used to assign
templates and settings to the set of members contained in a group. To create and manage a group, including adding
and removing members from a group, an auth token containing the identity:groups_rw is required. Searching and
viewing members of a group requires an auth token with a scope of identity:groups_read.
To learn more about managing people to use as members in the /groups API please refer to the People API.
"""
[docs]
def list(
self,
include_members: bool = None,
attributes: str = None,
sort_by: str = None,
sort_order: str = None,
list_filter: str = None,
start_index: int = None,
count: int = None,
org_id: str = None,
**params,
) -> Generator[Group, None, None]:
"""
List groups in your organization.
:param include_members: Optionally return group members in the response. The maximum number of members returned
is 500.
:type include_members: bool
:param attributes: The attributes to return.
:type attributes: str
:param list_filter: Searches the group by `displayName` with an operator and a value. The available operators
are `eq` (equal) and `sw` (starts with). Only `displayName` can be used to filter results.
:type list_filter: str
:param sort_by: Sort the results based by group `displayName`.
:type sort_by: str
:param sort_order: Sort results alphabetically by group display name, in ascending or descending order.
:type sort_order: str
:param start_index: The index to start for group pagination.
:type start_index: int
:param count: Specifies the desired number of search results per page.
:type count: int
:param org_id: List groups in this organization. Only admin users of another organization (such as partners)
may use this parameter.
:type org_id: str
:param params:
:return: generator of :class:`Group` objects
"""
params.update(
(to_camel(k), v) for i, (k, v) in enumerate(locals().items()) if i and k != 'params' and v is not None
)
for k, v in params.items():
if isinstance(v, bool):
params[k] = 'true' if v else 'false'
if lf := params.pop('listFilter', None):
params['filter'] = lf
url = self.ep()
return self.session.follow_pagination(url=url, model=Group, item_key='groups', params=params)
[docs]
def create(self, settings: Group) -> Group:
"""
Create a new group using the provided settings. Only display_name is mandatory
:param settings: settings for new group
:type settings: Group
:return: new group
:rtype: :class:`Group`
"""
url = self.ep()
body = settings.model_dump_json(
exclude={
'group_id': True,
'members': {'__all__': {'member_type': True, 'display_name': True, 'operation': True}},
'created': True,
'last_modified': True,
}
)
data = self.post(url, data=body)
return Group.model_validate(data)
[docs]
def details(self, group_id: str, include_members: bool = None) -> Group:
"""
Get Group Details
Get details for a group, by ID.
Optionally, the members may be retrieved with this request. The maximum number of members returned is 500.
:param group_id: A unique identifier for the group.
:type group_id: str
:param include_members: Include the members as part of the response.
:type include_members: bool
:rtype: :class:`Group`
"""
url = self.ep(group_id)
params = dict()
if include_members is not None:
params['includeMembers'] = 'true' if include_members else 'false'
data = self.get(url, params=params)
return Group.model_validate(data)
[docs]
def members(self, group_id: str, **params) -> Generator[GroupMember, None, None]:
"""
Query members of a group
:param group_id: group id
:type group_id: str
:param params:
:return: generator of :class:`GroupMember` instances
"""
url = self.ep(f'{group_id}/Members')
return self.session.follow_pagination(url=url, model=GroupMember, params=params, item_key='members')
[docs]
def update(self, group_id: str, settings: Group = None, remove_all: bool = None) -> Group:
"""
Update a Group
Update the group details, by ID.
:param group_id:
:param settings:
:param remove_all:
:return:
"""
if not any((settings, remove_all)):
raise ValueError('settings or remove_all have to be present')
url = self.ep(group_id)
if settings:
body = settings.model_dump_json(
exclude={
'group_id': True,
'members': {'__all__': {'member_type': True, 'display_name': True}},
'created': True,
'last_modified': True,
}
)
else:
body = 'purgeAllValues:{"attributes":["members"]}'
data = self.patch(url, data=body)
return Group.model_validate(data)
[docs]
def delete_group(self, group_id: str) -> None:
"""
Delete a Group
Remove a group from the system.
Specify the group ID in the `groupId` parameter in the URI.
:param group_id: A unique identifier for the group.
:type group_id: str
:rtype: None
"""
url = self.ep(group_id)
self.delete(url)