lms.djangoapps.instructor package

Contents

lms.djangoapps.instructor package#

Subpackages#

Submodules#

lms.djangoapps.instructor.access module#

Access control operations for use by instructor APIs.

Does not include any access control, be sure to check access before calling.

TO DO sync instructor and staff flags
e.g. should these be possible?

{instructor: true, staff: false} {instructor: true, staff: true}

lms.djangoapps.instructor.access.FORUM_ROLES = ('Administrator', 'Moderator', 'Group Moderator', 'Community TA')#

Forum/discussion roles managed through update_forum_role(). Stored separately from ROLES because they use a different model (Role from django_comment_common) and different helpers.

lms.djangoapps.instructor.access.allow_access(course, user, level, send_email=True)#

Allow user access to course modification.

level is one of [‘instructor’, ‘staff’, ‘beta’]

lms.djangoapps.instructor.access.is_beta_tester(user, course_id)#

Returns True if the user is a beta tester in this course, and False if not

lms.djangoapps.instructor.access.is_forum_role(rolename)#

Return True if rolename is a forum/discussion role.

lms.djangoapps.instructor.access.list_forum_members(course_id, rolename)#

Return a User QuerySet of users holding rolename forum role for the course.

Returns an empty QuerySet if the role doesn’t exist for the course.

lms.djangoapps.instructor.access.list_with_level(course_id, level)#

List users who have ‘level’ access.

level is in [‘instructor’, ‘staff’, ‘beta’] for standard courses. There could be other levels specific to the course. If there is no Group for that course-level, returns an empty list

lms.djangoapps.instructor.access.revoke_access(course, user, level, send_email=True)#

Revoke access from user to course modification.

level is one of [‘instructor’, ‘staff’, ‘beta’]

lms.djangoapps.instructor.access.update_forum_role(course_id, user, rolename, action)#

Change forum access of user.

rolename is one of [FORUM_ROLE_ADMINISTRATOR, FORUM_ROLE_MODERATOR, FORUM_ROLE_COMMUNITY_TA] action is one of [‘allow’, ‘revoke’]

if action is bad, raises ValueError if rolename does not exist, raises Role.DoesNotExist

lms.djangoapps.instructor.apps module#

Instructor Application Configuration

class lms.djangoapps.instructor.apps.InstructorConfig(app_name, app_module)#

Bases: AppConfig

Application Configuration for Instructor.

name = 'lms.djangoapps.instructor'#
plugin_app = {'settings_config': {'lms.djangoapp': {'common': {'relative_path': 'settings.common'}, 'devstack': {'relative_path': 'settings.devstack'}, 'production': {'relative_path': 'settings.production'}, 'test': {'relative_path': 'settings.test'}}}, 'url_config': {'lms.djangoapp': {'app_name': 'lms.djangoapps.instructor', 'namespace': '', 'regex': '', 'relative_path': 'urls'}}}#
ready()#

Override this method in subclasses to run code when Django starts.

lms.djangoapps.instructor.constants module#

Constants used by Instructor.

class lms.djangoapps.instructor.constants.ReportType(*values)#

Bases: StrEnum

Enum for report types used in the instructor dashboard downloads API. These are the user-facing report type identifiers.

ANONYMIZED_STUDENT_IDS = 'anonymized_student_ids'#
COHORT_RESULTS = 'cohort_results'#
ENROLLED_STUDENTS = 'enrolled_students'#
GRADE = 'grade'#
ISSUED_CERTIFICATES = 'issued_certificates'#
ORA2_DATA = 'ora2_data'#
ORA2_SUBMISSION_FILES = 'ora2_submission_files'#
ORA2_SUMMARY = 'ora2_summary'#
PENDING_ACTIVATIONS = 'pending_activations'#
PENDING_ENROLLMENTS = 'pending_enrollments'#
PROBLEM_GRADE = 'problem_grade'#
PROBLEM_RESPONSES = 'problem_responses'#
UNKNOWN = 'unknown'#

lms.djangoapps.instructor.enrollment module#

Enrollment operations for use by instructor APIs.

Does not include any access control, be sure to check access before calling.

class lms.djangoapps.instructor.enrollment.EmailEnrollmentState(course_id, email)#

Bases: object

Store the complete enrollment state of an email in a class

to_dict()#
example: {

‘user’: False, ‘enrollment’: False, ‘allowed’: True, ‘auto_enroll’: True,

}

lms.djangoapps.instructor.enrollment.enroll_email(course_id, student_email, auto_enroll=False, message_students=False, message_params=None, language=None)#

Enroll a student by email.

student_email is student’s emails e.g. “foo@bar.com” auto_enroll determines what is put in CourseEnrollmentAllowed.auto_enroll

if auto_enroll is set, then when the email registers, they will be enrolled in the course automatically.

message_students determines if student should be notified of action by email or push message. message_params parameters used while parsing message templates (a dict). language is the language used to render the email.

returns two EmailEnrollmentState’s

representing state before and after the action.

lms.djangoapps.instructor.enrollment.get_email_params(course, auto_enroll, secure=True, course_key=None, display_name=None)#

Generate parameters used when parsing email templates.

auto_enroll is a flag for auto enrolling non-registered students: (a boolean) Returns a dict of parameters

lms.djangoapps.instructor.enrollment.get_subject_and_message(subject_template, message_template, param_dict)#

Return the rendered subject and message with the appropriate parameters.

lms.djangoapps.instructor.enrollment.get_user_email_language(user)#

Return the language most appropriate for writing emails to user. Returns None if the preference has not been set, or if the user does not exist.

lms.djangoapps.instructor.enrollment.render_message_to_string(subject_template, message_template, param_dict, language=None)#

Render a mail subject and message templates using the parameters from param_dict and the given language. If language is None, the platform default language is used.

Returns two strings that correspond to the rendered, translated email subject and message.

lms.djangoapps.instructor.enrollment.reset_student_attempts(course_id, student, module_state_key, requesting_user, delete_module=False, emit_signals_and_events=True)#

Reset student attempts for a problem. Optionally deletes all student state for the specified problem.

In the previous instructor dashboard it was possible to modify/delete modules that were not problems. That has been disabled for safety.

student is a User problem_to_reset is the name of a problem e.g. ‘L2Node1’. To build the module_state_key ‘problem/’ and course information will be appended to problem_to_reset. delete_module: Instead of resetting attempts, delete the learner’s StudentModule emit_signals_and_events: If this is False, don’t fire django signals or emit events. This is intended for

the case where we are calling this function many times, and want to handle the signalling and eventing at a bulk level rather than firing every individual call to this function

Raises:

  • ValueError – problem_state is invalid JSON.

  • StudentModule.DoesNotExist – could not load the student module.

  • submissions.SubmissionError – unexpected error occurred while resetting the score in the submissions API.

lms.djangoapps.instructor.enrollment.send_beta_role_email(action, user, message_params)#

Send an email to a user added or removed as a beta tester.

action is one of ‘add’ or ‘remove’ user is the User affected message_params parameters used while parsing email templates (a dict).

lms.djangoapps.instructor.enrollment.send_mail_to_student(student, param_dict, language=None)#

Construct the email using templates and then send it. student is the student’s email address (a str),

param_dict is a dict with keys [

site_name: name given to edX instance (a str) registration_url: url for registration (a str) display_name : display name of a course (a str) course_id: id of course (a str) auto_enroll: user input option (a str) course_url: url of course (a str) user_id: LMS user ID of student (an int) - None if unknown email_address: email of student (a str) full_name: student full name (a str) message_type: type of email to send and template to use (a str) is_shib_course: (a boolean)

]

language is the language used to render the email. If None the language of the currently-logged in user (that is, the user sending the email) will be used.

Returns a boolean indicating whether the email was sent successfully.

lms.djangoapps.instructor.enrollment.unenroll_email(course_id, student_email, message_students=False, message_params=None, language=None)#

Unenroll a student by email.

student_email is student’s emails e.g. “foo@bar.com” message_students determines if student should be notified of action by email or push message. message_params parameters used while parsing email templates (a dict). language is the language used to render the email.

returns two EmailEnrollmentState’s

representing state before and after the action.

lms.djangoapps.instructor.enrollment.uses_shib(course)#

Used to return whether course has Shibboleth as the enrollment domain

Returns a boolean indicating if Shibboleth authentication is set for this course.

lms.djangoapps.instructor.handlers module#

Handlers for instructor

lms.djangoapps.instructor.handlers.handle_exam_completion(sender, signal, **kwargs)#

exam completion event from the event bus

lms.djangoapps.instructor.handlers.handle_exam_reset(sender, signal, **kwargs)#

exam reset event from the event bus

lms.djangoapps.instructor.message_types module#

ACE message types for the instructor module.

class lms.djangoapps.instructor.message_types.AccountCreationAndEnrollment(*args, **kwargs)#

Bases: BaseMessageType

A message for registering and inviting learners into a course.

This message includes username and password.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.AddBetaTester(*args, **kwargs)#

Bases: BaseMessageType

A message for course beta testers when they’re invited.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.AllowedEnroll(*args, **kwargs)#

Bases: BaseMessageType

A message for _unregistered_ learners who received an invitation to a course.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.AllowedUnenroll(*args, **kwargs)#

Bases: BaseMessageType

A message for _unregistered_ learners who had their invitation to a course cancelled.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.BatchEnrollment(*args, **kwargs)#

Bases: BaseMessageType

A message for instructors when they finish the batch enrollment async process.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.EnrollEnrolled(*args, **kwargs)#

Bases: BaseMessageType

A message for _registered_ learners who have been both invited and enrolled to a course.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.EnrolledUnenroll(*args, **kwargs)#

Bases: BaseMessageType

A message for _registered_ learners who have been unenrolled from a course.

APP_LABEL = 'instructor'#
class lms.djangoapps.instructor.message_types.RemoveBetaTester(*args, **kwargs)#

Bases: BaseMessageType

A message for course beta testers when they’re removed.

APP_LABEL = 'instructor'#

lms.djangoapps.instructor.ora module#

Utilities for retrieving Open Response Assessments (ORAs) data for instructor dashboards.

lms.djangoapps.instructor.ora.get_open_response_assessment_list(course)#

Return a list of Open Response Assessments (ORAs) for a course.

Uses OraAggregateData to collect response metrics, which transparently supports both ORA1 and ORA2 data.

lms.djangoapps.instructor.ora.get_ora_summary(course)#

Return aggregated ORA statistics for a course.

lms.djangoapps.instructor.permissions module#

Permissions for the instructor dashboard and associated actions

class lms.djangoapps.instructor.permissions.CourseTeamPermission#

Bases: BasePermission

Allow access to course team management endpoints for users with instructor (Admin) access or the Discussion Admin (staff + forum Administrator) role.

has_permission(request, view)#

Return True if permission is granted, False otherwise.

class lms.djangoapps.instructor.permissions.ForumAdminRequiresInstructorAccess#

Bases: BasePermission

default roles require either (staff & forum admin) or (instructor) User should be forum-admin and staff to access this endpoint.

But if request rolename is FORUM_ROLE_ADMINISTRATOR, then user must also have instructor-level access to proceed.

has_permission(request, view)#

Permission class for forum endpoints.

Only allow if: - User is an instructor, OR - User is staff AND forum admin.

Special case: - If the action relates to forum admin (FORUM_ROLE_ADMINISTRATOR), user must be instructor.

class lms.djangoapps.instructor.permissions.InstructorPermission#

Bases: BasePermission

Generic permissions

has_permission(request, view)#

Return True if permission is granted, False otherwise.

lms.djangoapps.instructor.services module#

Implementation of “Instructor” service

class lms.djangoapps.instructor.services.InstructorService#

Bases: object

Instructor service for deleting the students attempt(s) of an exam. This service has been created for the edx_proctoring’s dependency injection to cater for a requirement where edx_proctoring needs to call into edx-platform’s functions to delete the students’ existing answers, grades and attempt counts if there had been an earlier attempt.

This service also contains utility functions to check if a user is course staff, send notifications related to proctored exam attempts, and retrieve a course team’s proctoring escalation email.

complete_student_attempt(user_identifier: str, content_id: str) → None#

Calls the update_exam_completion_task, marking the exam as complete.

The task submits all completable xblocks inside of the content_id block to the Completion Service to mark them as complete. One use case of this function is for special exams (timed/proctored) where regardless of submission status on individual problems, we want to mark the entire exam as complete when the exam is finished.

params:

user_identifier (str): username or email of a user content_id (str): the block key for a piece of content

delete_student_attempt(student_identifier, course_id, content_id, requesting_user)#

Deletes student state for a problem. requesting_user may be kept as an audit trail.

Takes some of the following query parameters

  • student_identifier is an email or username

  • content_id is a url-name of a problem

  • course_id is the id for the course

get_proctoring_escalation_email(course_id)#

Returns the proctoring escalation email for a course, or None if not given.

Example arguments: * course_id (String): ‘block-v1:edX+DemoX+Demo_Course’

is_course_staff(user, course_id)#

Returns True if the user is the course staff else Returns False

send_support_notification(course_id, exam_name, student_username, review_status, review_url=None)#

Creates a Zendesk ticket for an exam attempt review from the proctoring system. Currently, it sends notifications for ‘Suspicious” status, but additional statuses can be supported by adding to the notify_support_for_status list in edx_proctoring/backends/software_secure.py The notifications can be disabled by disabling the “Create Zendesk Tickets For Suspicious Proctored Exam Attempts” setting in the course’s Advanced settings.

lms.djangoapps.instructor.tasks module#

Celery Tasks for the Instructor App.

lms.djangoapps.instructor.toggles module#

Waffle flags for instructor dashboard.

lms.djangoapps.instructor.toggles.data_download_v2_is_enabled()#

check if data download v2 is enabled.

lms.djangoapps.instructor.toggles.legacy_instructor_dashboard()#

Check if legacy instructor dashboard experience is enabled.

lms.djangoapps.instructor.toggles.use_optimised_is_small_course()#

lms.djangoapps.instructor.urls module#

Instructor API endpoint urls.

lms.djangoapps.instructor.utils module#

Utility functions for student enrollment operations.

This module contains reusable functions for processing student enrollments that can be used in both synchronous and asynchronous contexts.

lms.djangoapps.instructor.utils.process_single_student_enrollment(request_user: User, course_key: CourseKey, action: str, identifier: str, auto_enroll: bool, email_students: bool, reason: str | None, email_params: dict | None)#

Process enrollment/unenrollment for a single student.

Parameters:

  • request_user (User) – User who initiated the enrollment operation

  • course_key (CourseKey) – CourseKey object for the course

  • action (str) – ‘enroll’ or ‘unenroll’

  • identifier (str) – Student identifier (email or username)

  • auto_enroll (bool) – Whether to auto-enroll in verified track if applicable

  • email_students (bool) – Whether to send enrollment emails

  • reason (str | None) – Optional reason for enrollment change

  • email_params (dict | None) – Pre-computed email parameters (optional)

Returns:

Result of the enrollment operation with keys:

  • identifier: The student identifier

  • success: Boolean indicating if operation was successful

  • before: State before operation (if successful)

  • after: State after operation (if successful)

  • error_type: Type of error (‘invalid_identifier’, ‘validation_error’, ‘general_error’)

  • error_message: Error message (if failed)

Return type:

dict

lms.djangoapps.instructor.utils.process_student_enrollment_batch(request_user: User, course_key: CourseKey, action: str, identifiers: list[str], auto_enroll: bool, email_students: bool, reason: str | None, secure: bool, progress_callback: Callable[[...], None] | None = None)#

Process a batch of student enrollment/unenrollment operations.

Parameters:

  • request_user (User) – User who initiated the batch operation

  • course_key (CourseKey) – CourseKey object for the course

  • action (str) – ‘enroll’ or ‘unenroll’

  • identifiers (list[str]) – List of student identifiers (emails or usernames)

  • auto_enroll (bool) – Whether to auto-enroll in verified track if applicable

  • email_students (bool) – Whether to send enrollment emails

  • reason (str | None) – Optional reason for enrollment change

  • secure (bool) – Whether the request is secure (HTTPS)

  • progress_callback (Optional[Callable]) – Optional callback function to report progress Should accept (current, total, results) parameters

Returns:

Batch processing results with keys:

  • action: The action performed

  • auto_enroll: Auto-enrollment setting

  • results: List of individual enrollment results

  • successful_operations: Count of successful operations

  • failed_operations: Count of failed operations

  • total_students: Total number of students processed

Return type:

dict

Module contents#

Contents