openedx.core.djangoapps.course_groups package

Contents

openedx.core.djangoapps.course_groups package#

Subpackages#

Submodules#

openedx.core.djangoapps.course_groups.api module#

course_groups API

openedx.core.djangoapps.course_groups.api.remove_user_from_cohort(course_key, username, cohort_id=None)#

Removes an user from a course group.

openedx.core.djangoapps.course_groups.cohorts module#

This file contains the logic for cohorts, as exposed internally to the forums, and to the cohort admin views.

openedx.core.djangoapps.course_groups.cohorts.add_cohort(course_key, name, assignment_type)#

Add a cohort to a course. Raises ValueError if a cohort of the same name already exists.

openedx.core.djangoapps.course_groups.cohorts.add_user_to_cohort(cohort, username_or_email_or_user)#

Look up the given user, and if successful, add them to the specified cohort.

Parameters:

  • cohort – CourseUserGroup

  • username_or_email_or_user – user or string. Treated as email if has ‘@’

Returns:

User object (or None if the email address is preassigned), string (or None) indicating previous cohort, and whether the user is a preassigned user or not

Raises:

  • User.DoesNotExist if can't find user. However, if a valid email is provided for the user, it is stored –

  • in a database so that the user can be added to the cohort if they eventually enroll in the course. –

  • ValueError if user already present in this cohort. –

  • ValidationError if an invalid email address is entered. –

  • User.DoesNotExist if a user could not be found. –

openedx.core.djangoapps.course_groups.cohorts.bulk_cache_cohorts(course_key, users)#

Pre-fetches and caches the cohort assignments for the given users, for later fast retrieval by get_cohort.

openedx.core.djangoapps.course_groups.cohorts.get_assignment_type(user_group)#

Get assignment type for cohort.

openedx.core.djangoapps.course_groups.cohorts.get_cohort(user, course_key, assign=True, use_cached=False)#

Returns the user’s cohort for the specified course.

The cohort for the user is cached for the duration of a request. Pass use_cached=True to use the cached value instead of fetching from the database.

Parameters:

  • user – a Django User object.

  • course_key – CourseKey

  • assign (bool) – if False then we don’t assign a group to user

  • use_cached (bool) – Whether to use the cached value or fetch from database.

Returns:

A CourseUserGroup object if the course is cohorted and the User has a cohort, else None.

Raises:

ValueError if the CourseKey doesn't exist. –

openedx.core.djangoapps.course_groups.cohorts.get_cohort_by_id(course_key, cohort_id)#

Return the CourseUserGroup object for the given cohort. Raises DoesNotExist it isn’t present. Uses the course_key for extra validation.

openedx.core.djangoapps.course_groups.cohorts.get_cohort_by_name(course_key, name)#

Return the CourseUserGroup object for the given cohort. Raises DoesNotExist it isn’t present.

openedx.core.djangoapps.course_groups.cohorts.get_cohort_id(user, course_key, use_cached=False)#

Given a course key and a user, return the id of the cohort that user is assigned to in that course. If they don’t have a cohort, return None.

openedx.core.djangoapps.course_groups.cohorts.get_cohort_names(course)#

Return a dict that maps cohort ids to names for the given course

openedx.core.djangoapps.course_groups.cohorts.get_cohorted_user_partition_id(course_key)#

Returns the partition id to which cohorts are linked or None if there is no cohort linked to a content group.

openedx.core.djangoapps.course_groups.cohorts.get_course_cohort_id(course_key)#

Given a course key, return the int id for the cohort settings.

Raises:

Http404 if the course doesn't exist. –

openedx.core.djangoapps.course_groups.cohorts.get_course_cohorts(course=None, course_id=None, assignment_type=None, ordering='asc')#

Get a list of all the cohorts in the given course. This will include auto cohorts, regardless of whether or not the auto cohorts include any users.

Parameters:

  • course – the course for which cohorts should be returned

  • assignment_type – cohort assignment type

  • ordering – sort direction for results by name. Use ‘desc’ for descending order. Any other value (including the default ‘asc’) results in ascending order.

Returns:

A list of CourseUserGroup objects. Empty if there are no cohorts. Does not check whether the course is cohorted.

openedx.core.djangoapps.course_groups.cohorts.get_group_info_for_cohort(cohort, use_cached=False)#

Get the ids of the group and partition to which this cohort has been linked as a tuple of (int, int).

If the cohort has not been linked to any group/partition, both values in the tuple will be None.

The partition group info is cached for the duration of a request. Pass use_cached=True to use the cached value instead of fetching from the database.

openedx.core.djangoapps.course_groups.cohorts.get_legacy_discussion_settings(course_key)#
openedx.core.djangoapps.course_groups.cohorts.get_random_cohort(course_key)#

Helper method to get a cohort for random assignment.

If there are multiple cohorts of type RANDOM in the course, one of them will be randomly selected. If there are no existing cohorts of type RANDOM in the course, one will be created.

openedx.core.djangoapps.course_groups.cohorts.is_cohort_exists(course_key, name)#

Check if a cohort already exists.

openedx.core.djangoapps.course_groups.cohorts.is_course_cohorted(course_key)#

Given a course key, return a boolean for whether or not the course is cohorted.

Raises:

Http404 if the course doesn't exist. –

openedx.core.djangoapps.course_groups.cohorts.is_last_random_cohort(user_group)#

Check if this cohort is the only random cohort in the course.

openedx.core.djangoapps.course_groups.cohorts.local_random()#

Get the local random number generator. In a function so that we don’t run random.Random() at import time.

openedx.core.djangoapps.course_groups.cohorts.migrate_cohort_settings(course)#

Migrate all the cohort settings associated with this course from modulestore to mysql. After that we will never touch modulestore for any cohort related settings.

openedx.core.djangoapps.course_groups.cohorts.remove_user_from_cohort(cohort, username_or_email)#

Look up the given user, and if successful, remove them from the specified cohort.

Parameters:

  • cohort – CourseUserGroup

  • username_or_email – string. Treated as email if has ‘@’

Raises:

  • User.DoesNotExist if can't find user. –

  • ValueError if user not already present in this cohort. –

openedx.core.djangoapps.course_groups.cohorts.set_assignment_type(user_group, assignment_type)#

Set assignment type for cohort.

openedx.core.djangoapps.course_groups.cohorts.set_course_cohorted(course_key, cohorted)#

Given a course course and a boolean, sets whether or not the course is cohorted.

Raises:

Value error if cohorted is not a boolean –

openedx.core.djangoapps.course_groups.constants module#

Constants for course groups.

openedx.core.djangoapps.course_groups.models module#

Django models related to course groups functionality.

exception openedx.core.djangoapps.course_groups.models.CohortAssignmentNotAllowed#

Bases: CohortMembershipException

exception openedx.core.djangoapps.course_groups.models.CohortChangeNotAllowed#

Bases: CohortMembershipException

class openedx.core.djangoapps.course_groups.models.CohortMembership(*args, **kwargs)#

Bases: Model

Used internally to enforce our particular definition of uniqueness.

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

classmethod assign(cohort, user)#

Assign user to cohort, switching them to this cohort if they had previously been assigned to another cohort Returns CohortMembership, previous_cohort (if any)

clean()#

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clean_fields(*args, **kwargs)#

Clean all fields and raise a ValidationError containing a dict of all validation errors if any occur.

course_id#

DO NOT REUSE THIS CLASS. Provided for backwards compatibility only!

A placeholder class that provides a way to set the attribute on the model.

course_user_group#

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

course_user_group_id#
id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
save(*args, **kwargs)#

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

user#

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

user_id#
exception openedx.core.djangoapps.course_groups.models.CohortMembershipException#

Bases: Exception

class openedx.core.djangoapps.course_groups.models.CourseCohort(*args, **kwargs)#

Bases: Model

This model represents cohort related info.

ASSIGNMENT_TYPE_CHOICES = (('random', 'Random'), ('manual', 'Manual'))#
exception DoesNotExist#

Bases: ObjectDoesNotExist

MANUAL = 'manual'#
exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

RANDOM = 'random'#
assignment_type#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

course_user_group#

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Restaurant.place is a ForwardOneToOneDescriptor instance.

course_user_group_id#
classmethod create(cohort_name=None, course_id=None, course_user_group=None, assignment_type='manual')#

Create a complete(CourseUserGroup + CourseCohort) object.

Parameters:

  • cohort_name – Name of the cohort to be created

  • course_id – Course Id

  • course_user_group – CourseUserGroup

  • assignment_type – ‘random’ or ‘manual’

get_assignment_type_display(*, field=<django.db.models.fields.CharField: assignment_type>)#
id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
class openedx.core.djangoapps.course_groups.models.CourseCohortsSettings(*args, **kwargs)#

Bases: Model

This model represents cohort settings for courses. The only non-deprecated fields are is_cohorted and course_id.

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

always_cohort_inline_discussions#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property cohorted_discussions#

DEPRECATED– DO NOT USE. Instead use CourseDiscussionSettings.divided_discussions via CourseDiscussionSettings.get.

course_id#

DO NOT REUSE THIS CLASS. Provided for backwards compatibility only!

A placeholder class that provides a way to set the attribute on the model.

id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

is_cohorted#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
class openedx.core.djangoapps.course_groups.models.CourseUserGroup(*args, **kwargs)#

Bases: Model

This model represents groups of users in a course. Groups may have different types, which may be treated specially. For example, a user can be in at most one cohort per course, and cohorts are used to split up the forums by group.

COHORT = 'cohort'#
exception DoesNotExist#

Bases: ObjectDoesNotExist

GROUP_TYPE_CHOICES = (('cohort', 'Cohort'),)#
exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

cohort#

Accessor to the related object on the reverse side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Place.restaurant is a ReverseOneToOneDescriptor instance.

cohortmembership_set#

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

cohorttarget_set#

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

course_id#

DO NOT REUSE THIS CLASS. Provided for backwards compatibility only!

A placeholder class that provides a way to set the attribute on the model.

courseusergrouppartitiongroup#

Accessor to the related object on the reverse side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Place.restaurant is a ReverseOneToOneDescriptor instance.

classmethod create(name, course_id, group_type='cohort')#

Create a new course user group.

Parameters:

  • name – Name of group

  • course_id – course id

  • group_type – group type

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

get_group_type_display(*, field=<django.db.models.fields.CharField: group_type>)#
group_type#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
unregisteredlearnercohortassignments_set#

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

users#

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

class openedx.core.djangoapps.course_groups.models.CourseUserGroupPartitionGroup(*args, **kwargs)#

Bases: Model

Create User Partition Info.

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

course_user_group#

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Restaurant.place is a ForwardOneToOneDescriptor instance.

course_user_group_id#
created_at#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

get_next_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)#
get_next_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=True, **kwargs)#
get_previous_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)#
get_previous_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=False, **kwargs)#
group_id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
partition_id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

updated_at#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class openedx.core.djangoapps.course_groups.models.UnregisteredLearnerCohortAssignments(*args, **kwargs)#

Bases: DeletableByUserValue, Model

Tracks the assignment of an unregistered learner to a course’s cohort.

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

course_id#

DO NOT REUSE THIS CLASS. Provided for backwards compatibility only!

A placeholder class that provides a way to set the attribute on the model.

course_user_group#

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

course_user_group_id#
email#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
classmethod redact_before_delete_fields()#

Redact email before deleting records for downstream soft-delete systems.

openedx.core.djangoapps.course_groups.models.remove_user_from_cohort(sender, instance, **kwargs)#

Ensures that when a CohortMemebrship is deleted, the underlying CourseUserGroup has its users list updated to reflect the change as well.

openedx.core.djangoapps.course_groups.partition_scheme module#

Provides a UserPartition driver for cohorts.

class openedx.core.djangoapps.course_groups.partition_scheme.CohortPartitionScheme#

Bases: object

This scheme uses lms cohorts (CourseUserGroups) and cohort-partition mappings (CourseUserGroupPartitionGroup) to map lms users into Partition Groups.

classmethod get_group_for_user(course_key, user, user_partition, use_cached=True)#

Returns the Group from the specified user partition to which the user is assigned, via their cohort membership and any mappings from cohorts to partitions / groups that might exist.

If the user has not yet been assigned to a cohort, an assignment might be created on-the-fly, as determined by the course’s cohort config. Any such side-effects will be triggered inside the call to cohorts.get_cohort().

If the user has no cohort mapping, or there is no (valid) cohort -> partition group mapping found, the function returns None.

openedx.core.djangoapps.course_groups.partition_scheme.get_cohorted_user_partition(course)#

Returns the first user partition from the specified course which uses the CohortPartitionScheme, or None if one is not found. Note that it is currently recommended that each course have only one cohorted user partition.

openedx.core.djangoapps.course_groups.permissions module#

Permissions for cohorts API

class openedx.core.djangoapps.course_groups.permissions.IsStaffOrAdmin#

Bases: BasePermission

Permission that checks if the user is staff or an admin.

has_permission(request, view)#

Returns true if the user is admin or staff and request method is GET.

openedx.core.djangoapps.course_groups.serializers module#

Cohorts API serializers.

class openedx.core.djangoapps.course_groups.serializers.CohortUsersAPISerializer(*args, **kwargs)#

Bases: ModelSerializer

Serializer for cohort users.

class Meta#

Bases: object

fields = ('username', 'email', 'name')#
model#

alias of User

get_full_name(model)#

Return the full name of the user.

openedx.core.djangoapps.course_groups.urls module#

Cohort API URLs

openedx.core.djangoapps.course_groups.views module#

Views related to course groups functionality.

class openedx.core.djangoapps.course_groups.views.APIPermissions(**kwargs)#

Bases: GenericAPIView

Helper class defining the authentication and permission class for the subclass views.

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)#
permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>, <class 'openedx.core.djangoapps.course_groups.permissions.IsStaffOrAdmin'>)#
serializer_class#

alias of Serializer

class openedx.core.djangoapps.course_groups.views.CohortHandler(**kwargs)#

Bases: DeveloperErrorViewMixin, APIPermissions

Use Cases

Get the current cohorts in a course. Create a new cohort in a course. Modify a cohort in a course.

Example Requests:

GET /api/cohorts/v1/courses/{course_id}/cohorts/ GET /api/cohorts/v1/courses/{course_id}/cohorts/?ordering=asc GET /api/cohorts/v1/courses/{course_id}/cohorts/?ordering=desc POST /api/cohorts/v1/courses/{course_id}/cohorts/ GET /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id} PATCH /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}

GET Query Parameters

  • ordering (optional): Sort direction for the cohort list by name. Accepted values are “asc” (ascending, default) and “desc” (descending). Returns HTTP 400 for invalid values.

POST Request Values

  • name (required): The string identifier for a cohort.

  • assignment_type (required): The string representing the assignment type (“manual” or “random”).

  • user_partition_id (optional): The integer identifier of the UserPartition (content group configuration).

  • group_id (optional): The integer identifier of the specific group in the partition. If group_id is specified, user_partition_id must also be specified.

PATCH Request Values

  • name (optional): The string identifier for a cohort.

  • assignment_type (optional): The string representing the assignment type (“manual” or “random”).

  • user_partition_id (optional): The integer identifier of the UserPartition (content group configuration).

  • group_id (optional): The integer identifier of the specific group in the partition. Set group_id to null to remove the content group association. If group_id is specified (non-null), user_partition_id must also be specified.

At least one of name, assignment_type, or group_id must be provided.

Response Values

  • cohorts: List of cohorts.

  • cohort: A cohort representation:

    • name: The string identifier for a cohort.

    • id: The integer identifier for a cohort.

    • user_count: The number of students in the cohort.

    • assignment_type: The string representing the assignment type.

    • user_partition_id: The integer identifier of the UserPartition.

    • group_id: The integer identifier of the specific group in the partition.

get(request, course_key_string, cohort_id=None)#

Endpoint to get either one or all cohorts.

patch(request, course_key_string, cohort_id=None)#

Endpoint to update a cohort name, assignment type, and/or content group association.

post(request, course_key_string, cohort_id=None)#

Endpoint to create a new cohort, must not include cohort_id.

queryset = []#
class openedx.core.djangoapps.course_groups.views.CohortSettings(**kwargs)#

Bases: DeveloperErrorViewMixin, APIPermissions

Use Cases

Get the cohort setting for a course. Set the cohort setting for a course.

Example Requests:

GET /api/cohorts/v1/settings/{course_id} PUT /api/cohorts/v1/settings/{course_id}

Response Values

  • is_cohorted: current status of the cohort setting

get(request, course_key_string)#

Endpoint to fetch the course cohort settings.

put(request, course_key_string)#

Endpoint to set the course cohort settings.

class openedx.core.djangoapps.course_groups.views.CohortUsers(**kwargs)#

Bases: DeveloperErrorViewMixin, APIPermissions

Use Cases

List users in a cohort Removes an user from a cohort. Add a user to a specific cohort.

Example Requests

GET /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users DELETE /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users/{username} POST /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users/{username} POST /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users

GET list of users in a cohort request parameters

  • course_id (required): The course id of the course the cohort belongs to.

  • cohort_id (required): The cohort id of the cohort to list the users in.

  • page_size: A query string parameter with the number of results to return per page. Optional. Default: 10. Maximum: 100.

  • page: A query string parameter with the page number to retrieve. Optional. Default: 1.

** POST add a user to a cohort request parameters**

  • course_id (required): The course id of the course the cohort belongs to.

  • cohort_id (required): The cohort id of the cohort to list the users in.

  • users (required): A body JSON parameter with a list of usernames/email addresses of users to be added to the cohort.

** DELETE remove a user from a cohort request parameters**

  • course_id (required): The course id of the course the cohort belongs to.

  • cohort_id (required): The cohort id of the cohort to list the users in.

  • username (required): The username of the user to be removed from the given cohort.

GET Response Values

Returns a HTTP 404 Not Found response status code when:

  • The course corresponding to the corresponding course id could not be found.

  • The requesting user does not have staff access to the course.

  • The cohort corresponding to the given cohort id could not be found.

Returns a HTTP 200 OK response status code to indicate success.

  • count: Number of users enrolled in the given cohort.

  • num_pages: Total number of pages of results.

  • current_page: Current page number.

  • start: The list index of the first item in the response.

  • previous: The URL of the previous page of results or null if it is the first page.

  • next: The URL of the next page of results or null if it is the last page.

  • results: A list of users in the cohort.

    • username: Username of the user.

    • email: Email address of the user.

    • name: Full name of the user.

POST Response Values

Returns a HTTP 404 Not Found response status code when:

  • The course corresponding to the corresponding course id could not be found.

  • The requesting user does not have staff access to the course.

  • The cohort corresponding to the given cohort id could not be found.

Returns a HTTP 200 OK response status code to indicate success.

  • success: Boolean indicating if the operation was successful.

  • added: Usernames/emails of the users that have been added to the cohort.

  • changed: Usernames/emails of the users that have been moved to the cohort.

  • present: Usernames/emails of the users already present in the cohort.

  • unknown: Usernames/emails of the users with an unknown cohort.

  • preassigned: Usernames/emails of unenrolled users that have been preassigned to the cohort.

  • invalid: Invalid emails submitted.

Adding multiple users to a cohort, send a request to: POST /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users

With a payload such as: {

“users”: [username1, username2, username3…]

}

DELETE Response Values

Returns a HTTP 404 Not Found response status code when:

  • The course corresponding to the corresponding course id could not be found.

  • The requesting user does not have staff access to the course.

  • The cohort corresponding to the given cohort id could not be found.

  • The user corresponding to the given username could not be found.

Returns a HTTP 204 No Content response status code to indicate success.

delete(request, course_key_string, cohort_id, username=None)#

Removes and user from a specific cohort.

Note: It’s better to use the post method to move users between cohorts.

get(request, course_key_string, cohort_id, username=None)#

Lists the users in a specific cohort.

post(request, course_key_string, cohort_id, username=None)#

Add given users to the cohort.

serializer_class#

alias of CohortUsersAPISerializer

openedx.core.djangoapps.course_groups.views.add_users_to_cohort(request, course_key_string, cohort_id)#

Return json dict of:

{‘success’: True,
‘added’: [{‘username’: …,

‘name’: …, ‘email’: …}, …],

‘changed’: [{‘username’: …,

‘name’: …, ‘email’: …, ‘previous_cohort’: …}, …],

‘present’: [str1, str2, …], # already there ‘unknown’: [str1, str2, …], ‘preassigned’: [str1, str2, …], ‘invalid’: [str1, str2, …]}

Raises Http404 if the cohort cannot be found for the given course.

openedx.core.djangoapps.course_groups.views.cohort_handler(request, course_key_string, cohort_id=None)#

The restful handler for cohort requests. Requires JSON. GET

If a cohort ID is specified, returns a JSON representation of the cohort

(name, id, user_count, assignment_type, user_partition_id, group_id).

If no cohort ID is specified, returns the JSON representation of all cohorts.

This is returned as a dict with the list of cohort information stored under the key cohorts.

PUT or POST or PATCH

If a cohort ID is specified, updates the cohort with the specified ID. Currently the only properties that can be updated are name, user_partition_id and group_id. Returns the JSON representation of the updated cohort. If no cohort ID is specified, creates a new cohort and returns the JSON representation of the updated cohort.

openedx.core.djangoapps.course_groups.views.course_cohort_settings_handler(request, course_key_string)#

The restful handler for cohort setting requests. Requires JSON. This will raise 404 if user is not staff. GET

Returns the JSON representation of cohort settings for the course.

PATCH

Updates the cohort settings for the course. Returns the JSON representation of updated settings.

openedx.core.djangoapps.course_groups.views.debug_cohort_mgmt(request, course_key_string)#

Debugging view for dev.

openedx.core.djangoapps.course_groups.views.json_http_response(data)#

Return an HttpResponse with the data json-serialized and the right content type header.

Create cohort to partition_id/group_id link.

openedx.core.djangoapps.course_groups.views.remove_user_from_cohort(request, course_key_string, cohort_id)#

Expects ‘username’: username in POST data.

Return json dict of:

{‘success’: True} or {‘success’: False,

‘msg’: error_msg}

openedx.core.djangoapps.course_groups.views.split_by_comma_and_whitespace(cstr)#

Split a string both by commas and whitespace. Returns a list.

Remove any existing cohort to partition_id/group_id link.

openedx.core.djangoapps.course_groups.views.users_in_cohort(request, course_key_string, cohort_id)#

Return users in the cohort. Show up to 100 per page, and page using the ‘page’ GET attribute in the call. Format:

Returns:

{‘success’: True,

’page’: page, ‘num_pages’: paginator.num_pages, ‘users’: [{‘username’: …, ‘email’: …, ‘name’: …}]

Return type:

Json dump of dictionary in the following format

}

Module contents#

Contents