Skip to content

Teams Service

Team lifecycle management.

teams_lib_pzsp2_z1.services.teams.TeamsService

Bases: BaseService

Service for managing Microsoft Teams lifecycle and properties via the Go backend.

This class acts as a high-level Python wrapper. It delegates logical operations to the underlying Go library.

Concepts: * References: The teamRef argument accepts either the Team UUID or the Team Display Name. The Go backend resolves these automatically. * Context: Operations are executed on behalf of the authenticated user (derived from the MSAL context). * Caching: If the Go client was initialized with cache enabled, this service will transparently use cached team references to reduce API calls.

Source code in teams_lib_pzsp2_z1/services/teams.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
class TeamsService(BaseService):
    """Service for managing Microsoft Teams lifecycle and properties via the Go backend.

    This class acts as a high-level Python wrapper. It delegates logical operations
    to the underlying Go library.

    **Concepts:**
    * **References**: The `teamRef` argument accepts either the Team UUID or the
        Team Display Name. The Go backend resolves these automatically.
    * **Context**: Operations are executed on behalf of the authenticated user
        (derived from the MSAL context).
    * **Caching**: If the Go client was initialized with cache enabled, this service
        will transparently use cached team references to reduce API calls.
    """

    def get(self, team_ref: str) -> Team:
        """Retrieves a specific team by its reference.

        Args:
            team_ref (str): The reference to the team (UUID or Display Name).
        Returns:
            Team: The requested team object containing details like ID, DisplayName, and Visibility.
        """
        response = self.client.execute(
            cmd_type="request",
            method="getTeam",
            params={
                "teamRef": team_ref,
            },
        )

        return Team(
            id=response["ID"],
            display_name=response["DisplayName"],
            description=response["Description"],
            is_archived=(True if response["IsArchived"] else False),
            visibility=response["Visibility"],
        )

    def list_my_joined(self) -> list[Team]:
        """Lists all teams that the authenticated user has joined.

        Returns:
            list[Team]: A list of team objects the user is a member of.
        """
        response = self.client.execute(
            cmd_type="request",
            method="listMyJoined",
            params={},
        )
        return [
            Team(
                id=team["ID"],
                display_name=team["DisplayName"],
                description=team["Description"],
                is_archived=(True if team["IsArchived"] else False),
                visibility=team["Visibility"],
            )
            for team in response
        ]

    def update(self, team_ref: str, update: UpdateTeam) -> Team:
        """Applies updates to a team's properties.

        Only fields that are not None in the `update` object will be modified.

        Args:
            team_ref (str): The reference to the team (UUID or Display Name).
            update (UpdateTeam): An object containing the fields to update (e.g., DisplayName).

        Returns:
            Team: The updated team object.
        """
        params = {"teamRef": team_ref}
        # Filter out None values to perform a PATCH-like update
        update_dict = {k: v for k, v in update.__dict__.items() if v is not None}
        params["team"] = update_dict

        response = self.client.execute(
            cmd_type="request",
            method="updateTeam",
            params=params,
        )
        return Team(
            id=response["ID"],
            display_name=response["DisplayName"],
            description=response["Description"],
            is_archived=(True if response["IsArchived"] else False),
            visibility=response["Visibility"],
        )

    def create_via_group(
        self, display_name: str, mail_nickname: str, visibility: str
    ) -> Team:
        """Creates a new team associated with a standard Microsoft 365 group.

        Args:
            display_name (str): The name of the new team.
            mail_nickname (str): The mail alias for the underlying group.
            visibility (str): The privacy level ('Public' or 'Private').

        Returns:
            Team: The newly created team object.
        """
        response = self.client.execute(
            cmd_type="request",
            method="createTeamViaGroup",
            params={
                "displayName": display_name,
                "mailNickname": mail_nickname,
                "visibility": visibility,
            },
        )
        return Team(
            id=response["ID"],
            display_name=response["DisplayName"],
            description=response["Description"],
            is_archived=(True if response["IsArchived"] else False),
            visibility=response["Visibility"],
        )

    def create_from_template(  # noqa: PLR0913
        self,
        display_name: str,
        description: str,
        owners: list[str],
        members: list[str] | None = None,
        visibility: str = "public",
        include_me: bool = True,
    ) -> str:
        """Creates a new team based on a template.

        This operation is often asynchronous.

        Args:
            display_name (str): The name of the team.
            description (str): A brief description of the team.
            owners (list[str]): A list of user references (IDs or emails) to be owners.
            members (list[str] | None, optional): A list of user references to be members. Defaults to None.
            visibility (str, optional): The privacy level ('public' or 'private'). Defaults to "public".
            include_me (bool, optional): Whether to add the authenticated user as an owner. Defaults to True.

        Returns:
            str: The ID of the newly created team (or the async operation ID).
        """
        response = self.client.execute(
            cmd_type="request",
            method="createTeamFromTemplate",
            params={
                "displayName": display_name,
                "description": description,
                "owners": owners,
                "members": members,
                "visibility": visibility,
                "includeMe": include_me,
            },
        )
        return response

    def archive(self, team_ref: str, spo_read_only_from_members: bool) -> bool:
        """Archives a team.

        Args:
            team_ref (str): The reference to the team (UUID or Display Name).
            spo_read_only_from_members (bool): If True, sets the associated SharePoint site
                to read-only for members.

        Returns:
            bool: True if the team was successfully archived.
        """
        response = self.client.execute(
            cmd_type="request",
            method="archiveTeam",
            params={
                "teamRef": team_ref,
                "spoReadOnlyFromMembers": spo_read_only_from_members,
            },
        )
        return response == "archived"

    def unarchive(self, team_ref: str) -> bool:
        """Restores an archived team to an active state.

        Args:
            team_ref (str): The reference to the team (UUID or Display Name).
        Returns:
            bool: True if the team was successfully unarchived.
        """
        response = self.client.execute(
            cmd_type="request",
            method="unarchiveTeam",
            params={
                "teamRef": team_ref,
            },
        )
        return response == "unarchived"

    def delete(self, team_ref: str) -> bool:
        """Deletes a team (soft delete).

        Args:
            team_ref (str): The reference to the team (UUID or Display Name).
        Returns:
            bool: True if the delete request was successful.
        """
        response = self.client.execute(
            cmd_type="request",
            method="deleteTeam",
            params={
                "teamRef": team_ref,
            },
        )
        return response == "deleted"

    def restore_deleted(self, deleted_team_ID: str) -> str:
        """Restores a previously deleted team.

        Args:
            deleted_team_ID (str): The ID of the deleted group/team.

        Returns:
            str: The ID of the restored team/group.
        """
        response = self.client.execute(
            cmd_type="request",
            method="restoreDeletedTeam",
            params={
                "deletedGroupID": deleted_team_ID,
            },
        )
        return response

Functions

archive(team_ref, spo_read_only_from_members)

Archives a team.

Parameters:

Name Type Description Default
team_ref str

The reference to the team (UUID or Display Name).

 required
spo_read_only_from_members bool

If True, sets the associated SharePoint site to read-only for members.

 required

Returns:

Name Type Description
bool bool

True if the team was successfully archived.
Source code in teams_lib_pzsp2_z1/services/teams.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def archive(self, team_ref: str, spo_read_only_from_members: bool) -> bool:
    """Archives a team.

    Args:
        team_ref (str): The reference to the team (UUID or Display Name).
        spo_read_only_from_members (bool): If True, sets the associated SharePoint site
            to read-only for members.

    Returns:
        bool: True if the team was successfully archived.
    """
    response = self.client.execute(
        cmd_type="request",
        method="archiveTeam",
        params={
            "teamRef": team_ref,
            "spoReadOnlyFromMembers": spo_read_only_from_members,
        },
    )
    return response == "archived"

create_from_template(display_name, description, owners, members=None, visibility='public', include_me=True)

Creates a new team based on a template.

This operation is often asynchronous.

Parameters:

Name Type Description Default
display_name str

The name of the team.

 required
description str

A brief description of the team.

 required
owners list[str]

A list of user references (IDs or emails) to be owners.

 required
members list[str] | None

A list of user references to be members. Defaults to None.

 None
visibility str

The privacy level ('public' or 'private'). Defaults to "public".

 'public'
include_me bool

Whether to add the authenticated user as an owner. Defaults to True.

 True

Returns:

Name Type Description
str str

The ID of the newly created team (or the async operation ID).
Source code in teams_lib_pzsp2_z1/services/teams.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def create_from_template(  # noqa: PLR0913
    self,
    display_name: str,
    description: str,
    owners: list[str],
    members: list[str] | None = None,
    visibility: str = "public",
    include_me: bool = True,
) -> str:
    """Creates a new team based on a template.

    This operation is often asynchronous.

    Args:
        display_name (str): The name of the team.
        description (str): A brief description of the team.
        owners (list[str]): A list of user references (IDs or emails) to be owners.
        members (list[str] | None, optional): A list of user references to be members. Defaults to None.
        visibility (str, optional): The privacy level ('public' or 'private'). Defaults to "public".
        include_me (bool, optional): Whether to add the authenticated user as an owner. Defaults to True.

    Returns:
        str: The ID of the newly created team (or the async operation ID).
    """
    response = self.client.execute(
        cmd_type="request",
        method="createTeamFromTemplate",
        params={
            "displayName": display_name,
            "description": description,
            "owners": owners,
            "members": members,
            "visibility": visibility,
            "includeMe": include_me,
        },
    )
    return response

create_via_group(display_name, mail_nickname, visibility)

Creates a new team associated with a standard Microsoft 365 group.

Parameters:

Name Type Description Default
display_name str

The name of the new team.

 required
mail_nickname str

The mail alias for the underlying group.

 required
visibility str

The privacy level ('Public' or 'Private').

 required

Returns:

Name Type Description
Team Team

The newly created team object.
Source code in teams_lib_pzsp2_z1/services/teams.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def create_via_group(
    self, display_name: str, mail_nickname: str, visibility: str
) -> Team:
    """Creates a new team associated with a standard Microsoft 365 group.

    Args:
        display_name (str): The name of the new team.
        mail_nickname (str): The mail alias for the underlying group.
        visibility (str): The privacy level ('Public' or 'Private').

    Returns:
        Team: The newly created team object.
    """
    response = self.client.execute(
        cmd_type="request",
        method="createTeamViaGroup",
        params={
            "displayName": display_name,
            "mailNickname": mail_nickname,
            "visibility": visibility,
        },
    )
    return Team(
        id=response["ID"],
        display_name=response["DisplayName"],
        description=response["Description"],
        is_archived=(True if response["IsArchived"] else False),
        visibility=response["Visibility"],
    )

delete(team_ref)

Deletes a team (soft delete).

Parameters:

Name Type Description Default
team_ref str

The reference to the team (UUID or Display Name).

 required

Returns: bool: True if the delete request was successful.

Source code in teams_lib_pzsp2_z1/services/teams.py 
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def delete(self, team_ref: str) -> bool:
    """Deletes a team (soft delete).

    Args:
        team_ref (str): The reference to the team (UUID or Display Name).
    Returns:
        bool: True if the delete request was successful.
    """
    response = self.client.execute(
        cmd_type="request",
        method="deleteTeam",
        params={
            "teamRef": team_ref,
        },
    )
    return response == "deleted"

get(team_ref)

Retrieves a specific team by its reference.

Parameters:

Name Type Description Default
team_ref str

The reference to the team (UUID or Display Name).

 required

Returns: Team: The requested team object containing details like ID, DisplayName, and Visibility.

Source code in teams_lib_pzsp2_z1/services/teams.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def get(self, team_ref: str) -> Team:
    """Retrieves a specific team by its reference.

    Args:
        team_ref (str): The reference to the team (UUID or Display Name).
    Returns:
        Team: The requested team object containing details like ID, DisplayName, and Visibility.
    """
    response = self.client.execute(
        cmd_type="request",
        method="getTeam",
        params={
            "teamRef": team_ref,
        },
    )

    return Team(
        id=response["ID"],
        display_name=response["DisplayName"],
        description=response["Description"],
        is_archived=(True if response["IsArchived"] else False),
        visibility=response["Visibility"],
    )

list_my_joined()

Lists all teams that the authenticated user has joined.

Returns:

Type Description
list[Team]

list[Team]: A list of team objects the user is a member of.
Source code in teams_lib_pzsp2_z1/services/teams.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def list_my_joined(self) -> list[Team]:
    """Lists all teams that the authenticated user has joined.

    Returns:
        list[Team]: A list of team objects the user is a member of.
    """
    response = self.client.execute(
        cmd_type="request",
        method="listMyJoined",
        params={},
    )
    return [
        Team(
            id=team["ID"],
            display_name=team["DisplayName"],
            description=team["Description"],
            is_archived=(True if team["IsArchived"] else False),
            visibility=team["Visibility"],
        )
        for team in response
    ]

restore_deleted(deleted_team_ID)

Restores a previously deleted team.

Parameters:

Name Type Description Default
deleted_team_ID str

The ID of the deleted group/team.

 required

Returns:

Name Type Description
str str

The ID of the restored team/group.
Source code in teams_lib_pzsp2_z1/services/teams.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def restore_deleted(self, deleted_team_ID: str) -> str:
    """Restores a previously deleted team.

    Args:
        deleted_team_ID (str): The ID of the deleted group/team.

    Returns:
        str: The ID of the restored team/group.
    """
    response = self.client.execute(
        cmd_type="request",
        method="restoreDeletedTeam",
        params={
            "deletedGroupID": deleted_team_ID,
        },
    )
    return response

unarchive(team_ref)

Restores an archived team to an active state.

Parameters:

Name Type Description Default
team_ref str

The reference to the team (UUID or Display Name).

 required

Returns: bool: True if the team was successfully unarchived.

Source code in teams_lib_pzsp2_z1/services/teams.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
def unarchive(self, team_ref: str) -> bool:
    """Restores an archived team to an active state.

    Args:
        team_ref (str): The reference to the team (UUID or Display Name).
    Returns:
        bool: True if the team was successfully unarchived.
    """
    response = self.client.execute(
        cmd_type="request",
        method="unarchiveTeam",
        params={
            "teamRef": team_ref,
        },
    )
    return response == "unarchived"

update(team_ref, update)

Applies updates to a team's properties.

Only fields that are not None in the update object will be modified.

Parameters:

Name Type Description Default
team_ref str

The reference to the team (UUID or Display Name).

 required
update UpdateTeam

An object containing the fields to update (e.g., DisplayName).

 required

Returns:

Name Type Description
Team Team

The updated team object.
Source code in teams_lib_pzsp2_z1/services/teams.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def update(self, team_ref: str, update: UpdateTeam) -> Team:
    """Applies updates to a team's properties.

    Only fields that are not None in the `update` object will be modified.

    Args:
        team_ref (str): The reference to the team (UUID or Display Name).
        update (UpdateTeam): An object containing the fields to update (e.g., DisplayName).

    Returns:
        Team: The updated team object.
    """
    params = {"teamRef": team_ref}
    # Filter out None values to perform a PATCH-like update
    update_dict = {k: v for k, v in update.__dict__.items() if v is not None}
    params["team"] = update_dict

    response = self.client.execute(
        cmd_type="request",
        method="updateTeam",
        params=params,
    )
    return Team(
        id=response["ID"],
        display_name=response["DisplayName"],
        description=response["Description"],
        is_archived=(True if response["IsArchived"] else False),
        visibility=response["Visibility"],
    )