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())