def cross_list_section(self, new_course):
"""
Move the Section to another course.
:calls: `POST /api/v1/sections/:id/crosslist/:new_course_id \
<https://canvas.instructure.com/doc/api/sections.html#method.sections.crosslist>`_
:param new_course: The object or ID of the new course.
:type new_course: :class:`canvasapi.course.Course` or int
:rtype: :class:`canvasapi.section.Section`
"""
from canvasapi.course import Course
new_course_id = obj_or_id(new_course, "new_course", (Course, ))
response = self._requester.request(
'POST', 'sections/{}/crosslist/{}'.format(self.id, new_course_id))
return Section(self._requester, response.json())
def get_group_category(self, category):
"""
Get a single group category.
:calls: `GET /api/v1/group_categories/:group_category_id \
<https://canvas.instructure.com/doc/api/group_categories.html#method.group_categories.show>`_
:param category: The object or ID of the category.
:type category: :class:`canvasapi.group.GroupCategory` or int
:rtype: :class:`canvasapi.group.GroupCategory`
"""
category_id = obj_or_id(category, "category", (GroupCategory,))
response = self.__requester.request(
'GET',
'group_categories/{}'.format(category_id)
)
return GroupCategory(self.__requester, response.json())
def get_outcome(self, outcome):
"""
Returns the details of the outcome with the given id.
:calls: `GET /api/v1/outcomes/:id \
<https://canvas.instructure.com/doc/api/outcomes.html#method.outcomes_api.show>`_
:param outcome: The outcome object or ID to return.
:type outcome: :class:`canvasapi.outcome.Outcome` or int
:returns: An Outcome object.
:rtype: :class:`canvasapi.outcome.Outcome`
"""
from canvasapi.outcome import Outcome
outcome_id = obj_or_id(outcome, "outcome", (Outcome, ))
response = self.__requester.request("GET",
"outcomes/{}".format(outcome_id))
return Outcome(self.__requester, response.json())
def merge_into(self, destination_user):
"""
Merge this user into another user.
:calls: `PUT /api/v1/users/:id/merge_into/:destination_user_id \
<https://canvas.instructure.com/doc/api/users.html#method.users.merge_into>`_
:param destination_user: The object or ID of the user to merge into.
:type destination_user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.user.User`
"""
dest_user_id = obj_or_id(destination_user, "destination_user",
(User, ))
response = self._requester.request(
"PUT", "users/{}/merge_into/{}".format(self.id, dest_user_id))
super(User, self).set_attributes(response.json())
return self
def get_bookmark(self, bookmark):
"""
Return single Bookmark by id
:calls: `GET /api/v1/users/self/bookmarks/:id \
<https://canvas.instructure.com/doc/api/bookmarks.html#method.bookmarks/bookmarks.show>`_
:param bookmark: The object or ID of the bookmark.
:type bookmark: :class:`canvasapi.bookmark.Bookmark` or int
:rtype: :class:`canvasapi.bookmark.Bookmark`
"""
from canvasapi.bookmark import Bookmark
bookmark_id = obj_or_id(bookmark, "bookmark", (Bookmark, ))
response = self._requester.request(
'GET', 'users/self/bookmarks/{}'.format(bookmark_id))
return Bookmark(self._requester, response.json())
def remove_user(self, user):
"""
Leave a group if allowed.
:calls: `DELETE /api/v1/groups/:group_id/users/:user_id \
<https://canvas.instructure.com/doc/api/groups.html#method.group_memberships.destroy>`_
:param user: The user object or ID to remove from the group.
:type user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.user.User`
"""
from canvasapi.user import User
user_id = obj_or_id(user, "user", (User, ))
response = self._requester.request(
"DELETE", "groups/{}/users/{}".format(self.id, user_id))
return User(self._requester, response.json())
def delete_external_feed(self, feed):
"""
Deletes the external feed.
:calls: `DELETE /api/v1/groups/:group_id/external_feeds/:external_feed_id \
<https://canvas.instructure.com/doc/api/announcement_external_feeds.html#method.external_feeds.destroy>`_
:param feed: The object or id of the feed to be deleted.
:type feed: :class:`canvasapi.external_feed.ExternalFeed` or int
:rtype: :class:`canvasapi.external_feed.ExternalFeed`
"""
from canvasapi.external_feed import ExternalFeed
feed_id = obj_or_id(feed, "feed", (ExternalFeed, ))
response = self._requester.request(
"DELETE", "groups/{}/external_feeds/{}".format(self.id, feed_id))
return ExternalFeed(self._requester, response.json())
def get_poll(self, poll, **kwargs):
"""
Get a single poll, based on the poll id.
:calls: `GET /api/v1/polls/:id \
<https://canvas.instructure.com/doc/api/polls.html#method.polling/polls.show>`_
:param poll: The ID of the poll or the poll to change.
:type poll: int
:rtype: :class:`canvasapi.poll.Poll`
"""
from canvasapi.poll import Poll
poll_id = obj_or_id(poll, "poll", (Poll, ))
response = self.__requester.request("GET",
"polls/{}".format(poll_id),
_kwargs=combine_kwargs(**kwargs))
return Poll(self.__requester, response.json()["polls"][0])
def get_full_discussion_topic(self, topic):
"""
Return a cached structure of the discussion topic.
:calls: `GET /api/v1/groups/:group_id/discussion_topics/:topic_id/view \
<https://canvas.instructure.com/doc/api/discussion_topics.html#method.discussion_topics_api.view>`_
:param topic: The object or ID of the discussion topic.
:type topic: :class:`canvasapi.discussion_topic.DiscussionTopic` or int
:rtype: dict
"""
topic_id = obj_or_id(topic, "topic", (DiscussionTopic, ))
response = self._requester.request(
'GET',
'groups/{}/discussion_topics/{}/view'.format(self.id, topic_id),
)
return response.json()
def get_course_nickname(self, course):
"""
Return the nickname for the given course.
:calls: `GET /api/v1/users/self/course_nicknames/:course_id \
<https://canvas.instructure.com/doc/api/users.html#method.course_nicknames.show>`_
:param course: The object or ID of the course.
:type course: :class:`canvasapi.course.Course` or int
:rtype: :class:`canvasapi.course.CourseNickname`
"""
from canvasapi.course import CourseNickname
course_id = obj_or_id(course, "course", (Course, ))
response = self.__requester.request(
"GET", "users/self/course_nicknames/{}".format(course_id))
return CourseNickname(self.__requester, response.json())
def get_folder(self, folder):
"""
Returns the details for a user's folder
:calls: `GET /api/v1/users/:user_id/folders/:id \
<https://canvas.instructure.com/doc/api/files.html#method.folders.show>`_
:param folder: The object or ID of the folder to retrieve.
:type folder: :class:`canvasapi.folder.Folder` or int
:rtype: :class:`canvasapi.folder.Folder`
"""
from canvasapi.folder import Folder
folder_id = obj_or_id(folder, "folder", (Folder, ))
response = self._requester.request(
'GET', 'users/{}/folders/{}'.format(self.id, folder_id))
return Folder(self._requester, response.json())
def get_folder(self, folder, **kwargs):
"""
Returns the details for a group's folder
:calls: `GET /api/v1/groups/:group_id/folders/:id \
<https://canvas.instructure.com/doc/api/files.html#method.folders.show>`_
:param folder: The object or ID of the folder to retrieve.
:type folder: :class:`canvasapi.folder.Folder` or int
:rtype: :class:`canvasapi.folder.Folder`
"""
folder_id = obj_or_id(folder, "folder", (Folder,))
response = self._requester.request(
"GET",
"groups/{}/folders/{}".format(self.id, folder_id),
_kwargs=combine_kwargs(**kwargs),
)
return Folder(self._requester, response.json())
def get_calendar_event(self, calendar_event):
"""
Return single Calendar Event by id
:calls: `GET /api/v1/calendar_events/:id \
<https://canvas.instructure.com/doc/api/calendar_events.html#method.calendar_events_api.show>`_
:param calendar_event: The object or ID of the calendar event.
:type calendar_event: :class:`canvasapi.calendar_event.CalendarEvent` or int
:rtype: :class:`canvasapi.calendar_event.CalendarEvent`
"""
from canvasapi.calendar_event import CalendarEvent
calendar_event_id = obj_or_id(calendar_event, "calendar_event",
(CalendarEvent, ))
response = self.__requester.request(
'GET', 'calendar_events/{}'.format(calendar_event_id))
return CalendarEvent(self.__requester, response.json())
def get_session(self, poll_session, **kwargs):
"""
Returns the poll session with the given id.
:calls: `GET /api/v1/polls/:poll_id/poll_sessions/:id \
<https://canvas.instructure.com/doc/api/poll_sessions.html#method.polling/poll_sessions.show>`_
:param poll_session: List of arguments. Takes a poll session id (int) or poll session \
object.
:rtype: :class:`canvasapi.poll_session.PollSession`
"""
poll_session_id = obj_or_id(poll_session, "poll_session", (PollSession,))
response = self._requester.request(
'GET',
'polls/{}/poll_sessions/{}'.format(self.id, poll_session_id),
_kwargs=combine_kwargs(**kwargs)
)
return PollSession(self._requester, response.json()['poll_sessions'][0])
def deactivate_role(self, role, **kwargs):
"""
Deactivate a custom role.
:calls: `DELETE /api/v1/accounts/:account_id/roles/:id \
<https://canvas.instructure.com/doc/api/roles.html#method.role_overrides.remove_role>`_
:param role: The object or ID of the role.
:type role: :class:`canvasapi.account.Role` or int
:rtype: :class:`canvasapi.account.Role`
"""
role_id = obj_or_id(role, "role", (Role,))
response = self._requester.request(
'DELETE',
'accounts/{}/roles/{}'.format(self.id, role_id),
_kwargs=combine_kwargs(**kwargs)
)
return Role(self._requester, response.json())
def get_file(self, file, **kwargs):
"""
Return the standard attachment json object for a file.
:calls: `GET /api/v1/groups/:group_id/files/:id \
<https://canvas.instructure.com/doc/api/files.html#method.files.api_show>`_
:param file: The object or ID of the file to retrieve.
:type file: :class:`canvasapi.file.File` or int
:rtype: :class:`canvasapi.file.File`
"""
from canvasapi.file import File
file_id = obj_or_id(file, "file", (File, ))
response = self._requester.request('GET',
'groups/{}/files/{}'.format(
self.id, file_id),
_kwargs=combine_kwargs(**kwargs))
return File(self._requester, response.json())
def update_role(self, role, **kwargs):
"""
Update permissions for an existing role.
:calls: `PUT /api/v1/accounts/:account_id/roles/:id \
<https://canvas.instructure.com/doc/api/roles.html#method.role_overrides.update>`_
:param role: The object or ID of the role.
:type role: :class:`canvasapi.account.Role` or int
:rtype: :class:`canvasapi.account.Role`
"""
role_id = obj_or_id(role, "role", (Role,))
response = self._requester.request(
'PUT',
'accounts/{}/roles/{}'.format(self.id, role_id),
_kwargs=combine_kwargs(**kwargs)
)
return Role(self._requester, response.json())
def get_announcements(self, context_codes, **kwargs):
"""
List announcements.
:calls: `GET /api/v1/announcements \
<https://canvas.instructure.com/doc/api/announcements.html#method.announcements_api.index>`_
:param context_codes: Course ID(s) or <Course> objects to request announcements from.
:type context_codes: list
:rtype: :class:`canvasapi.paginated_list.PaginatedList` of
:class:`canvasapi.discussion_topic.DiscussionTopic`
"""
from canvasapi.discussion_topic import DiscussionTopic
if type(context_codes) is not list or len(context_codes) == 0:
raise RequiredFieldMissing("context_codes need to be passed as a list")
if isinstance(context_codes[0], str) and "course_" in context_codes[0]:
# Legacy support for context codes passed as list of `course_123`-style strings
kwargs["context_codes"] = context_codes
else:
# The type of object in `context_codes` is taken care of by obj_or_id, extracting
# the course ID from a <Course> object or by returning plain strings.
course_ids = [
obj_or_id(course_id, "context_codes", (Course,))
for course_id in context_codes
]
# Set the **kwargs object vaue so it can be combined with others passed by the user.
kwargs["context_codes"] = [
f"course_{course_id}" for course_id in course_ids
]
return PaginatedList(
DiscussionTopic,
self.__requester,
"GET",
"announcements",
_kwargs=combine_kwargs(**kwargs),
)
def get_user_notifications(self, user):
"""
Return a list of all global notifications in the account for
this user. Any notifications that have been closed by the user
will not be returned.
:calls: `GET /api/v1/accounts/:account_id/users/:user_id/account_notifications \
<https://canvas.instructure.com/doc/api/account_notifications.html#method.account_notifications.user_index>`_
:param user: The user object or ID to retrieve notifications for.
:type user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.paginated_list.PaginatedList` of
:class:`canvasapi.account.AccountNotification`
"""
from canvasapi.user import User
user_id = obj_or_id(user, "user", (User, ))
return PaginatedList(
AccountNotification, self._requester, 'GET',
'accounts/%s/users/%s/account_notifications' % (self.id, user_id))
def get_progress(self, progress, **kwargs):
"""
Get a specific progress.
:calls: `GET /api/v1/progress/:id
<https://canvas.instructure.com/doc/api/progress.html#method.progress.show>`_
:param progress: The object or ID of the progress to retrieve.
:type progress: int, str or :class:`canvasapi.progress.Progress`
:rtype: :class:`canvasapi.progress.Progress`
"""
from canvasapi.progress import Progress
progress_id = obj_or_id(progress, "progress", (Progress, ))
response = self.__requester.request('GET',
'progress/{}'.format(progress_id),
_kwargs=combine_kwargs(**kwargs))
return Progress(self.__requester, response.json())
def enroll_user(self, user, **kwargs):
"""
Create a new user enrollment for a course or a section.
:calls: `POST /api/v1/section/:section_id/enrollments \
<https://canvas.instructure.com/doc/api/enrollments.html#method.enrollments_api.create>`_
:param user: The object or ID of the user to enroll in this course.
:type user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.enrollment.Enrollment`
"""
kwargs["enrollment[user_id]"] = obj_or_id(user, "user", (User, ))
response = self._requester.request(
"POST",
"sections/{}/enrollments".format(self.id),
_kwargs=combine_kwargs(**kwargs),
)
return Enrollment(self._requester, response.json())
def update_membership(self, user, **kwargs):
"""
Accept a membership request, or add/remove moderator rights.
:calls: `PUT /api/v1/groups/:group_id/users/:user_id \
<https://canvas.instructure.com/doc/api/groups.html#method.group_memberships.update>`_
:param user: The object or ID of the user.
:type user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.group.GroupMembership`
"""
from canvasapi.user import User
user_id = obj_or_id(user, "user", (User, ))
response = self._requester.request('PUT',
'groups/{}/users/{}'.format(
self.id, user_id),
_kwargs=combine_kwargs(**kwargs))
return GroupMembership(self._requester, response.json())
def get_discussion_topic(self, topic):
"""
Return data on an individual discussion topic.
:calls: `GET /api/v1/groups/:group_id/discussion_topics/:topic_id \
<https://canvas.instructure.com/doc/api/discussion_topics.html#method.discussion_topics_api.show>`_
:param topic: The object or ID of the discussion topic.
:type topic: :class:`canvasapi.discussion_topic.DiscussionTopic` or int
:rtype: :class:`canvasapi.discussion_topic.DiscussionTopic`
"""
topic_id = obj_or_id(topic, "topic", (DiscussionTopic, ))
response = self._requester.request(
'GET', 'groups/{}/discussion_topics/{}'.format(self.id, topic_id))
response_json = response.json()
response_json.update({'group_id': self.id})
return DiscussionTopic(self._requester, response_json)
def get_outcome_group(self, group):
"""
Returns the details of the Outcome Group with the given id.
:calls: `GET /api/v1/global/outcome_groups/:id \
<https://canvas.instructure.com/doc/api/outcome_groups.html#method.outcome_groups_api.show>`_
:param group: The outcome group object or ID to return.
:type group: :class:`canvasapi.outcome.OutcomeGroup` or int
:returns: An outcome group object.
:rtype: :class:`canvasapi.outcome.OutcomeGroup`
"""
from canvasapi.outcome import OutcomeGroup
outcome_group_id = obj_or_id(group, "group", (OutcomeGroup, ))
response = self.__requester.request(
'GET', 'global/outcome_groups/{}'.format(outcome_group_id))
return OutcomeGroup(self.__requester, response.json())
def get_appointment_group(self, appointment_group):
"""
Return single Appointment Group by id
:calls: `GET /api/v1/appointment_groups/:id \
<https://canvas.instructure.com/doc/api/appointment_groups.html#method.appointment_groups.show>`_
:param appointment_group: The ID of the appointment group.
:type appointment_group: :class:`canvasapi.appointment_group.AppointmentGroup` or int
:rtype: :class:`canvasapi.appointment_group.AppointmentGroup`
"""
from canvasapi.appointment_group import AppointmentGroup
appointment_group_id = obj_or_id(appointment_group,
"appointment_group",
(AppointmentGroup, ))
response = self.__requester.request(
'GET', 'appointment_groups/{}'.format(appointment_group_id))
return AppointmentGroup(self.__requester, response.json())
def get_quiz_submission(self, quiz_submission, **kwargs):
"""
Get a single quiz submission.
:calls: `GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions/:id \
<https://canvas.instructure.com/doc/api/quiz_submissions.html#method.quizzes/quiz_submissions_api.show>`_
:param quiz_submission: The object or ID of the quiz submission to retrieve.
:type quiz_submission: int, string, :class:`canvasapi.quiz.QuizSubmission`
:rtype: :class:`canvasapi.quiz.QuizSubmission`
"""
quiz_submission_id = obj_or_id(quiz_submission, "quiz_submission",
(QuizSubmission, ))
response = self._requester.request(
"GET",
"courses/{}/quizzes/{}/submissions/{}".format(
self.course_id, self.id, quiz_submission_id),
_kwargs=combine_kwargs(**kwargs),
)
response_json = response.json()["quiz_submissions"][0]
response_json.update({"course_id": self.course_id})
if len(response.json().get("quizzes", [])) > 0:
response_json.update(
{"quiz": Quiz(self._requester,
response.json()["quizzes"][0])})
if len(response.json().get("submissions", [])) > 0:
response_json.update({
"submission":
Submission(self._requester,
response.json()["submissions"][0])
})
if len(response.json().get("users", [])) > 0:
response_json.update(
{"user": User(self._requester,
response.json()["users"][0])})
return QuizSubmission(self._requester, response_json)
def remove_user(self, user):
"""
Remove user from membership.
:calls: `DELETE /api/v1/groups/:group_id/:type/:id \
<https://canvas.instructure.com/doc/api/groups.html#method.group_memberships.destroy>`_
:param user: The user object or ID to remove from the group.
:type user: :class:`canvasapi.user.User` or int
:returns: An empty dictionary
:rtype: dict
"""
from canvasapi.user import User
user_id = obj_or_id(user, "user", (User,))
response = self._requester.request(
'DELETE',
'groups/{}/users/{}'.format(self.id, user_id),
)
return response.json()
def get_override(self, override, **kwargs):
"""
Get a single assignment override with the given override id.
:calls: `GET /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id \
<https://canvas.instructure.com/doc/api/assignments.html#method.assignment_overrides.show>`_
:param override: The object or ID of the override to get
:type override: :class:`canvasapi.assignment.AssignmentOverride` or int
:rtype: :class:`canvasapi.assignment.AssignmentOverride`
"""
override_id = obj_or_id(override, "override", (AssignmentOverride, ))
response = self._requester.request(
'GET',
'courses/{}/assignments/{}/overrides/{}'.format(
self.course_id, self.id, override_id),
_kwargs=combine_kwargs(**kwargs))
response_json = response.json()
response_json.update(course_id=self.course_id)
return AssignmentOverride(self._requester, response_json)
def get_membership(self, user, membership_type):
"""
List users in a group.
:calls: `GET /api/v1/groups/:group_id/users/:user_id \
<https://canvas.instructure.com/doc/api/groups.html#method.group_memberships.show>`_
or `GET /api/v1/groups/:group_id/memberships/:membership_id
<https://canvas.instructure.com/doc/api/groups.html#method.group_memberships.show>`_
:param user: list of user ids
:type user: :class:`canvasapi.user.User` or int
:rtype: :class:`canvasapi.group.GroupMembership`
"""
from canvasapi.user import User
user_id = obj_or_id(user, "user", (User, ))
response = self._requester.request(
'GET', 'groups/{}/{}/{}'.format(self.id, membership_type, user_id))
return GroupMembership(self._requester, response.json())
def get_conversation(self, conversation, **kwargs):
"""
Return single Conversation
:calls: `GET /api/v1/conversations/:id \
<https://canvas.instructure.com/doc/api/conversations.html#method.conversations.show>`_
:param conversation: The object or ID of the conversation.
:type conversation: :class:`canvasapi.conversation.Conversation` or int
:rtype: :class:`canvasapi.conversation.Conversation`
"""
from canvasapi.conversation import Conversation
conversation_id = obj_or_id(conversation, "conversation",
(Conversation, ))
response = self.__requester.request(
'GET',
'conversations/{}'.format(conversation_id),
_kwargs=combine_kwargs(**kwargs))
return Conversation(self.__requester, response.json())
