def list_group_memberships_users(request_ctx,
group_id,
filter_states=None,
per_page=None,
**request_kwargs):
"""
List the members of a group.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param filter_states: (optional) Only list memberships with the given workflow_states. By default it will return all memberships.
:type filter_states: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List group memberships
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
filter_states_types = ('accepted', 'invited', 'requested')
utils.validate_attr_is_acceptable(filter_states, filter_states_types)
path = '/v1/groups/{group_id}/users'
payload = {
'filter_states': filter_states,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_all_quiz_submission_questions(request_ctx, quiz_submission_id, include,
**request_kwargs):
"""
Get a list of all the question records for this quiz submission.
<b>200 OK</b> response code is returned if the request was successful.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param quiz_submission_id: (required) ID
:type quiz_submission_id: string
:param include: (required) Associations to include with the quiz submission question.
:type include: string
:return: Get all quiz submission questions.
:rtype: requests.Response (with void data)
"""
include_types = ('quiz_question')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/quiz_submissions/{quiz_submission_id}/questions'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(
quiz_submission_id=quiz_submission_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_your_groups(request_ctx,
context_type=None,
per_page=None,
**request_kwargs):
"""
Returns a list of active groups for the current user.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param context_type: (optional) Only include groups that are in this type of context.
:type context_type: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List your groups
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
context_type_types = ('Account', 'Course')
utils.validate_attr_is_acceptable(context_type, context_type_types)
path = '/v1/users/self/groups'
payload = {
'context_type': context_type,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format()
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_course_sections(request_ctx,
course_id,
include=None,
per_page=None,
**request_kwargs):
"""
Returns the list of sections for this course.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param include: (optional) - "students": Associations to include with the group. Note: this is only available if you have permission to view users or grades in the course - "avatar_url": Include the avatar URLs for students returned.
:type include: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List course sections
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
include_types = ('students', 'avatar_url')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/sections'
payload = {
'include[]': include,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def create_external_feed_groups(request_ctx, group_id, url, verbosity, header_match=None, **request_kwargs):
"""
Create a new external feed for the course or group.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param url: (required) The url to the external rss or atom feed
:type url: string
:param verbosity: (required) no description
:type verbosity: string
:param header_match: (optional) If given, only feed entries that contain this string in their title will be imported
:type header_match: boolean or None
:return: Create an external feed
:rtype: requests.Response (with ExternalFeed data)
"""
verbosity_types = ('full', 'truncate', 'link_only')
utils.validate_attr_is_acceptable(verbosity, verbosity_types)
path = '/v1/groups/{group_id}/external_feeds'
payload = {
'url' : url,
'header_match' : header_match,
'verbosity' : verbosity,
}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_submissions_for_multiple_assignments_sections(request_ctx, section_id, student_ids, assignment_ids, grouped, include, **request_kwargs):
"""
Get all existing submissions for a given set of students and assignments.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param section_id: (required) ID
:type section_id: string
:param student_ids: (required) List of student ids to return submissions for. If this argument is omitted, return submissions for the calling user. Students may only list their own submissions. Observers may only list those of associated students. The special id "all" will return submissions for all students in the course/section as appropriate.
:type student_ids: string
:param assignment_ids: (required) List of assignments to return submissions for. If none are given, submissions for all assignments are returned.
:type assignment_ids: string
:param grouped: (required) If this argument is present, the response will be grouped by student, rather than a flat array of submissions.
:type grouped: boolean
:param include: (required) Associations to include with the group. `total_scores` requires the `grouped` argument.
:type include: string
:return: List submissions for multiple assignments
:rtype: requests.Response (with void data)
"""
include_types = ('submission_history', 'submission_comments', 'rubric_assessment', 'assignment', 'total_scores')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/sections/{section_id}/students/submissions'
payload = {
'student_ids' : student_ids,
'assignment_ids' : assignment_ids,
'grouped' : grouped,
'include' : include,
}
url = request_ctx.base_api_url + path.format(section_id=section_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_submission_sections(request_ctx, section_id, assignment_id, user_id, include, **request_kwargs):
"""
Get a single submission, based on user id.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param section_id: (required) ID
:type section_id: string
:param assignment_id: (required) ID
:type assignment_id: string
:param user_id: (required) ID
:type user_id: string
:param include: (required) Associations to include with the group.
:type include: string
:return: Get a single submission
:rtype: requests.Response (with void data)
"""
include_types = ('submission_history', 'submission_comments', 'rubric_assessment')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/sections/{section_id}/assignments/{assignment_id}/submissions/{user_id}'
payload = {
'include' : include,
}
url = request_ctx.base_api_url + path.format(section_id=section_id, assignment_id=assignment_id, user_id=user_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_assignment_submissions_courses(request_ctx, course_id, assignment_id, include, **request_kwargs):
"""
Get all existing submissions for an assignment.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param assignment_id: (required) ID
:type assignment_id: string
:param include: (required) Associations to include with the group.
:type include: string
:return: List assignment submissions
:rtype: requests.Response (with void data)
"""
include_types = ('submission_history', 'submission_comments', 'rubric_assessment', 'assignment')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignments/{assignment_id}/submissions'
payload = {
'include' : include,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, assignment_id=assignment_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_assignment_group(request_ctx, course_id, assignment_group_id, include, override_assignment_dates=None, **request_kwargs):
"""
Returns the assignment group with the given id.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param assignment_group_id: (required) ID
:type assignment_group_id: string
:param include: (required) Associations to include with the group. "discussion_topic" is only valid if "assignments" is also included.
:type include: string
:param override_assignment_dates: (optional) Apply assignment overrides for each assignment, defaults to true.
:type override_assignment_dates: boolean or None
:return: Get an Assignment Group
:rtype: requests.Response (with AssignmentGroup data)
"""
include_types = ('assignments', 'discussion_topic')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignment_groups/{assignment_group_id}'
payload = {
'include' : include,
'override_assignment_dates' : override_assignment_dates,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, assignment_group_id=assignment_group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_assignment_groups(request_ctx, course_id, include, override_assignment_dates=None, per_page=None, **request_kwargs):
"""
Returns the list of assignment groups for the current context. The returned
groups are sorted by their position field.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param include: (required) Associations to include with the group. both "discussion_topic" and "all_dates" is only valid are only valid if "assignments" is also included.
:type include: string
:param override_assignment_dates: (optional) Apply assignment overrides for each assignment, defaults to true.
:type override_assignment_dates: boolean or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List assignment groups
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
include_types = ('assignments', 'discussion_topic', 'all_dates')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignment_groups'
payload = {
'include' : include,
'override_assignment_dates' : override_assignment_dates,
'per_page' : per_page,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_group(request_ctx, group_id, include, **request_kwargs):
"""
Returns the data for a single group, or a 401 if the caller doesn't have
the rights to see it.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param include: (required) - "permissions": Include permissions the current user has for the group.
:type include: string
:return: Get a single group
:rtype: requests.Response (with Group data)
"""
include_types = ('permissions')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/groups/{group_id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_appointment_group(request_ctx, id, include=None, **request_kwargs):
"""
Returns information for a single appointment group
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param include: (optional) Array of additional information to include. Ssee include[] argument of "List appointment groups" action. "child_events":: reservations of time slots time slots "appointments":: will always be returned
:type include: string or None
:return: Get a single appointment group
:rtype: requests.Response (with void data)
"""
include_types = ('child_events', 'appointments')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/appointment_groups/{id}'
payload = {
'include' : include,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def reorder_quiz_items(request_ctx, course_id, id, order_id, order_type, **request_kwargs):
"""
Change order of the quiz questions or groups within the quiz
<b>204 No Content<b> response code is returned if the reorder was successful.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param order_id: (required) The associated item's unique identifier
:type order_id: integer
:param order_type: (required) The type of item is either 'question' or 'group'
:type order_type: string
:return: Reorder quiz items
:rtype: requests.Response (with void data)
"""
order_type_types = ("question", "group")
utils.validate_attr_is_acceptable(order_type, order_type_types)
path = "/v1/courses/{course_id}/quizzes/{id}/reorder"
payload = {"order[id]": order_id, "order[type]": order_type}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_student_group_participants(request_ctx, id, registration_status=None, **request_kwargs):
"""
List student groups that are (or may be) participating in this appointment
group. Refer to the Groups API for the response fields. Returns no results
for appointment groups with the "User" participant_type.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param registration_status: (optional) Limits results to the a given participation status, defaults to "all"
:type registration_status: string or None
:return: List student group participants
:rtype: requests.Response (with void data)
"""
registration_status_types = ('all', 'registered', 'registered')
utils.validate_attr_is_acceptable(registration_status, registration_status_types)
path = '/v1/appointment_groups/{id}/groups'
payload = {
'registration_status' : registration_status,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def update_appointment_group(request_ctx, id, appointment_group_context_codes, appointment_group_sub_context_codes=None, appointment_group_title=None, appointment_group_description=None, appointment_group_location_name=None, appointment_group_location_address=None, appointment_group_publish=None, appointment_group_participants_per_appointment=None, appointment_group_min_appointments_per_participant=None, appointment_group_max_appointments_per_participant=None, appointment_group_new_appointments_X=None, appointment_group_participant_visibility=None, **request_kwargs):
"""
Update and return an appointment group. If new_appointments are specified,
the response will return a new_appointments array (same format as
appointments array, see "List appointment groups" action).
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param appointment_group_context_codes: (required) Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.
:type appointment_group_context_codes: string
:param appointment_group_sub_context_codes: (optional) Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be "Group" instead of "User".
:type appointment_group_sub_context_codes: string or None
:param appointment_group_title: (optional) Short title for the appointment group.
:type appointment_group_title: string or None
:param appointment_group_description: (optional) Longer text description of the appointment group.
:type appointment_group_description: string or None
:param appointment_group_location_name: (optional) Location name of the appointment group.
:type appointment_group_location_name: string or None
:param appointment_group_location_address: (optional) Location address.
:type appointment_group_location_address: string or None
:param appointment_group_publish: (optional) Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.
:type appointment_group_publish: boolean or None
:param appointment_group_participants_per_appointment: (optional) Maximum number of participants that may register for each time slot. Defaults to null (no limit).
:type appointment_group_participants_per_appointment: integer or None
:param appointment_group_min_appointments_per_participant: (optional) Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots.
:type appointment_group_min_appointments_per_participant: integer or None
:param appointment_group_max_appointments_per_participant: (optional) Maximum number of time slots a user may register for.
:type appointment_group_max_appointments_per_participant: integer or None
:param appointment_group_new_appointments_X: (optional) Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.
:type appointment_group_new_appointments_X: string or None
:param appointment_group_participant_visibility: (optional) "private":: participants cannot see who has signed up for a particular time slot "protected":: participants can see who has signed up. Defaults to "private".
:type appointment_group_participant_visibility: string or None
:return: Update an appointment group
:rtype: requests.Response (with void data)
"""
appointment_group_participant_visibility_types = ('private', 'protected')
utils.validate_attr_is_acceptable(appointment_group_participant_visibility, appointment_group_participant_visibility_types)
path = '/v1/appointment_groups/{id}'
payload = {
'appointment_group[context_codes]' : appointment_group_context_codes,
'appointment_group[sub_context_codes]' : appointment_group_sub_context_codes,
'appointment_group[title]' : appointment_group_title,
'appointment_group[description]' : appointment_group_description,
'appointment_group[location_name]' : appointment_group_location_name,
'appointment_group[location_address]' : appointment_group_location_address,
'appointment_group[publish]' : appointment_group_publish,
'appointment_group[participants_per_appointment]' : appointment_group_participants_per_appointment,
'appointment_group[min_appointments_per_participant]' : appointment_group_min_appointments_per_participant,
'appointment_group[max_appointments_per_participant]' : appointment_group_max_appointments_per_participant,
'appointment_group[new_appointments][X]' : appointment_group_new_appointments_X,
'appointment_group[participant_visibility]' : appointment_group_participant_visibility,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.put(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_appointment_groups(request_ctx, scope=None, context_codes=None, include_past_appointments=None, include=None, **request_kwargs):
"""
Retrieve the list of appointment groups that can be reserved or managed by
the current user.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param scope: (optional) Defaults to "reservable"
:type scope: string or None
:param context_codes: (optional) Array of context codes used to limit returned results.
:type context_codes: string or None
:param include_past_appointments: (optional) Defaults to false. If true, includes past appointment groups
:type include_past_appointments: boolean or None
:param include: (optional) Array of additional information to include. "appointments":: calendar event time slots for this appointment group "child_events":: reservations of those time slots "participant_count":: number of reservations "reserved_times":: the event id, start time and end time of reservations the current user has made)
:type include: string or None
:return: List appointment groups
:rtype: requests.Response (with void data)
"""
scope_types = ('reservable', 'manageable')
include_types = ('appointments', 'child_events', 'participant_count', 'reserved_times')
utils.validate_attr_is_acceptable(scope, scope_types)
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/appointment_groups'
payload = {
'scope' : scope,
'context_codes' : context_codes,
'include_past_appointments' : include_past_appointments,
'include' : include,
}
url = request_ctx.base_api_url + path.format()
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def conclude_enrollment(request_ctx, course_id, id, task=None, **request_kwargs):
"""
Delete or conclude an enrollment.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param task: (optional) The action to take on the enrollment.
:type task: string or None
:return: Conclude an enrollment
:rtype: requests.Response (with Enrollment data)
"""
task_types = ("conclude", "delete")
utils.validate_attr_is_acceptable(task, task_types)
path = "/v1/courses/{course_id}/enrollments/{id}"
payload = {"task": task}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.delete(request_ctx, url, payload=payload, **request_kwargs)
return response
def export_course_content(request_ctx, course_id, export_type, **request_kwargs):
"""
Begin a content export job for a course.
You can use the `ProgressController#show <https://github.com/instructure/canvas-lms/blob/master/app/controllers/progress_controller.rb>`_ to track the
progress of the export. The migration's progress is linked to with the
_progress_url_ value.
When the export completes, use the `ContentExportsApiController#show <https://github.com/instructure/canvas-lms/blob/master/app/controllers/content_exports_api_controller.rb>`_ endpoint
to retrieve a download URL for the exported content.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param export_type: (required) "common_cartridge":: Export the contents of the course in the Common Cartridge (.imscc) format "qti":: Export quizzes in the QTI format
:type export_type: string
:return: Export course content
:rtype: requests.Response (with ContentExport data)
"""
export_type_types = ('common_cartridge', 'qti')
utils.validate_attr_is_acceptable(export_type, export_type_types)
path = '/v1/courses/{course_id}/content_exports'
payload = {
'export_type' : export_type,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_quiz_submission(request_ctx, course_id, quiz_id, id, include,
**request_kwargs):
"""
Get a single quiz submission.
<b>200 OK</b> response code is returned if the request was successful.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param quiz_id: (required) ID
:type quiz_id: string
:param id: (required) ID
:type id: string
:param include: (required) Associations to include with the quiz submission.
:type include: string
:return: Get a single quiz submission.
:rtype: requests.Response (with void data)
"""
include_types = ('submission', 'quiz', 'user')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/quizzes/{quiz_id}/submissions/{id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(
course_id=course_id, quiz_id=quiz_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def reorder_question_groups(request_ctx, course_id, quiz_id, id, order_id, order_type, **request_kwargs):
"""
Change the order of the quiz questions within the group
<b>204 No Content<b> response code is returned if the reorder was successful.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param quiz_id: (required) ID
:type quiz_id: string
:param id: (required) ID
:type id: string
:param order_id: (required) The associated item's unique identifier
:type order_id: integer
:param order_type: (required) The type of item is always 'question' for a group
:type order_type: string
:return: Reorder question groups
:rtype: requests.Response (with void data)
"""
order_type_types = ('question')
utils.validate_attr_is_acceptable(order_type, order_type_types)
path = '/v1/courses/{course_id}/quizzes/{quiz_id}/groups/{id}/reorder'
payload = {
'order[id]' : order_id,
'order[type]' : order_type,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, quiz_id=quiz_id, id=id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_group_memberships_users(request_ctx, group_id, filter_states=None, per_page=None, **request_kwargs):
"""
List the members of a group.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param filter_states: (optional) Only list memberships with the given workflow_states. By default it will return all memberships.
:type filter_states: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List group memberships
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
filter_states_types = ("accepted", "invited", "requested")
utils.validate_attr_is_acceptable(filter_states, filter_states_types)
path = "/v1/groups/{group_id}/users"
payload = {"filter_states": filter_states, "per_page": per_page}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def update_membership_users(request_ctx, group_id, user_id, moderator, workflow_state=None, **request_kwargs):
"""
Accept a membership request, or add/remove moderator rights.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param user_id: (required) ID
:type user_id: string
:param moderator: (required) no description
:type moderator: string
:param workflow_state: (optional) Currently, the only allowed value is "accepted"
:type workflow_state: string or None
:return: Update a membership
:rtype: requests.Response (with GroupMembership data)
"""
workflow_state_types = "accepted"
utils.validate_attr_is_acceptable(workflow_state, workflow_state_types)
path = "/v1/groups/{group_id}/users/{user_id}"
payload = {"workflow_state": workflow_state, "moderator": moderator}
url = request_ctx.base_api_url + path.format(group_id=group_id, user_id=user_id)
response = client.put(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_group_s_users(request_ctx, group_id, include, search_term=None, per_page=None, **request_kwargs):
"""
Returns a list of users in the group.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param include: (required) - "avatar_url": Include users' avatar_urls.
:type include: string
:param search_term: (optional) The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.
:type search_term: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List group's users
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
include_types = "avatar_url"
utils.validate_attr_is_acceptable(include, include_types)
path = "/v1/groups/{group_id}/users"
payload = {"search_term": search_term, "include": include, "per_page": per_page}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_your_groups(request_ctx, context_type=None, per_page=None, **request_kwargs):
"""
Returns a list of active groups for the current user.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param context_type: (optional) Only include groups that are in this type of context.
:type context_type: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List your groups
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
context_type_types = ("Account", "Course")
utils.validate_attr_is_acceptable(context_type, context_type_types)
path = "/v1/users/self/groups"
payload = {"context_type": context_type, "per_page": per_page}
url = request_ctx.base_api_url + path.format()
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_student_group_participants(request_ctx,
id,
registration_status=None,
**request_kwargs):
"""
List student groups that are (or may be) participating in this appointment
group. Refer to the Groups API for the response fields. Returns no results
for appointment groups with the "User" participant_type.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param registration_status: (optional) Limits results to the a given participation status, defaults to "all"
:type registration_status: string or None
:return: List student group participants
:rtype: requests.Response (with void data)
"""
registration_status_types = ('all', 'registered', 'registered')
utils.validate_attr_is_acceptable(registration_status,
registration_status_types)
path = '/v1/appointment_groups/{id}/groups'
payload = {
'registration_status': registration_status,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_appointment_group(request_ctx,
id,
include=None,
**request_kwargs):
"""
Returns information for a single appointment group
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param include: (optional) Array of additional information to include. Ssee include[] argument of "List appointment groups" action. "child_events":: reservations of time slots time slots "appointments":: will always be returned
:type include: string or None
:return: Get a single appointment group
:rtype: requests.Response (with void data)
"""
include_types = ('child_events', 'appointments')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/appointment_groups/{id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_assignment(request_ctx,
course_id,
id,
include,
override_assignment_dates=None,
**request_kwargs):
"""
Returns the assignment with the given id.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param include: (required) Associations to include with the assignment.
:type include: string
:param override_assignment_dates: (optional) Apply assignment overrides to the assignment, defaults to true.
:type override_assignment_dates: boolean or None
:return: Get a single assignment
:rtype: requests.Response (with Assignment data)
"""
include_types = ('submission')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignments/{id}'
payload = {
'include': include,
'override_assignment_dates': override_assignment_dates,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_submission_sections(request_ctx, section_id, assignment_id,
user_id, include, **request_kwargs):
"""
Get a single submission, based on user id.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param section_id: (required) ID
:type section_id: string
:param assignment_id: (required) ID
:type assignment_id: string
:param user_id: (required) ID
:type user_id: string
:param include: (required) Associations to include with the group.
:type include: string
:return: Get a single submission
:rtype: requests.Response (with void data)
"""
include_types = ('submission_history', 'submission_comments',
'rubric_assessment')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/sections/{section_id}/assignments/{assignment_id}/submissions/{user_id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(
section_id=section_id, assignment_id=assignment_id, user_id=user_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def create_communication_channel(request_ctx, user_id, communication_channel_address, communication_channel_type, skip_confirmation=None, **request_kwargs):
"""
Creates a new communication channel for the specified user.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param user_id: (required) ID
:type user_id: string
:param communication_channel_address: (required) An email address or SMS number.
:type communication_channel_address: string
:param communication_channel_type: (required) The type of communication channel. In order to enable push notification support, the server must be properly configured (via sns.yml) to communicate with Amazon Simple Notification Services, and the developer key used to create the access token from this request must have an SNS ARN configured on it.
:type communication_channel_type: string
:param skip_confirmation: (optional) Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.
:type skip_confirmation: boolean or None
:return: Create a communication channel
:rtype: requests.Response (with CommunicationChannel data)
"""
communication_channel_type_types = ('email', 'sms', 'push')
utils.validate_attr_is_acceptable(communication_channel_type, communication_channel_type_types)
path = '/v1/users/{user_id}/communication_channels'
payload = {
'communication_channel[address]' : communication_channel_address,
'communication_channel[type]' : communication_channel_type,
'skip_confirmation' : skip_confirmation,
}
url = request_ctx.base_api_url + path.format(user_id=user_id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_assignment_submissions_courses(request_ctx, course_id, assignment_id,
include, **request_kwargs):
"""
Get all existing submissions for an assignment.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param assignment_id: (required) ID
:type assignment_id: string
:param include: (required) Associations to include with the group.
:type include: string
:return: List assignment submissions
:rtype: requests.Response (with void data)
"""
include_types = ('submission_history', 'submission_comments',
'rubric_assessment', 'assignment')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignments/{assignment_id}/submissions'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(course_id=course_id,
assignment_id=assignment_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_quiz_report(request_ctx, course_id, quiz_id, id, include=None, **request_kwargs):
"""
Returns the data for a single quiz report.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param quiz_id: (required) ID
:type quiz_id: string
:param id: (required) ID
:type id: string
:param include: (optional) Whether the output should include documents for the file and/or progress objects associated with this report. (Note: JSON-API only)
:type include: string[] or None
:return: Get a quiz report
:rtype: requests.Response (with QuizReport data)
"""
include_types = ('file', 'progress')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/quizzes/{quiz_id}/reports/{id}'
payload = {
'include' : include,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, quiz_id=quiz_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_course_sections(request_ctx, course_id, include=None, per_page=None, **request_kwargs):
"""
Returns the list of sections for this course.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param include: (optional) - "students": Associations to include with the group. Note: this is only available if you have permission to view users or grades in the course - "avatar_url": Include the avatar URLs for students returned.
:type include: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List course sections
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
include_types = ('students', 'avatar_url')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/sections'
payload = {
'include[]' : include,
'per_page' : per_page,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_quiz_submission_question(request_ctx, quiz_submission_id, id, include, **request_kwargs):
"""
Get a single question record.
<b>200 OK</b> response code is returned if the request was successful.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param quiz_submission_id: (required) ID
:type quiz_submission_id: string
:param id: (required) ID
:type id: string
:param include: (required) Associations to include with the quiz submission question.
:type include: string
:return: Get a single quiz submission question.
:rtype: requests.Response (with void data)
"""
include_types = ('quiz_question')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/quiz_submissions/{quiz_submission_id}/questions/{id}'
payload = {
'include' : include,
}
url = request_ctx.base_api_url + path.format(quiz_submission_id=quiz_submission_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def set_feature_flag_users(request_ctx, user_id, feature, state=None, locking_account_id=None, **request_kwargs):
"""
Set a feature flag for a given Account, Course, or User. This call will fail if a parent account sets
a feature flag for the same feature in any state other than "allowed".
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param user_id: (required) ID
:type user_id: string
:param feature: (required) ID
:type feature: string
:param state: (optional) "off":: The feature is not available for the course, user, or account and sub-accounts. "allowed":: (valid only on accounts) The feature is off in the account, but may be enabled in sub-accounts and courses by setting a feature flag on the sub-account or course. "on":: The feature is turned on unconditionally for the user, course, or account and sub-accounts.
:type state: string or None
:param locking_account_id: (optional) If set, this FeatureFlag may only be modified by someone with administrative rights in the specified account. The locking account must be above the target object in the account chain.
:type locking_account_id: integer or None
:return: Set feature flag
:rtype: requests.Response (with FeatureFlag data)
"""
state_types = ('off', 'allowed', 'on')
utils.validate_attr_is_acceptable(state, state_types)
path = '/v1/users/{user_id}/features/flags/{feature}'
payload = {
'state' : state,
'locking_account_id' : locking_account_id,
}
url = request_ctx.base_api_url + path.format(user_id=user_id, feature=feature)
response = client.put(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_available_tabs_for_course_or_group_groups(request_ctx, group_id,
include, **request_kwargs):
"""
Returns a list of navigation tabs available in the current context.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param include: (required) Optionally include external tool tabs in the returned list of tabs (Only has effect for courses, not groups)
:type include: string
:return: List available tabs for a course or group
:rtype: requests.Response (with void data)
"""
include_types = ('external')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/groups/{group_id}/tabs'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(group_id=group_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_file(request_ctx, id, include=None, **request_kwargs):
"""
Returns the standard attachment json object
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param include: (optional) Array of additional information to include. "user":: the user who uploaded the file or last edited its content
:type include: string or None
:return: Get file
:rtype: requests.Response (with File data)
"""
include_types = ('user')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/files/{id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_quiz_report(request_ctx,
course_id,
quiz_id,
id,
include=None,
**request_kwargs):
"""
Returns the data for a single quiz report.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param quiz_id: (required) ID
:type quiz_id: string
:param id: (required) ID
:type id: string
:param include: (optional) Whether the output should include documents for the file and/or progress objects associated with this report. (Note: JSON-API only)
:type include: string[] or None
:return: Get a quiz report
:rtype: requests.Response (with QuizReport data)
"""
include_types = ('file', 'progress')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/quizzes/{quiz_id}/reports/{id}'
payload = {
'include': include,
}
url = request_ctx.base_api_url + path.format(
course_id=course_id, quiz_id=quiz_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_assignment(request_ctx, course_id, id, include, override_assignment_dates=None, **request_kwargs):
"""
Returns the assignment with the given id.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param include: (required) Associations to include with the assignment.
:type include: string
:param override_assignment_dates: (optional) Apply assignment overrides to the assignment, defaults to true.
:type override_assignment_dates: boolean or None
:return: Get a single assignment
:rtype: requests.Response (with Assignment data)
"""
include_types = ('submission')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/assignments/{id}'
payload = {
'include' : include,
'override_assignment_dates' : override_assignment_dates,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_module_item_sequence(request_ctx, course_id, asset_type, asset_id,
**request_kwargs):
"""
Given an asset in a course, find the ModuleItem it belongs to, and also the previous and next Module Items
in the course sequence.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param asset_type: (required) The type of asset to find module sequence information for. Use the ModuleItem if it is known (e.g., the user navigated from a module item), since this will avoid ambiguity if the asset appears more than once in the module sequence.
:type asset_type: string
:param asset_id: (required) The id of the asset (or the url in the case of a Page)
:type asset_id: integer
:return: Get module item sequence
:rtype: requests.Response (with ModuleItemSequence data)
"""
asset_type_types = ('ModuleItem', 'File', 'Page', 'Discussion',
'Assignment', 'Quiz', 'ExternalTool')
utils.validate_attr_is_acceptable(asset_type, asset_type_types)
path = '/v1/courses/{course_id}/module_item_sequence'
payload = {
'asset_type': asset_type,
'asset_id': asset_id,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def conclude_course(request_ctx, id, event, **request_kwargs):
"""
Delete or conclude an existing course
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param event: (required) The action to take on the course.
:type event: string
:return: Conclude a course
:rtype: requests.Response (with void data)
"""
event_types = ('delete', 'conclude')
utils.validate_attr_is_acceptable(event, event_types)
path = '/v1/courses/{id}'
payload = {
'event': event,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.delete(request_ctx,
url,
payload=payload,
**request_kwargs)
return response
def show_module(request_ctx,
course_id,
id,
include,
student_id=None,
**request_kwargs):
"""
Get information about a single module
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param include: (required) - "items": Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the {api:ContextModuleItemsApiController#index List Module Items API} if items are not returned. - "content_details": Requires include['items']. Returns additional details with module items specific to their associated content items. Includes standard lock information for each item.
:type include: string
:param student_id: (optional) Returns module completion information for the student with this id.
:type student_id: string or None
:return: Show module
:rtype: requests.Response (with Module data)
"""
include_types = ('items', 'content_details')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/modules/{id}'
payload = {
'include': include,
'student_id': student_id,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_course_accounts(request_ctx, account_id, id, include,
**request_kwargs):
"""
Return information on a single course.
Accepts the same include[] parameters as the list action plus:
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) ID
:type account_id: string
:param id: (required) ID
:type id: string
:param include: (required) - "all_courses": Also search recently deleted courses. - "permissions": Include permissions the current user has for the course.
:type include: string
:return: Get a single course
:rtype: requests.Response (with Course data)
"""
include_types = ('all_courses', 'permissions')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/accounts/{account_id}/courses/{id}'
payload = {
'include[]': include,
}
url = request_ctx.base_api_url + path.format(account_id=account_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def create_new_role(request_ctx, account_id, role, base_role_type=None, permissions={}, **request_kwargs):
"""
Create a new course-level or account-level role.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) ID
:type account_id: string
:param role: (required) Label and unique identifier for the role.
:type role: string
:param base_role_type: (optional) Specifies the role type that will be used as a base for the permissions granted to this role. Defaults to 'AccountMembership' if absent
:type base_role_type: string or None
:param permissions: (optional) Specifies the permissions that will be granted to this role. See Canvas API docs for details on the structure.
:type permissions: dict
:return: Create a new role
:rtype: requests.Response (with Role data)
"""
base_role_type_types = ('AccountMembership', 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', 'DesignerEnrollment')
utils.validate_attr_is_acceptable(base_role_type, base_role_type_types)
path = '/v1/accounts/{account_id}/roles'
payload = {
'role' : role,
'base_role_type' : base_role_type,
}
# flatten the permissions dict
for p in permissions:
for a in permissions[p]:
payload['permissions[{}][{}]'.format(p, a)] = permissions[p][a]
url = request_ctx.base_api_url + path.format(account_id=account_id)
response = client.post(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_enrollments_sections(request_ctx,
section_id,
type=None,
role=None,
role_id=None,
state=None,
user_id=None,
per_page=None,
**request_kwargs):
"""
Depending on the URL given, return either (1) all of the enrollments in
a course, (2) all of the enrollments in a section or (3) all of a user's
enrollments. This includes student, teacher, TA, and observer enrollments.
If a user has multiple enrollments in a context (e.g. as a teacher
and a student or in multiple course sections), each enrollment will be
listed separately.
note: Currently, only an admin user can return other users' enrollments. A
user can, however, return his/her own enrollments.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param section_id: (required) ID
:type section_id: string
:param type: (optional) A list of enrollment types to return. Accepted values are 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'DesignerEnrollment', and 'ObserverEnrollment.' If omitted, all enrollment types are returned. This argument is ignored if `role` is given.
:type type: string or None
:param role: (optional) A list of enrollment roles to return. Accepted values include course-level roles created by the {api:RoleOverridesController#add_role Add Role API} as well as the base enrollment types accepted by the `type` argument above.
:type role: string or None
:param role_id: (optional) A list of enrollment role IDs to return. Accepted values include course-level the numeric IDs of the roles created by the {api:RoleOverridesController#add_role Add Role API} as well as the base enrollment types accepted by the `type` argument above.
:type role_id: integer or None
:param state: (optional) Filter by enrollment state. If omitted, 'active' and 'invited' enrollments are returned. When querying a user's enrollments (either via user_id argument or via user enrollments endpoint), the following additional synthetic states are supported: "current_and_invited"|"current_and_future"|"current_and_concluded"
:type state: string or None
:param user_id: (optional) Filter by user_id (only valid for course or section enrollment queries). If set to the current user's id, this is a way to determine if the user has any enrollments in the course or section, independent of whether the user has permission to view other people on the roster.
:type user_id: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List enrollments
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
state_types = ('active', 'invited', 'creation_pending', 'deleted',
'rejected', 'completed', 'inactive')
utils.validate_attr_is_acceptable(state, state_types)
path = '/v1/sections/{section_id}/enrollments'
payload = {
'type[]': type,
'role[]': role,
'role_id[]': role_id,
'state[]': state,
'user_id': user_id,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format(section_id=section_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_module_item_sequence(request_ctx, course_id, asset_type, asset_id, **request_kwargs):
"""
Given an asset in a course, find the ModuleItem it belongs to, and also the previous and next Module Items
in the course sequence.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param asset_type: (required) The type of asset to find module sequence information for. Use the ModuleItem if it is known (e.g., the user navigated from a module item), since this will avoid ambiguity if the asset appears more than once in the module sequence.
:type asset_type: string
:param asset_id: (required) The id of the asset (or the url in the case of a Page)
:type asset_id: integer
:return: Get module item sequence
:rtype: requests.Response (with ModuleItemSequence data)
"""
asset_type_types = ('ModuleItem', 'File', 'Page', 'Discussion', 'Assignment', 'Quiz', 'ExternalTool')
utils.validate_attr_is_acceptable(asset_type, asset_type_types)
path = '/v1/courses/{course_id}/module_item_sequence'
payload = {
'asset_type' : asset_type,
'asset_id' : asset_id,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_roles(request_ctx, account_id, state, per_page=None, **request_kwargs):
"""
List the roles available to an account.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) The id of the account to retrieve roles for.
:type account_id: string
:param state: (required) Filter by role state. If this argument is omitted, only 'active' roles are returned.
:type state: string
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List roles
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
state_types = ('active', 'inactive')
utils.validate_attr_is_acceptable(state, state_types)
path = '/v1/accounts/{account_id}/roles'
payload = {
'state[]' : state,
'per_page' : per_page,
}
url = request_ctx.base_api_url + path.format(account_id=account_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def show_module_item(request_ctx, course_id, module_id, id, include, student_id=None, **request_kwargs):
"""
Get information about a single module item
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param module_id: (required) ID
:type module_id: string
:param id: (required) ID
:type id: string
:param include: (required) If included, will return additional details specific to the content associated with this item. Refer to the {api:Modules:Module%20Item Module Item specification} for more details. Includes standard lock information for each item.
:type include: string
:param student_id: (optional) Returns module completion information for the student with this id.
:type student_id: string or None
:return: Show module item
:rtype: requests.Response (with ModuleItem data)
"""
include_types = ('content_details')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/modules/{module_id}/items/{id}'
payload = {
'include' : include,
'student_id' : student_id,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, module_id=module_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def show_module(request_ctx, course_id, id, include, student_id=None, **request_kwargs):
"""
Get information about a single module
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param include: (required) - "items": Return module items inline if possible. This parameter suggests that Canvas return module items directly in the Module object JSON, to avoid having to make separate API requests for each module when enumerating modules and items. Canvas is free to omit 'items' for any particular module if it deems them too numerous to return inline. Callers must be prepared to use the {api:ContextModuleItemsApiController#index List Module Items API} if items are not returned. - "content_details": Requires include['items']. Returns additional details with module items specific to their associated content items. Includes standard lock information for each item.
:type include: string
:param student_id: (optional) Returns module completion information for the student with this id.
:type student_id: string or None
:return: Show module
:rtype: requests.Response (with Module data)
"""
include_types = ('items', 'content_details')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/modules/{id}'
payload = {
'include' : include,
'student_id' : student_id,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def get_single_course_accounts(request_ctx, account_id, id, include, **request_kwargs):
"""
Return information on a single course.
Accepts the same include[] parameters as the list action plus:
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) ID
:type account_id: string
:param id: (required) ID
:type id: string
:param include: (required) - "all_courses": Also search recently deleted courses. - "permissions": Include permissions the current user has for the course.
:type include: string
:return: Get a single course
:rtype: requests.Response (with Course data)
"""
include_types = ('all_courses', 'permissions')
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/accounts/{account_id}/courses/{id}'
payload = {
'include[]' : include,
}
url = request_ctx.base_api_url + path.format(account_id=account_id, id=id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def conclude_course(request_ctx, id, event, **request_kwargs):
"""
Delete or conclude an existing course
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param id: (required) ID
:type id: string
:param event: (required) The action to take on the course.
:type event: string
:return: Conclude a course
:rtype: requests.Response (with void data)
"""
event_types = ('delete', 'conclude')
utils.validate_attr_is_acceptable(event, event_types)
path = '/v1/courses/{id}'
payload = {
'event' : event,
}
url = request_ctx.base_api_url + path.format(id=id)
response = client.delete(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_roles(request_ctx,
account_id,
state,
per_page=None,
**request_kwargs):
"""
List the roles available to an account.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) The id of the account to retrieve roles for.
:type account_id: string
:param state: (required) Filter by role state. If this argument is omitted, only 'active' roles are returned.
:type state: string
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List roles
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
state_types = ('active', 'inactive')
utils.validate_attr_is_acceptable(state, state_types)
path = '/v1/accounts/{account_id}/roles'
payload = {
'state[]': state,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format(account_id=account_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def conclude_enrollment(request_ctx,
course_id,
id,
task=None,
**request_kwargs):
"""
Delete or conclude an enrollment.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param id: (required) ID
:type id: string
:param task: (optional) The action to take on the enrollment.
:type task: string or None
:return: Conclude an enrollment
:rtype: requests.Response (with Enrollment data)
"""
task_types = ('conclude', 'delete', 'inactivate', 'deactivate')
utils.validate_attr_is_acceptable(task, task_types)
path = '/v1/courses/{course_id}/enrollments/{id}'
payload = {
'task': task,
}
url = request_ctx.base_api_url + path.format(course_id=course_id, id=id)
response = client.delete(request_ctx,
url,
payload=payload,
**request_kwargs)
return response
def list_active_courses_in_account(request_ctx, account_id, with_enrollments=None, published=None, completed=None, by_teachers=None, by_subaccounts=None, hide_enrollmentless_courses=None, state=None, enrollment_term_id=None, search_term=None, include=None, per_page=None, **request_kwargs):
"""
Retrieve the list of courses in this account.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param account_id: (required) ID
:type account_id: string
:param with_enrollments: (optional) If true, include only courses with at least one enrollment. If false, include only courses with no enrollments. If not present, do not filter on course enrollment status.
:type with_enrollments: boolean or None
:param published: (optional) If true, include only published courses. If false, exclude published courses. If not present, do not filter on published status.
:type published: boolean or None
:param completed: (optional) If true, include only completed courses (these may be in state 'completed', or their enrollment term may have ended). If false, exclude completed courses. If not present, do not filter on completed status.
:type completed: boolean or None
:param by_teachers: (optional) List of User IDs of teachers; if supplied, include only courses taught by one of the referenced users.
:type by_teachers: array or None
:param by_subaccounts: (optional) List of Account IDs; if supplied, include only courses associated with one of the referenced subaccounts.
:type by_subaccounts: array or None
:param hide_enrollmentless_courses: (optional) If present, only return courses that have at least one enrollment. Equivalent to 'with_enrollments=true'; retained for compatibility.
:type hide_enrollmentless_courses: boolean or None
:param state: (optional) If set, only return courses that are in the given state(s). By default, all states but "deleted" are returned.
:type state: array or None
:param enrollment_term_id: (optional) If set, only includes courses from the specified term.
:type enrollment_term_id: integer or None
:param search_term: (optional) The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters.
:type search_term: string or None
:param include: (optional) - All explanations can be seen in the {api:CoursesController#index Course API index documentation}
:type include: array or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List active courses in an account
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
state_types = ('created', 'claimed', 'available', 'completed', 'deleted', 'all')
include_types = ('needs_grading_count', 'syllabus_body', 'total_scores', 'term', 'course_progress', 'sections', 'storage_quota_used_mb')
utils.validate_attr_is_acceptable(state, state_types)
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/accounts/{account_id}/courses'
payload = {
'with_enrollments' : with_enrollments,
'published' : published,
'completed' : completed,
'by_teachers' : by_teachers,
'by_subaccounts' : by_subaccounts,
'hide_enrollmentless_courses' : hide_enrollmentless_courses,
'state' : state,
'enrollment_term_id' : enrollment_term_id,
'search_term' : search_term,
'include' : include,
'per_page' : per_page,
}
url = request_ctx.base_api_url + path.format(account_id=account_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def update_create_page_groups(request_ctx,
group_id,
url,
wiki_page_title,
wiki_page_body,
wiki_page_hide_from_students,
wiki_page_notify_of_update,
wiki_page_editing_roles=None,
wiki_page_published=None,
wiki_page_front_page=None,
**request_kwargs):
"""
Update the title or contents of a wiki page
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_id: (required) ID
:type group_id: string
:param url: (required) ID
:type url: string
:param wiki_page_title: (required) The title for the new page. NOTE: changing a page's title will change its url. The updated url will be returned in the result.
:type wiki_page_title: string
:param wiki_page_body: (required) The content for the new page.
:type wiki_page_body: string
:param wiki_page_hide_from_students: (required) Whether the page should be hidden from students. *Note:* when draft state is enabled, attempts to set +hide_from_students+ will be ignored and the value returned will always be the inverse of the +published+ value.
:type wiki_page_hide_from_students: boolean
:param wiki_page_notify_of_update: (required) Whether participants should be notified when this page changes.
:type wiki_page_notify_of_update: boolean
:param wiki_page_editing_roles: (optional) Which user roles are allowed to edit this page. Any combination of these roles is allowed (separated by commas). "teachers":: Allows editing by teachers in the course. "students":: Allows editing by students in the course. "members":: For group wikis, allows editing by members of the group. "public":: Allows editing by any user.
:type wiki_page_editing_roles: string or None
:param wiki_page_published: (optional) Whether the page is published (true) or draft state (false). *Note:* when draft state is disabled, attempts to set +published+ will be ignored and the value returned will always be the inverse of the +hide_from_students+ value.
:type wiki_page_published: boolean or None
:param wiki_page_front_page: (optional) Set an unhidden page as the front page (if true)
:type wiki_page_front_page: boolean or None
:return: Update/create page
:rtype: requests.Response (with Page data)
"""
wiki_page_editing_roles_types = ('teachers', 'students', 'members',
'public')
utils.validate_attr_is_acceptable(wiki_page_editing_roles,
wiki_page_editing_roles_types)
path = '/v1/groups/{group_id}/pages/{url}'
payload = {
'wiki_page[title]': wiki_page_title,
'wiki_page[body]': wiki_page_body,
'wiki_page[hide_from_students]': wiki_page_hide_from_students,
'wiki_page[editing_roles]': wiki_page_editing_roles,
'wiki_page[notify_of_update]': wiki_page_notify_of_update,
'wiki_page[published]': wiki_page_published,
'wiki_page[front_page]': wiki_page_front_page,
}
url = request_ctx.base_api_url + path.format(group_id=group_id, url=url)
response = client.put(request_ctx, url, payload=payload, **request_kwargs)
return response
def test_validate_attr_is_acceptable_raises_attributeerror_on_allow_none_true(self):
"""
Assert that validate_attr_is_acceptable does not raise an AttributeError if the value is None
and allow_none is True
"""
try:
utils.validate_attr_is_acceptable(None, ['b', 'c'], True)
except AttributeError:
print 'assert None can be passed when allow_none=True failed'
raise
def list_users_in_course_search_users(request_ctx,
course_id,
include,
search_term=None,
enrollment_type=None,
enrollment_role=None,
user_id=None,
per_page=None,
**request_kwargs):
"""
Returns the list of users in this course. And optionally the user's enrollments in the course.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param course_id: (required) ID
:type course_id: string
:param include: (required) - "email": Optional user email. - "enrollments": Optionally include with each Course the user's current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a 'grades' key with 'current_score', 'final_score', 'current_grade' and 'final_grade' values. - "locked": Optionally include whether an enrollment is locked. - "avatar_url": Optionally include avatar_url. - "test_student": Optionally include the course's Test Student, if present. Default is to not include Test Student.
:type include: string
:param search_term: (optional) The partial name or full ID of the users to match and return in the results list.
:type search_term: string or None
:param enrollment_type: (optional) When set, only return users where the user is enrolled as this type. This argument is ignored if enrollment_role is given.
:type enrollment_type: string or None
:param enrollment_role: (optional) When set, only return users enrolled with the specified course-level role. This can be a role created with the {api:RoleOverridesController#add_role Add Role API} or a base role type of 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'ObserverEnrollment', or 'DesignerEnrollment'.
:type enrollment_role: string or None
:param user_id: (optional) If included, the user will be queried and if the user is part of the users set, the page parameter will be modified so that the page containing user_id will be returned.
:type user_id: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List users in course
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
enrollment_type_types = ('teacher', 'student', 'ta', 'observer',
'designer')
include_types = ('email', 'enrollments', 'locked', 'avatar_url',
'test_student')
utils.validate_attr_is_acceptable(enrollment_type, enrollment_type_types)
utils.validate_attr_is_acceptable(include, include_types)
path = '/v1/courses/{course_id}/search_users'
payload = {
'search_term': search_term,
'enrollment_type': enrollment_type,
'enrollment_role': enrollment_role,
'include[]': include,
'user_id': user_id,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format(course_id=course_id)
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def list_calendar_events(request_ctx,
type=None,
start_date=None,
end_date=None,
undated=None,
all_events=None,
context_codes=None,
per_page=None,
**request_kwargs):
"""
Retrieve the list of calendar events or assignments for the current user
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param type: (optional) Defaults to "event"
:type type: string or None
:param start_date: (optional) Only return events since the start_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
:type start_date: date or None
:param end_date: (optional) Only return events before the end_date (inclusive). Defaults to start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end_date is the same as start_date, then only events on that day are returned.
:type end_date: date or None
:param undated: (optional) Defaults to false (dated events only). If true, only return undated events and ignore start_date and end_date.
:type undated: boolean or None
:param all_events: (optional) Defaults to false (uses start_date, end_date, and undated criteria). If true, all events are returned, ignoring start_date, end_date, and undated criteria.
:type all_events: boolean or None
:param context_codes: (optional) List of context codes of courses/groups/users whose events you want to see. If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42
:type context_codes: string or None
:param per_page: (optional) Set how many results canvas should return, defaults to config.LIMIT_PER_PAGE
:type per_page: integer or None
:return: List calendar events
:rtype: requests.Response (with array data)
"""
if per_page is None:
per_page = request_ctx.per_page
type_types = ('event', 'assignment')
utils.validate_attr_is_acceptable(type, type_types)
path = '/v1/calendar_events'
payload = {
'type': type,
'start_date': start_date,
'end_date': end_date,
'undated': undated,
'all_events': all_events,
'context_codes': context_codes,
'per_page': per_page,
}
url = request_ctx.base_api_url + path.format()
response = client.get(request_ctx, url, payload=payload, **request_kwargs)
return response
def update_group_category(request_ctx,
group_category_id,
name,
self_signup=None,
auto_leader=None,
group_limit=None,
create_group_count=None,
split_group_count=None,
**request_kwargs):
"""
Modifies an existing group category.
:param request_ctx: The request context
:type request_ctx: :class:RequestContext
:param group_category_id: (required) ID
:type group_category_id: string
:param name: (required) Name of the group category
:type name: string
:param self_signup: (optional) Allow students to sign up for a group themselves (Course Only). Valid values are: "enabled":: allows students to self sign up for any group in course "restricted":: allows students to self sign up only for groups in the same section null disallows self sign up
:type self_signup: string or None
:param auto_leader: (optional) Assigns group leaders automatically when generating and allocating students to groups Valid values are: "first":: the first student to be allocated to a group is the leader "random":: a random student from all members is chosen as the leader
:type auto_leader: string or None
:param group_limit: (optional) Limit the maximum number of users in each group (Course Only). Requires self signup.
:type group_limit: string or None
:param create_group_count: (optional) Create this number of groups (Course Only).
:type create_group_count: string or None
:param split_group_count: (optional) (Deprecated) Create this number of groups, and evenly distribute students among them. not allowed with "enable_self_signup". because the group assignment happens synchronously, it's recommended that you instead use the assign_unassigned_members endpoint. (Course Only)
:type split_group_count: string or None
:return: Update a Group Category
:rtype: requests.Response (with GroupCategory data)
"""
self_signup_types = ('enabled', 'restricted')
auto_leader_types = ('first', 'random')
utils.validate_attr_is_acceptable(self_signup, self_signup_types)
utils.validate_attr_is_acceptable(auto_leader, auto_leader_types)
path = '/v1/group_categories/{group_category_id}'
payload = {
'name': name,
'self_signup': self_signup,
'auto_leader': auto_leader,
'group_limit': group_limit,
'create_group_count': create_group_count,
'split_group_count': split_group_count,
}
url = request_ctx.base_api_url + path.format(
group_category_id=group_category_id)
response = client.put(request_ctx, url, payload=payload, **request_kwargs)
return response
