lms.djangoapps.instructor_task package

Contents

lms.djangoapps.instructor_task package#

Subpackages#

Submodules#

lms.djangoapps.instructor_task.api module#

API for submitting background tasks by an instructor for a course.

Also includes methods for getting information about tasks that have already been submitted, filtered either by running state or input arguments.

exception lms.djangoapps.instructor_task.api.SpecificStudentIdMissingError#

Bases: Exception

Exception indicating that a student id was not provided when generating a certificate for a specific student.

lms.djangoapps.instructor_task.api.generate_anonymous_ids(request, course_key)#

Generate anonymize id CSV report.

lms.djangoapps.instructor_task.api.generate_certificates_for_students(request, course_key, student_set=None, specific_student_id=None)#

Submits a task to generate certificates for given students enrolled in the course.

Arguments:

course_key : Course Key student_set : Semantic for student collection for certificate generation.

Options are: ‘all_allowlisted’: All students on the certificate allowlist. ‘allowlisted_not_generated’: Students on certificate allowlist who do not have certificates yet. ‘specific_student’: Single student for certificate generation.

specific_student_id : Student ID when student_set is ‘specific_student’

Raises AlreadyRunningError if certificates are currently being generated. Raises SpecificStudentIdMissingError if student_set is ‘specific_student’ and specific_student_id is ‘None’

lms.djangoapps.instructor_task.api.get_entrance_exam_instructor_task_history(course_id, usage_key=None, student=None)#

Returns a query of InstructorTask objects of historical tasks for a given course, that optionally match an entrance exam and student if present.

lms.djangoapps.instructor_task.api.get_instructor_task_history(course_id, usage_key=None, student=None, task_type=None)#

Returns a query of InstructorTask objects of historical tasks for a given course, that optionally match a particular problem, a student, and/or a task type.

lms.djangoapps.instructor_task.api.get_running_instructor_tasks(course_id)#

Returns a query of InstructorTask objects of running tasks for a given course.

Used to generate a list of tasks to display on the instructor dashboard.

lms.djangoapps.instructor_task.api.process_scheduled_instructor_tasks()#

Utility function that retrieves tasks whose schedules have elapsed and should be processed. Only retrieves instructor tasks that are in the SCHEDULED state. Then submits these tasks for processing by Celery.

lms.djangoapps.instructor_task.api.regenerate_certificates(request, course_key, statuses_to_regenerate)#

Submits a task to regenerate certificates for given students enrolled in the course. Regenerate Certificate only if the status of the existing generated certificate is in ‘statuses_to_regenerate’ list passed in the arguments.

Raises AlreadyRunningError if certificates are currently being generated.

lms.djangoapps.instructor_task.api.submit_bulk_course_email(request, course_key, email_id, schedule=None)#

Request to have bulk email sent as a background task.

The specified CourseEmail object will be sent be updated for all students who have enrolled in a course. Parameters are the course_key and the email_id, the id of the CourseEmail object.

AlreadyRunningError is raised if the same recipients are already being emailed with the same CourseEmail object.

lms.djangoapps.instructor_task.api.submit_calculate_grades_csv(request, course_key, **task_kwargs)#

AlreadyRunningError is raised if the course’s grades are already being updated.

lms.djangoapps.instructor_task.api.submit_calculate_inactive_enrolled_students_csv(request, course_key, features)#

Submits a task to generate a CSV file containing information about enrolled students in a course who have not activated their account yet.

Raises AlreadyRunningError if said file is already being updated.

lms.djangoapps.instructor_task.api.submit_calculate_may_enroll_csv(request, course_key, features)#

Submits a task to generate a CSV file containing information about invited students who have not enrolled in a given course yet.

Raises AlreadyRunningError if said file is already being updated.

lms.djangoapps.instructor_task.api.submit_calculate_problem_responses_csv(request, course_key, problem_locations, problem_types_filter=None)#

Submits a task to generate a CSV file containing all student answers to a given problem.

Raises AlreadyRunningError if said file is already being updated.

lms.djangoapps.instructor_task.api.submit_calculate_students_features_csv(request, course_key, features, **task_kwargs)#

Submits a task to generate a CSV containing student profile info.

Raises AlreadyRunningError if said CSV is already being updated.

lms.djangoapps.instructor_task.api.submit_cohort_students(request, course_key, file_name)#

Request to have students cohorted in bulk.

Raises AlreadyRunningError if students are currently being cohorted.

lms.djangoapps.instructor_task.api.submit_course_survey_report(request, course_key)#

Submits a task to generate a HTML File containing the executive summary report.

Raises AlreadyRunningError if HTML File is already being updated.

lms.djangoapps.instructor_task.api.submit_delete_entrance_exam_state_for_student(request, usage_key, student)#

Requests reset of state for entrance exam as a background task.

Block state for all problems in entrance exam will be deleted for specified student.

All User Milestones of entrance exam will be removed for the specified student

Parameters are usage_key, which must be a Location representing entrance exam section and the student as a User object.

ItemNotFoundError is raised if entrance exam does not exists for given usage_key, AlreadyRunningError is raised if the entrance exam is already being reset.

lms.djangoapps.instructor_task.api.submit_delete_problem_state_for_all_students(request, usage_key)#

Request to have state deleted for a problem as a background task.

The problem’s state will be deleted for all students who have accessed the particular problem in a course. Parameters are the course_id and the usage_key, which must be a Location.

ItemNotFoundException is raised if the problem doesn’t exist, or AlreadyRunningError if the particular problem’s state is already being deleted.

lms.djangoapps.instructor_task.api.submit_export_ora2_data(request, course_key)#

AlreadyRunningError is raised if an ora2 report is already being generated.

lms.djangoapps.instructor_task.api.submit_export_ora2_submission_files(request, course_key)#

Submits a task to download and compress all submissions files (texts, attachments) for given course.

lms.djangoapps.instructor_task.api.submit_export_ora2_summary(request, course_key)#

AlreadyRunningError is raised if an ora2 report is already being generated.

lms.djangoapps.instructor_task.api.submit_override_score(request, usage_key, student, score)#

Request a problem score override as a background task. Only applicable to individual users.

The problem score will be overridden for the specified student only. Parameters are the course_id, the problem_url, the student as a User object, and the score override desired. The url must specify the location of the problem, using i4x-type notation.

ItemNotFoundException is raised if the problem doesn’t exist, or AlreadyRunningError if this task is already running for this student, or NotImplementedError if the problem is not a ScorableXBlock.

lms.djangoapps.instructor_task.api.submit_problem_grade_report(request, course_key, **task_kwargs)#

Submits a task to generate a CSV grade report containing problem values.

lms.djangoapps.instructor_task.api.submit_proctored_exam_results_report(request, course_key)#

Submits a task to generate a HTML File containing the executive summary report.

Raises AlreadyRunningError if HTML File is already being updated.

lms.djangoapps.instructor_task.api.submit_rescore_entrance_exam_for_student(request, usage_key, student=None, only_if_higher=False)#

Request entrance exam problems to be re-scored as a background task.

The entrance exam problems will be re-scored for given student or if student is None problems for all students who have accessed the entrance exam.

Parameters are usage_key, which must be a Location representing entrance exam section and the student as a User object.

ItemNotFoundError is raised if entrance exam does not exists for given usage_key, AlreadyRunningError is raised if the entrance exam is already being re-scored, or NotImplementedError if the problem doesn’t support rescoring.

lms.djangoapps.instructor_task.api.submit_rescore_problem_for_all_students(request, usage_key, only_if_higher=False)#

Request a problem to be rescored as a background task.

The problem will be rescored for all students who have accessed the particular problem in a course and have provided and checked an answer. Parameters are the course_id and the problem_url. The url must specify the location of the problem, using i4x-type notation.

ItemNotFoundException is raised if the problem doesn’t exist, or AlreadyRunningError if the problem is already being rescored, or NotImplementedError if the problem doesn’t support rescoring.

lms.djangoapps.instructor_task.api.submit_rescore_problem_for_student(request, usage_key, student, only_if_higher=False)#

Request a problem to be rescored as a background task.

The problem will be rescored for the specified student only. Parameters are the course_id, the problem_url, and the student as a User object. The url must specify the location of the problem, using i4x-type notation.

ItemNotFoundException is raised if the problem doesn’t exist, or AlreadyRunningError if the problem is already being rescored for this student, or NotImplementedError if the problem doesn’t support rescoring.

lms.djangoapps.instructor_task.api.submit_reset_problem_attempts_for_all_students(request, usage_key)#

Request to have attempts reset for a problem as a background task.

The problem’s attempts will be reset for all students who have accessed the particular problem in a course. Parameters are the course_id and the usage_key, which must be a Location.

ItemNotFoundException is raised if the problem doesn’t exist, or AlreadyRunningError if the problem is already being reset.

lms.djangoapps.instructor_task.api.submit_reset_problem_attempts_in_entrance_exam(request, usage_key, student)#

Request to have attempts reset for a entrance exam as a background task.

Problem attempts for all problems in entrance exam will be reset for specified student. If student is None problem attempts will be reset for all students.

Parameters are usage_key, which must be a Location representing entrance exam section and the student as a User object.

ItemNotFoundError is raised if entrance exam does not exists for given usage_key, AlreadyRunningError is raised if the entrance exam is already being reset.

lms.djangoapps.instructor_task.api.submit_student_enrollment_batch(request: HttpRequest, course_key: CourseKey, action: str, identifiers: list[str], auto_enroll: bool, email_students: bool, reason: str | None, secure: bool, site_id: int | None = None)#

Request to have student enrollment operations processed as a background task.

The task will process a batch of enrollment/unenrollment operations for the specified students in the given course.

Parameters:

  • request (HttpRequest) – The HTTP request object

  • course_key (CourseKey) – Course identifier

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

  • site_id (int | None) – Optional site ID for notification emails

Returns:

InstructorTask object representing the submitted background task

Raises:

AlreadyRunningError – If the same task is already running

lms.djangoapps.instructor_task.api_helper module#

Helper lib for instructor_tasks API.

Includes methods to check args for rescoring task, encoding student input, and task submission logic, including handling the Celery backend.

exception lms.djangoapps.instructor_task.api_helper.AlreadyRunningError(message=None)#

Bases: Exception

Exception indicating that a background task is already running

message = 'Requested task is already running'#
exception lms.djangoapps.instructor_task.api_helper.QueueConnectionError(message=None)#

Bases: Exception

Exception indicating that celery task was not created successfully.

message = 'Error occured. Please try again later.'#
lms.djangoapps.instructor_task.api_helper.check_arguments_for_overriding(usage_key, score)#

Do simple checks on the block to confirm that it supports overriding the problem score and the score passed in is not greater than the value of the problem or less than 0.

lms.djangoapps.instructor_task.api_helper.check_arguments_for_rescoring(usage_key)#

Do simple checks on the block to confirm that it supports rescoring.

Confirms first that the usage_key is defined (since that’s currently typed in). An ItemNotFoundException is raised if the corresponding module block doesn’t exist. NotImplementedError is raised if the corresponding module doesn’t support rescoring calls.

Note: the string returned here is surfaced as the error message on the instructor dashboard when a rescore is submitted for a non-rescorable block.

lms.djangoapps.instructor_task.api_helper.check_entrance_exam_problems_for_rescoring(exam_key)#

Grabs all problem blocks in exam and checks each block to confirm that it supports re-scoring.

An ItemNotFoundException is raised if the corresponding module block doesn’t exist for exam_key. NotImplementedError is raised if any of the problem in entrance exam doesn’t support re-scoring calls.

lms.djangoapps.instructor_task.api_helper.encode_entrance_exam_and_student_input(usage_key, student=None)#

Encode usage_key and optional student into task_key and task_input values.

Parameters:

  • usage_key (Location) – The usage_key identifying the entrance exam.

  • student (User) – the student affected

lms.djangoapps.instructor_task.api_helper.encode_problem_and_student_input(usage_key, student=None)#

Encode optional usage_key and optional student into task_key and task_input values.

Parameters:

  • usage_key (Location) – The usage_key identifying the problem.

  • student (User) – the student affected

lms.djangoapps.instructor_task.api_helper.generate_already_running_error_message(task_type)#

Returns already running error message for given task type.

lms.djangoapps.instructor_task.api_helper.get_status_from_instructor_task(instructor_task)#

Get the status for a given InstructorTask entry.

Returns a dict, with the following keys:

‘task_id’: id assigned by LMS and used by celery. ‘task_state’: state of task as stored in celery’s result store. ‘in_progress’: boolean indicating if task is still running. ‘task_progress’: dict containing progress information. This includes:

‘attempted’: number of attempts made ‘succeeded’: number of attempts that “succeeded” ‘total’: number of possible subtasks to attempt ‘action_name’: user-visible verb to use in status messages. Should be past-tense. ‘duration_ms’: how long the task has (or had) been running. ‘exception’: name of exception class raised in failed tasks. ‘message’: returned for failed and revoked tasks. ‘traceback’: optional, returned if task failed and produced a traceback.

lms.djangoapps.instructor_task.api_helper.get_updated_instructor_task(task_id)#

Returns InstructorTask object corresponding to a given task_id.

If the InstructorTask thinks the task is still running, then the task’s result is checked to return an updated state and output.

lms.djangoapps.instructor_task.api_helper.schedule_task(request, task_type, course_key, task_input, task_key, schedule)#

Helper function to schedule a background task.

Reserves the requested task and stores it until the task is ready for execution. We also create an instance of a InstructorTaskSchedule object responsible for maintaining the details of _when_ a task should be executed. Extracts arguments important to the task from the originating server request and stores them as part of the schedule object. Sets the task_status to SCHEDULED to indicate this task will be executed in the future.

Parameters:

  • request (WSGIRequest) – The originating web request associated with this task request.

  • task_type (String) – Text describing the type of task (e.g. ‘bulk_course_email’ or ‘grade_course’)

  • course_key (CourseKey) – The CourseKey of the course-run the task belongs to.

  • task_input (dict) – Task input arguments stores as JSON-serialized dictionary.

  • task_key (String) – Encoded input arguments used during task execution.

  • schedule (DateTime) – DateTime (in UTC) describing when the task should be executed.

lms.djangoapps.instructor_task.api_helper.submit_scheduled_task(schedule)#

Helper function for submitting a scheduled task due for execution to Celery.

lms.djangoapps.instructor_task.api_helper.submit_task(request, task_type, task_class, course_key, task_input, task_key)#

Helper method to submit a task.

Reserves the requested task, based on the course_key, task_type, and task_key, checking to see if the task is already running. The task_input is also passed so that it can be stored in the resulting InstructorTask entry. Arguments are extracted from the request provided by the originating server request. Then the task is submitted to run asynchronously, using the specified task_class and using the task_id constructed for it.

Cannot be inside an atomic block.

AlreadyRunningError is raised if the task is already running.

lms.djangoapps.instructor_task.apps module#

Instructor Task Application Configuration

class lms.djangoapps.instructor_task.apps.InstructorTaskConfig(app_name, app_module)#

Bases: AppConfig

Application Configuration for Instructor Task

name = 'lms.djangoapps.instructor_task'#
ready()#

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

lms.djangoapps.instructor_task.data module#

Public data structures for the instructor_task app.

class lms.djangoapps.instructor_task.data.InstructorTaskTypes(*values)#

Bases: str, Enum

Enum describing the assortment of instructor tasks supported by edx-platform.

BULK_COURSE_EMAIL = 'bulk_course_email'#
COHORT_STUDENTS = 'cohort_students'#
COURSE_SURVEY_REPORT = 'course_survey_report'#
DELETE_PROBLEM_STATE = 'delete_problem_state'#
DETAILED_ENROLLMENT_REPORT = 'detailed_enrollment_report'#
EXEC_SUMMARY_REPORT = 'exec_summary_report'#
EXPORT_ORA2_DATA = 'export_ora2_data'#
EXPORT_ORA2_SUBMISSION_FILES = 'export_ora2_submission_files'#
EXPORT_ORA2_SUMMARY = 'export_ora2_summary'#
GENERATE_ANONYMOUS_IDS_FOR_COURSE = 'generate_anonymous_ids_for_course'#
GENERATE_CERTIFICATES_ALL_STUDENT = 'generate_certificates_all_student'#
GENERATE_CERTIFICATES_CERTAIN_STUDENT = 'generate_certificates_certain_student'#
GENERATE_CERTIFICATES_STUDENT_SET = 'generate_certificates_student_set'#
GRADE_COURSE = 'grade_course'#
GRADE_PROBLEMS = 'grade_problems'#
INACTIVE_ENROLLED_STUDENTS_INFO_CSV = 'inactive_enrolled_students_info_csv'#
MAY_ENROLL_INFO_CSV = 'may_enroll_info_csv'#
OVERRIDE_PROBLEM_SCORE = 'override_problem_score'#
PROBLEM_RESPONSES_CSV = 'problem_responses_csv'#
PROCTORED_EXAM_RESULTS_REPORT = 'proctored_exam_results_report'#
PROFILE_INFO_CSV = 'profile_info_csv'#
REGENERATE_CERTIFICATES_ALL_STUDENT = 'regenerate_certificates_all_student'#
RESCORE_PROBLEM = 'rescore_problem'#
RESCORE_PROBLEM_IF_HIGHER = 'rescore_problem_if_higher'#
RESET_PROBLEM_ATTEMPTS = 'reset_problem_attempts'#
STUDENT_ENROLLMENT_BATCH = 'student_enrollment_batch'#

lms.djangoapps.instructor_task.exceptions module#

Exception classes used by Instructor tasks.

exception lms.djangoapps.instructor_task.exceptions.DuplicateTaskException#

Bases: Exception

Exception indicating that a task already exists or has already completed.

exception lms.djangoapps.instructor_task.exceptions.UpdateProblemModuleStateError#

Bases: Exception

Error signaling a fatal condition while updating problem modules.

Used when the current module cannot be processed and no more modules should be attempted.

lms.djangoapps.instructor_task.models module#

WE’RE USING MIGRATIONS!

If you make changes to this model, be sure to create an appropriate migration file and check it in at the same time as your model changes. To do that,

  1. Go to the edx-platform dir

  2. ./manage.py schemamigration instructor_task –auto description_of_your_change

  3. Add the migration file created in edx-platform/lms/djangoapps/instructor_task/migrations/

ASSUMPTIONS: modules have unique IDs, even across different module_types

class lms.djangoapps.instructor_task.models.DjangoStorageReportStore(storage_class=None, storage_kwargs=None)#

Bases: ReportStore

ReportStore implementation that delegates to django’s storage api.

classmethod from_config(config_name)#

By default, the default file storage specified by the STORAGES[‘default’] setting will be used. To configure the storage used, add a dict in settings with the following fields:

STORAGE_CLASS : The import path of the storage class to use. If
                not set, the STORAGES['default']['BACKEND'] setting will be used.
STORAGE_KWARGS : An optional dict of kwargs to pass to the storage
                 constructor. This can be used to specify a
                 different S3 bucket or root path, for example.

Reference the setting name when calling .from_config.

For a given course_id, return a list of (filename, url) tuples. Calls the url method of the underlying storage backend. Returned urls can be plugged straight into an href

path_to(course_id, filename='', parent_dir='')#

Return the full path to a given file for a given course.

store(course_id, filename, buff, parent_dir='')#

Store the contents of buff in a directory determined by hashing course_id, and name the file filename. buff can be any file-like object, ready to be read from the beginning.

store_rows(course_id, filename, rows, parent_dir='')#

Given a course_id, filename, and rows (each row is an iterable of strings), write the rows to the storage backend in csv format.

class lms.djangoapps.instructor_task.models.InstructorTask(*args, **kwargs)#

Bases: Model

Stores information about background tasks that have been submitted to perform work by an instructor (or course staff). Examples include grading and rescoring.

task_type identifies the kind of task being performed, e.g. rescoring. course_id uses the course run’s unique id to identify the course. task_key stores relevant input arguments encoded into key value for testing to see

if the task is already running (together with task_type and course_id).

task_input stores input arguments as JSON-serialized dict, for reporting purposes.

Examples include url of problem being rescored, id of student if only one student being rescored.

task_id stores the id used by celery for the background task. task_state stores the last known state of the celery task task_output stores the output of the celery task.

Format is a JSON-serialized dict. Content varies by task_type and task_state.

requester stores id of user who submitted the task created stores date that entry was first created updated stores date that entry was last modified

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

certificategenerationhistory_set#

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

In the example:

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

Parent.children is a ReverseManyToOneDescriptor instance.

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

course_id#

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

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

classmethod create(course_id, task_type, task_key, task_input, requester)#

Create an instance of InstructorTask.

static create_output_for_failure(exception, traceback_string)#

Converts failed result information to output format.

Traceback information is truncated or not included if it would result in an output string that would not fit in the database. If the output is still too long, then the exception message is also truncated.

Truncation is indicated by adding “…” to the end of the value.

static create_output_for_revoked()#

Creates standard message to store in output format for revoked tasks.

static create_output_for_success(returned_result)#

Converts successful result to output format.

Raises a ValueError exception if the output is too long.

created#

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

get_next_by_updated(*, field=<django.db.models.fields.DateTimeField: updated>, is_next=True, **kwargs)#
get_previous_by_updated(*, field=<django.db.models.fields.DateTimeField: updated>, is_next=False, **kwargs)#
id#

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

instructortaskschedule#

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

In the example:

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

Place.restaurant is a ReverseOneToOneDescriptor instance.

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

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

In the example:

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

Child.parent is a ForwardManyToOneDescriptor instance.

requester_id#
save_now()#

Writes InstructorTask immediately, ensuring the transaction is committed.

subtasks#

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

task_id#

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

task_input#

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

task_key#

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

task_output#

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

task_state#

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

task_type#

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

updated#

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

class lms.djangoapps.instructor_task.models.InstructorTaskSchedule(*args, **kwargs)#

Bases: TimeStampedModel

A database model to store information about _when_ to execute a scheduled background task.

The primary use case is to allow instructors to schedule their email messages (authored with the bulk course email tool) to be sent at a later date and time.

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

created#

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

get_next_by_created(*, field=<model_utils.fields.AutoCreatedField: created>, is_next=True, **kwargs)#
get_next_by_modified(*, field=<model_utils.fields.AutoLastModifiedField: modified>, is_next=True, **kwargs)#
get_next_by_task_due(*, field=<django.db.models.fields.DateTimeField: task_due>, is_next=True, **kwargs)#
get_previous_by_created(*, field=<model_utils.fields.AutoCreatedField: created>, is_next=False, **kwargs)#
get_previous_by_modified(*, field=<model_utils.fields.AutoLastModifiedField: modified>, is_next=False, **kwargs)#
get_previous_by_task_due(*, field=<django.db.models.fields.DateTimeField: task_due>, is_next=False, **kwargs)#
history = <django.db.models.manager.HistoryManagerFromHistoricalQuerySet object>#
id#

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

modified#

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

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

Save the model instance without creating a historical record.

Make sure you know what you’re doing before using this method.

task#

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

In the example:

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

Restaurant.place is a ForwardOneToOneDescriptor instance.

task_args#

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

task_due#

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

task_id#
class lms.djangoapps.instructor_task.models.ReportStore#

Bases: object

Simple abstraction layer that can fetch and store CSV files for reports download. Should probably refactor later to create a ReportFile object that can simply be appended to for the sake of memory efficiency, rather than passing in the whole dataset. Doing that for now just because it’s simpler.

classmethod from_config(config_name)#

Return one of the ReportStore subclasses depending on django configuration. Look at subclasses for expected configuration.

lms.djangoapps.instructor_task.notifications module#

Notification utilities for instructor tasks.

This module contains functions for sending email notifications about completed instructor tasks (enrollments, grades, certificates, etc.).

lms.djangoapps.instructor_task.notifications.send_enrollment_task_completion_email(course_key: CourseKey, instructor_task: InstructorTask, action: str, task_result: dict) → None#

Send a completion email to the user who initiated the enrollment batch task.

Parameters:

  • course_key (CourseKey) – The course key

  • instructor_task (InstructorTask) – The InstructorTask object

  • action (str) – The action (e.g., ‘enroll’, ‘unenroll’)

  • task_result (dict) – Dictionary containing task completion results with keys: - total_processed: Total number of students processed - successful: Number of successful operations - failed: Number of failed operations

lms.djangoapps.instructor_task.subtasks module#

This module contains celery task functions for handling the management of subtasks.

class lms.djangoapps.instructor_task.subtasks.SubtaskStatus(task_id, attempted=None, succeeded=0, failed=0, skipped=0, retried_nomax=0, retried_withmax=0, state=None)#

Bases: object

Create and return a dict for tracking the status of a subtask.

SubtaskStatus values are:

‘task_id’ : id of subtask. This is used to pass task information across retries. ‘attempted’ : number of attempts – should equal succeeded plus failed ‘succeeded’ : number that succeeded in processing ‘skipped’ : number that were not processed. ‘failed’ : number that failed during processing ‘retried_nomax’ : number of times the subtask has been retried for conditions that

should not have a maximum count applied

‘retried_withmax’number of times the subtask has been retried for conditions that

should have a maximum count applied

‘state’ : celery state of the subtask (e.g. QUEUING, PROGRESS, RETRY, FAILURE, SUCCESS)

Object is not JSON-serializable, so to_dict and from_dict methods are provided so that it can be passed as a serializable argument to tasks (and be reconstituted within such tasks).

In future, we may want to include specific error information indicating the reason for failure. Also, we should count up “not attempted” separately from attempted/failed.

classmethod create(task_id, **options)#

Construct a SubtaskStatus object.

classmethod from_dict(d)#

Construct a SubtaskStatus object from a dict representation.

get_retry_count()#

Returns the number of retries of any kind.

increment(succeeded=0, failed=0, skipped=0, retried_nomax=0, retried_withmax=0, state=None)#

Update the result of a subtask with additional results.

Kwarg arguments are incremented to the existing values. The exception is for state, which if specified is used to override the existing value.

to_dict()#

Output a dict representation of a SubtaskStatus object.

Use for creating a JSON-serializable representation for use by tasks.

lms.djangoapps.instructor_task.subtasks.check_subtask_is_valid(entry_id, current_task_id, new_subtask_status)#

Confirms that the current subtask is known to the InstructorTask and hasn’t already been completed.

Problems can occur when the parent task has been run twice, and results in duplicate subtasks being created for the same InstructorTask entry. This maybe happens when Celery loses its connection to its broker, and any current tasks get requeued.

If a parent task gets requeued, then the same InstructorTask may have a different set of subtasks defined (to do the same thing), so the subtasks from the first queuing would not be known to the InstructorTask. We return an exception in this case.

If a subtask gets requeued, then the first time the subtask runs it should run fine to completion. However, we want to prevent it from running again, so we check here to see what the existing subtask’s status is. If it is complete, we raise an exception. We also take a lock on the task, so that we can detect if another worker has started work but has not yet completed that work. The other worker is allowed to finish, and this raises an exception.

Raises a DuplicateTaskException exception if it’s not a task that should be run.

If this succeeds, it requires that update_subtask_status() is called to release the lock on the task.

lms.djangoapps.instructor_task.subtasks.initialize_subtask_info(entry, action_name, total_num, subtask_id_list)#

Store initial subtask information to InstructorTask object.

The InstructorTask’s “task_output” field is initialized. This is a JSON-serialized dict. Counters for ‘attempted’, ‘succeeded’, ‘failed’, ‘skipped’ keys are initialized to zero, as is the ‘duration_ms’ value. A ‘start_time’ is stored for later duration calculations, and the total number of “things to do” is set, so the user can be told how much needs to be done overall. The action_name is also stored, to help with constructing more readable task_progress messages.

The InstructorTask’s “subtasks” field is also initialized. This is also a JSON-serialized dict. Keys include ‘total’, ‘succeeded’, ‘retried’, ‘failed’, which are counters for the number of subtasks. ‘Total’ is set here to the total number, while the other three are initialized to zero. Once the counters for ‘succeeded’ and ‘failed’ match the ‘total’, the subtasks are done and the InstructorTask’s “status” will be changed to SUCCESS.

The “subtasks” field also contains a ‘status’ key, that contains a dict that stores status information for each subtask. The value for each subtask (keyed by its task_id) is its subtask status, as defined by SubtaskStatus.to_dict().

This information needs to be set up in the InstructorTask before any of the subtasks start running. If not, there is a chance that the subtasks could complete before the parent task is done creating subtasks. Doing so also simplifies the save() here, as it avoids the need for locking.

Monitoring code should assume that if an InstructorTask has subtask information, that it should rely on the status stored in the InstructorTask object, rather than status stored in the corresponding AsyncResult.

lms.djangoapps.instructor_task.subtasks.queue_subtasks_for_query(entry, action_name, create_subtask_fcn, item_querysets, item_fields, items_per_task, total_num_items)#

Generates and queues subtasks to each execute a chunk of “items” generated by a queryset.

Parameters:

  • entry – the InstructorTask object for which subtasks are being queued.

  • action_name – a past-tense verb that can be used for constructing readable status messages.

  • create_subtask_fcn – a function of two arguments that constructs the desired kind of subtask object. Arguments are the list of items to be processed by this subtask, and a SubtaskStatus object reflecting initial status (and containing the subtask’s id).

  • item_querysets – a list of query sets that define the “items” that should be passed to subtasks.

  • item_fields – the fields that should be included in the dict that is returned. These are in addition to the ‘pk’ field.

  • items_per_task – maximum size of chunks to break each query chunk into for use by a subtask.

  • total_num_items – total amount of items that will be put into subtasks

Returns: the task progress as stored in the InstructorTask object.

lms.djangoapps.instructor_task.subtasks.track_memory_usage(metric, course_id)#

Context manager to track how much memory (in bytes) a given process uses. Metrics will look like: ‘course_email.subtask_generation.memory.rss’ or ‘course_email.subtask_generation.memory.vms’.

lms.djangoapps.instructor_task.subtasks.update_subtask_status(entry_id, current_task_id, new_subtask_status, retry_count=0)#

Update the status of the subtask in the parent InstructorTask object tracking its progress.

Because select_for_update is used to lock the InstructorTask object while it is being updated, multiple subtasks updating at the same time may time out while waiting for the lock. The actual update operation is surrounded by a try/except/else that permits the update to be retried if the transaction times out.

The subtask lock acquired in the call to check_subtask_is_valid() is released here, only when the attempting of retries has concluded.

lms.djangoapps.instructor_task.tasks module#

This file contains tasks that are designed to perform background operations on the running state of a course.

At present, these tasks all operate on StudentModule objects in one way or another, so they share a visitor architecture. Each task defines an “update function” that takes a block, a particular StudentModule object, and xblock_instance_args.

A task may optionally specify a “filter function” that takes a query for StudentModule objects, and adds additional filter clauses.

A task also passes through “xblock_instance_args”, that are used to provide information to our code that instantiates xmodule instances.

The task definition then calls the traversal function, passing in the three arguments above, along with the id value for an InstructorTask object. The InstructorTask object contains a ‘task_input’ row which is a JSON-encoded dict containing a problem URL and optionally a student. These are used to set up the initial value of the query for traversing StudentModule objects.

lms.djangoapps.instructor_task.tasks_base module#

Base class for Instructor celery tasks.

class lms.djangoapps.instructor_task.tasks_base.BaseInstructorTask#

Bases: Task

Base task class for use with InstructorTask models.

Permits updating information about task in corresponding InstructorTask for monitoring purposes.

Assumes that the entry_id of the InstructorTask model is the first argument to the task.

The entry_id is the primary key for the InstructorTask entry representing the task. This class updates the entry on success and failure of the task it wraps. It is setting the entry’s value for task_state based on what Celery would set it to once the task returns to Celery: FAILURE if an exception is encountered, and SUCCESS if it returns normally. Other arguments are pass-throughs to perform_module_state_update, and documented there.

abstract = True#

Deprecated attribute abstract here for compatibility.

ignore_result = False#

If enabled the worker won’t store task state and return values for this task. Defaults to the :setting:`task_ignore_result` setting.

on_failure(exc, task_id, args, kwargs, einfo)#

Update InstructorTask object corresponding to this task with info about failure.

Fetches and updates exception and traceback information on failure.

If an exception is raised internal to the task, it is caught by celery and provided here. The information is recorded in the InstructorTask object as a JSON-serialized dict stored in the task_output column. It contains the following keys:

‘exception’: type of exception object ‘message’: error message from exception object ‘traceback’: traceback information (truncated if necessary)

Note that there is no way to record progress made within the task (e.g. attempted, succeeded, etc.) when such failures occur.

on_success(task_progress, task_id, args, kwargs)#

Update InstructorTask object corresponding to this task with info about success.

Updates task_output and task_state. But it shouldn’t actually do anything if the task is only creating subtasks to actually do the work.

Assumes task_progress is a dict containing the task’s result, with the following keys:

‘attempted’: number of attempts made ‘succeeded’: number of attempts that “succeeded” ‘skipped’: number of attempts that “skipped” ‘failed’: number of attempts that “failed” ‘total’: number of possible subtasks to attempt ‘action_name’: user-visible verb to use in status messages. Should be past-tense.

Pass-through of input action_name.

‘duration_ms’: how long the task has (or had) been running.

This is JSON-serialized and stored in the task_output column of the InstructorTask entry.

priority = None#

Default task priority.

rate_limit = None#

None (no rate limit), ‘100/s’ (hundred tasks a second), ‘100/m’ (hundred tasks a minute),`’100/h’` (hundred tasks an hour)

Type:

Rate limit for this task type. Examples

reject_on_worker_lost = None#

Even if acks_late is enabled, the worker will acknowledge tasks when the worker process executing them abruptly exits or is signaled (e.g., :sig:`KILL`/:sig:`INT`, etc).

Setting this to true allows the message to be re-queued instead, so that the task will execute again by the same worker, or another worker.

Warning: Enabling this can cause message loops; make sure you know what you’re doing.

request_stack = <celery.utils.threads._LocalStack object>#

Task request stack, the current request will be the topmost.

serializer = 'json'#

The name of a serializer that are registered with kombu.serialization.registry. Default is ‘json’.

store_errors_even_if_ignored = True#

When enabled errors will be stored even if the task is otherwise configured to ignore results.

track_started = True#

If enabled the task will report its status as ‘started’ when the task is executed by a worker. Disabled by default as the normal behavior is to not report that level of granularity. Tasks are either pending, finished, or waiting to be retried.

Having a ‘started’ status can be useful for when there are long running tasks and there’s a need to report what task is currently running.

The application default can be overridden using the :setting:`task_track_started` setting.

typing = True#

Enable argument checking. You can set this to false if you don’t want the signature to be checked when calling the task. Defaults to app.strict_typing.

lms.djangoapps.instructor_task.views module#

lms.djangoapps.instructor_task.views.get_task_completion_info(instructor_task)#

Construct progress message from progress information in InstructorTask entry.

Returns (boolean, message string) duple, where the boolean indicates whether the task completed without incident. (It is possible for a task to attempt many sub-tasks, such as rescoring many students’ problem responses, and while the task runs to completion, some of the students’ responses could not be rescored.)

Used for providing messages to instructor_task_status(), as well as external calls for providing course task submission history information.

lms.djangoapps.instructor_task.views.instructor_task_status(request)#

View method that returns the status of a course-related task or tasks.

Status is returned as a JSON-serialized dict, wrapped as the content of a HTTPResponse.

The task_id can be specified to this view in one of two ways:

  • by making a request containing ‘task_id’ as a parameter with a single value Returns a dict containing status information for the specified task_id

  • by making a request containing ‘task_ids’ as a parameter, with a list of task_id values. Returns a dict of dicts, with the task_id as key, and the corresponding dict containing status information for the specified task_id

    Task_id values that are unrecognized are skipped.

The dict with status information for a task contains the following keys:
‘message’: on complete tasks, status message reporting on final progress,

or providing exception message if failed. For tasks in progress, indicates the current progress.

‘succeeded’: on complete tasks or tasks in progress, boolean value indicates if the

task outcome was successful: did it achieve what it set out to do. This is in contrast with a successful task_state, which indicates that the task merely completed.

‘task_id’: id assigned by LMS and used by celery. ‘task_state’: state of task as stored in celery’s result store. ‘in_progress’: boolean indicating if task is still running. ‘task_progress’: dict containing progress information. This includes:

‘attempted’: number of attempts made ‘succeeded’: number of attempts that “succeeded” ‘total’: number of possible subtasks to attempt ‘action_name’: user-visible verb to use in status messages. Should be past-tense. ‘duration_ms’: how long the task has (or had) been running. ‘exception’: name of exception class raised in failed tasks. ‘message’: returned for failed and revoked tasks. ‘traceback’: optional, returned if task failed and produced a traceback.

Module contents#

Contents