Groups

class Groups(session_kwargs, client, return_type='raw')

Civis API /groups endpoint:

import civis
client = civis.APIClient()
# Call client.groups.<method>(<arguments>) to make a request, e.g.:
client.groups.list(...)

Methods

`delete_members`(id, user_id)	Remove a user from a group
`delete_shares_groups`(id, group_id)	Revoke the permissions a group has on this object
`delete_shares_users`(id, user_id)	Revoke the permissions a user has on this object
`get`(id)	Get a Group
`get_child_groups`(id)	Get child groups of this group
`list`(*[, query, permission, ...])	List Groups
`list_child_groups`(id)	Get child groups of this group
`list_shares`(id)	List users and groups permissioned on this object
`patch`(id, *[, name, description, slug, ...])	Update some attributes of this Group
`post`(name, *[, description, slug, ...])	Create a Group
`put`(id, name, *[, description, slug, ...])	Replace all attributes of this Group
`put_members`(id, user_id)	Add a user to a group
`put_shares_groups`(id, group_ids, ...[, ...])	Set the permissions groups has on this object
`put_shares_users`(id, user_ids, ...[, ...])	Set the permissions users have on this object

delete_members(id: int, user_id: int) → Response

Remove a user from a group

API URL: DELETE /groups/{id}/members/{user_id}

Parameters:

idint: The ID of the group.
user_idint: The ID of the user.

Returns:

None: Response code 204: success

delete_shares_groups(id: int, group_id: int) → Response

Revoke the permissions a group has on this object

API URL: DELETE /groups/{id}/shares/groups/{group_id}

Parameters:

idint: The ID of the resource that is shared.
group_idint: The ID of the group.

Returns:

None: Response code 204: success

delete_shares_users(id: int, user_id: int) → Response

Revoke the permissions a user has on this object

API URL: DELETE /groups/{id}/shares/users/{user_id}

Parameters:

idint: The ID of the resource that is shared.
user_idint: The ID of the user.

Returns:

None: Response code 204: success

get(id: int) → Response

Get a Group

API URL: GET /groups/{id}

Parameters:

idint

Returns:

civis.Response

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
default_otp_required_for_loginbool
The two factor authentication requirement for this group.
role_idsList[int]
An array of ids of all the roles this group has.
default_time_zonestr
The default time zone of this group.
default_jobs_labelstr
The default partition label for jobs of this group.
default_notebooks_labelstr
The default partition label for notebooks of this group.
default_services_labelstr
The default partition label for services of this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.
- emailstr
  This user’s email address.
- primary_group_idint
  The ID of the primary group of this user.
- activebool
  Whether this user account is active or deactivated.

get_child_groups(id: int) → Response

Get child groups of this group

API URL: GET /groups/{id}/child_groups

Parameters:

idint: The ID of this group.

Returns:

civis.Response

manageableList[civis.Response]
- id : int
- name : str
writeableList[civis.Response]
- id : int
- name : str
readableList[civis.Response]
- id : int
- name : str

list(*, query: str = None, permission: str = None, include_members: bool = None, organization_id: int = None, user_ids: List[int] = None, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None) → ListResponse | PaginatedResponse

List Groups

API URL: GET /groups

Parameters:

querystr, optional: If specified, it will filter the groups returned.
permissionstr, optional: A permissions string, one of “read”, “write”, or “manage”. Lists only groups for which the current user has that permission.
include_membersbool, optional: Show members of the group.
organization_idint, optional: The organization by which to filter groups.
user_idsList[int], optional: A list of user IDs to filter groups by.Groups will be returned if any of the users is a member
limitint, optional: Number of results to return. Defaults to 50. Maximum allowed is 1000.
page_numint, optional: Page number of the results to return. Defaults to the first page, 1.
orderstr, optional: The field on which to order the result set. Defaults to name. Must be one of: name, created_at.
order_dirstr, optional: Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.
iteratorbool, optional: If True, return a generator (specifically, a civis.PaginatedResponse object) to iterate over all responses. Use it when more results than the maximum allowed by ‘limit’ are needed. When True, ‘page_num’ is ignored. If False, return a civis.ListResponse object (= a list of civis.Response objects), whose size is determined by ‘limit’. Defaults to False.

Returns:

civis.ListResponse | civis.PaginatedResponse

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.

list_child_groups(id: int) → ListResponse

Get child groups of this group

API URL: GET /groups/{id}/child_groups

Warning

The method name <client>.groups.list_child_groups is deprecated and will be removed at civis-python v3.0.0 (no release timeline yet). Please switch to <client>.groups.get_child_groups for the same method.

Parameters:

idint: The ID of this group.

Returns:

civis.Response

manageableList[civis.Response]
- id : int
- name : str
writeableList[civis.Response]
- id : int
- name : str
readableList[civis.Response]
- id : int
- name : str

list_shares(id: int) → ListResponse

List users and groups permissioned on this object

API URL: GET /groups/{id}/shares

Parameters:

idint: The ID of the resource that is shared.

Returns:

civis.ListResponse

readerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
writerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
ownerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

patch(id: int, *, name: str = None, description: str = None, slug: str = None, organization_id: int = None, default_otp_required_for_login: bool = None, role_ids: List[int] = None, default_time_zone: str = None, default_jobs_label: str = None, default_notebooks_label: str = None, default_services_label: str = None) → Response

Update some attributes of this Group

API URL: PATCH /groups/{id}

Parameters:

idint: The ID of this group.
namestr, optional: This group’s name.
descriptionstr, optional: The description of the group.
slugstr, optional: The slug for this group.
organization_idint, optional: The ID of the organization this group belongs to.
default_otp_required_for_loginbool, optional: The two factor authentication requirement for this group.
role_idsList[int], optional: An array of ids of all the roles this group has.
default_time_zonestr, optional: The default time zone of this group.
default_jobs_labelstr, optional: The default partition label for jobs of this group.
default_notebooks_labelstr, optional: The default partition label for notebooks of this group.
default_services_labelstr, optional: The default partition label for services of this group.

Returns:

civis.Response

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
default_otp_required_for_loginbool
The two factor authentication requirement for this group.
role_idsList[int]
An array of ids of all the roles this group has.
default_time_zonestr
The default time zone of this group.
default_jobs_labelstr
The default partition label for jobs of this group.
default_notebooks_labelstr
The default partition label for notebooks of this group.
default_services_labelstr
The default partition label for services of this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.
- emailstr
  This user’s email address.
- primary_group_idint
  The ID of the primary group of this user.
- activebool
  Whether this user account is active or deactivated.

post(name: str, *, description: str = None, slug: str = None, organization_id: int = None, default_otp_required_for_login: bool = None, role_ids: List[int] = None, default_time_zone: str = None, default_jobs_label: str = None, default_notebooks_label: str = None, default_services_label: str = None) → Response

Create a Group

API URL: POST /groups

Parameters:

namestr: This group’s name.
descriptionstr, optional: The description of the group.
slugstr, optional: The slug for this group.
organization_idint, optional: The ID of the organization this group belongs to.
default_otp_required_for_loginbool, optional: The two factor authentication requirement for this group.
role_idsList[int], optional: An array of ids of all the roles this group has.
default_time_zonestr, optional: The default time zone of this group.
default_jobs_labelstr, optional: The default partition label for jobs of this group.
default_notebooks_labelstr, optional: The default partition label for notebooks of this group.
default_services_labelstr, optional: The default partition label for services of this group.

Returns:

civis.Response

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
default_otp_required_for_loginbool
The two factor authentication requirement for this group.
role_idsList[int]
An array of ids of all the roles this group has.
default_time_zonestr
The default time zone of this group.
default_jobs_labelstr
The default partition label for jobs of this group.
default_notebooks_labelstr
The default partition label for notebooks of this group.
default_services_labelstr
The default partition label for services of this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.
- emailstr
  This user’s email address.
- primary_group_idint
  The ID of the primary group of this user.
- activebool
  Whether this user account is active or deactivated.

put(id: int, name: str, *, description: str = None, slug: str = None, organization_id: int = None, default_otp_required_for_login: bool = None, role_ids: List[int] = None, default_time_zone: str = None, default_jobs_label: str = None, default_notebooks_label: str = None, default_services_label: str = None) → Response

Replace all attributes of this Group

API URL: PUT /groups/{id}

Parameters:

idint: The ID of this group.
namestr: This group’s name.
descriptionstr, optional: The description of the group.
slugstr, optional: The slug for this group.
organization_idint, optional: The ID of the organization this group belongs to.
default_otp_required_for_loginbool, optional: The two factor authentication requirement for this group.
role_idsList[int], optional: An array of ids of all the roles this group has.
default_time_zonestr, optional: The default time zone of this group.
default_jobs_labelstr, optional: The default partition label for jobs of this group.
default_notebooks_labelstr, optional: The default partition label for notebooks of this group.
default_services_labelstr, optional: The default partition label for services of this group.

Returns:

civis.Response

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
default_otp_required_for_loginbool
The two factor authentication requirement for this group.
role_idsList[int]
An array of ids of all the roles this group has.
default_time_zonestr
The default time zone of this group.
default_jobs_labelstr
The default partition label for jobs of this group.
default_notebooks_labelstr
The default partition label for notebooks of this group.
default_services_labelstr
The default partition label for services of this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.
- emailstr
  This user’s email address.
- primary_group_idint
  The ID of the primary group of this user.
- activebool
  Whether this user account is active or deactivated.

put_members(id: int, user_id: int) → Response

Add a user to a group

API URL: PUT /groups/{id}/members/{user_id}

Parameters:

idint: The ID of the group.
user_idint: The ID of the user.

Returns:

civis.Response

idint
The ID of this group.
namestr
This group’s name.
created_atstr (time)
The date and time when this group was created.
updated_atstr (time)
The date and time when this group was last updated.
descriptionstr
The description of the group.
slugstr
The slug for this group.
organization_idint
The ID of the organization this group belongs to.
organization_namestr
The name of the organization this group belongs to.
member_countint
The number of active members in this group.
total_member_countint
The total number of members in this group.
default_otp_required_for_loginbool
The two factor authentication requirement for this group.
role_idsList[int]
An array of ids of all the roles this group has.
default_time_zonestr
The default time zone of this group.
default_jobs_labelstr
The default partition label for jobs of this group.
default_notebooks_labelstr
The default partition label for notebooks of this group.
default_services_labelstr
The default partition label for services of this group.
last_updated_by_idint
The ID of the user who last updated this group.
created_by_idint
The ID of the user who created this group.
membersList[civis.Response]
The members of this group.
- idint
  The ID of this user.
- namestr
  This user’s name.
- usernamestr
  This user’s username.
- initialsstr
  This user’s initials.
- onlinebool
  Whether this user is online.
- emailstr
  This user’s email address.
- primary_group_idint
  The ID of the primary group of this user.
- activebool
  Whether this user account is active or deactivated.

put_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None) → Response

Set the permissions groups has on this object

API URL: PUT /groups/{id}/shares/groups

Parameters:

idint: The ID of the resource that is shared.
group_idsList[int]: An array of one or more group IDs.
permission_levelstr: Options are: “read”, “write”, or “manage”.
share_email_bodystr, optional: Custom body text for e-mail sent on a share.
send_shared_emailbool, optional: Send email to the recipients of a share.

Returns:

civis.Response

readerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
writerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
ownerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None) → Response

Set the permissions users have on this object

API URL: PUT /groups/{id}/shares/users

Parameters:

idint: The ID of the resource that is shared.
user_idsList[int]: An array of one or more user IDs.
permission_levelstr: Options are: “read”, “write”, or “manage”.
share_email_bodystr, optional: Custom body text for e-mail sent on a share.
send_shared_emailbool, optional: Send email to the recipients of a share.

Returns:

civis.Response

readerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
writerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
ownerscivis.Response
- usersList[civis.Response]
  
  id : int
  
  name : str
- groupsList[civis.Response]
  
  id : int
  
  name : str
total_user_sharesint
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_sharesint
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.