paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-07 15:33:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

user_groups: Add docstrings for several functions.

Browse Source
This commit is contained in:
Tim Abbott
2024-09-30 18:00:44 -07:00
parent b554106e6d
commit 096fea48a0
1 changed files with 35 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
zerver/lib/user_groups.py
View File

@@ -80,6 +80,12 @@ def has_user_group_access_for_subgroup(
*,
allow_deactivated: bool = False,
) -> bool:
"""Minimal access control checks for whether the given group
is visible to the given user for use as a subgroup.
In the future, if groups whose existence is not visible to the
entire organization are added, this may grow more complex.
"""
if user_group.realm_id != user_profile.realm_id:
return False
@@ -97,6 +103,13 @@ def get_user_group_by_id_in_realm(
for_setting: bool = False,
allow_deactivated: bool = False,
) -> NamedUserGroup:
"""
Internal function for accessing a single user group from client
code. Locks the group if for_read is False.
Notably does not do any access control checks, beyond only fetching
groups from the provided realm.
"""
try:
if for_read:
user_group = NamedUserGroup.objects.get(id=user_group_id, realm=realm)
@@ -115,6 +128,12 @@ def get_user_group_by_id_in_realm(
def check_permission_for_managing_all_groups(
user_group: UserGroup, user_profile: UserProfile
) -> bool:
"""
Given a user and a group in the same realm, checks if the user
can manage the group through the legacy can_edit_all_user_groups
permission, which is a permission that requires either certain roles
or membership in the group itself to be used.
"""
can_edit_all_user_groups = user_profile.can_edit_all_user_groups()
if can_edit_all_user_groups:
if user_profile.is_realm_admin or user_profile.is_moderator:
@@ -131,6 +150,14 @@ def access_user_group_for_update(
permission_setting: str,
allow_deactivated: bool = False,
) -> NamedUserGroup:
"""
Main entry point that views code should call when planning to modify
a given user group on behalf of a given user.
The permission_setting parameter indicates what permission to check;
different features will be used when editing the membership vs.
security-sensitive settings on a group.
"""
user_group = get_user_group_by_id_in_realm(
user_group_id, user_profile.realm, for_read=False, allow_deactivated=allow_deactivated
)
@@ -159,6 +186,10 @@ def access_user_group_for_update(
def access_user_group_for_deactivation(
user_group_id: int, user_profile: UserProfile
) -> NamedUserGroup:
"""
Main security check / access function for whether the acting
user has permission to deactivate a given user group.
"""
user_group = access_user_group_for_update(
user_group_id, user_profile, permission_setting="can_manage_group"
)
@@ -408,6 +439,10 @@ def access_user_group_for_setting(
permission_configuration: GroupPermissionSetting,
current_setting_value: UserGroup | None = None,
) -> UserGroup:
"""Given a permission setting and specification of what value it
should have (setting_user_group), returns either a Named or
anonymous `UserGroup` with the requested membership.
"""
if isinstance(setting_user_group, int):
named_user_group = get_user_group_by_id_in_realm(
setting_user_group, user_profile.realm, for_read=False, for_setting=True