django-user-tasks#
django-user-tasks is a reusable Django application for managing user-triggered asynchronous tasks. It provides a status page for each such task, which includes a meaningful progress indicator if the task is currently being executed and provides any appropriate text and/or links for output once the task is complete.
In Open edX, such tasks include operations such as exporting or importing a course, sending an email to all the students in a course, uploading a video, and other tasks which often take too long to perform during a single web request (as outlined in OEP-3). However, this has been written with the intention of being useful in a variety of Django projects outside the Open edX platform as well.
Note that this library was created as a consolidation of lessons learned from implementing such tasks in various parts of the Open edX code base. They don’t yet all use this library, but the plan is to over time refactor many of them to do so.
Overview#
django-user-tasks is currently a wrapper for Celery (although the hope is
that it could also be extended to also support channels and other
asynchronous task queues). By extending the provided UserTask
class (or
adding UserTaskMixin
to an existing Task subclass) and providing a
user_id
task argument, the task’s status is stored in a database table
separate from the Celery broker and result store. This UserTaskStatus
model allows for full database queries of the tasks that users are most likely
to care about while not imposing any restrictions on the Celery configuration
most appropriate for the site’s overall needs for asynchronous task
processing.
Most of the status updating is handled automatically via Celery’s signals mechanism, but it can be enhanced by:
Overriding the
UserTaskMixin
methods such asgenerate_name
andcalculate_total_steps
for particular types of tasksCalling some of the
UserTaskStatus
methods likeincrement_completed_steps
andset_state
from the task implementationSaving task output as instances of the
UserTaskArtifact
model
Documentation#
The full documentation is at https://django-user-tasks.readthedocs.org.
License#
The code in this repository is licensed under the Apache Software License 2.0 unless otherwise noted.
Please see LICENSE.txt
for details.
How To Contribute#
Contributions are very welcome.
Please read How To Contribute for details.
Reporting Security Issues#
Please do not report security issues in public. Please email security@openedx.org.
Getting Help#
Have a question about this repository, or about Open edX in general? Please refer to this list of resources if you need any assistance.
- GET /artifacts/#
List the generated task artifacts which are accessible to the requesting user.
- Query Parameters:
page (integer) – The page number of the resulting artifact list to retrieve.
- Status Codes:
200 OK – A list of task artifacts.
403 Forbidden – The requesting user lacks permission to view any task artifacts.
- Response JSON Object:
[].created (string) – Creation time of the artifact
[].file (string) – URL of a file containing artifact output
[].modified (string) – Last modified time of the artifact
[].name (string) – A name for this artifact to distinguish it from others for the same task
[].status (string) – URL of status information for the task which created this artifact
[].text (string) – Text content of the artifact
[].url (string) – URL where the artifact can be viewed
- GET /artifacts/{uuid}/#
Get information about the specified task artifact.
- Parameters:
uuid (string) – The external ID of a task artifact.
- Status Codes:
200 OK – Information about a task artifact.
404 Not Found – There is no such task artifact (or the user lacks permission to view it).
- Response JSON Object:
created (string) – Creation time of the artifact
file (string) – URL of a file containing artifact output
modified (string) – Last modified time of the artifact
name (string) – A name for this artifact to distinguish it from others for the same task
status (string) – URL of status information for the task which created this artifact
text (string) – Text content of the artifact
url (string) – URL where the artifact can be viewed
- GET /tasks/#
List the status of user-triggered tasks which are accessible to the requesting user.
- Query Parameters:
page (integer) – The page number of the resulting task status list to retrieve.
- Status Codes:
200 OK – A list of task status records.
403 Forbidden – The requesting user lacks permission to view any task status records.
- Response JSON Object:
[].artifacts[] (string) –
[].attempts (integer) – How many times has execution been attempted?
[].completed_steps (integer) – Number of task execution stages which have already finished
[].created (string) – Creation time of the task status record
[].modified (string) – Last modified time of the task status record
[].name (string) – A name for this task which the triggering user will understand
[].state (string) – English name of the state the task is currently in
[].state_text (string) – Name in the user’s language of the state the task is currently in
[].total_steps (integer) – Total number of execution stages needed to complete the task
- DELETE /tasks/{uuid}/#
Delete the specified task status record and any associated artifacts.
- Parameters:
uuid (string) – The external ID of a task status record.
- Status Codes:
204 No Content – Confirmation that the task was successfully deleted.
403 Forbidden – The user is allowed to view this status record, but lacks permission to delete it.
404 Not Found – There is no such task status record (or the user lacks permission to view it).
- GET /tasks/{uuid}/#
Get information about the specified task status record.
- Parameters:
uuid (string) – The external ID of a task status record.
- Status Codes:
200 OK – Information about the status of a user-triggered task.
404 Not Found – There is no such task status record (or the user lacks permission to view it).
- Response JSON Object:
artifacts[] (string) –
attempts (integer) – How many times has execution been attempted?
completed_steps (integer) – Number of task execution stages which have already finished
created (string) – Creation time of the task status record
modified (string) – Last modified time of the task status record
name (string) – A name for this task which the triggering user will understand
state (string) – English name of the state the task is currently in
state_text (string) – Name in the user’s language of the state the task is currently in
total_steps (integer) – Total number of execution stages needed to complete the task
- POST /tasks/{uuid}/cancel/#
Cancel the task associated with the specified status record.
Revoke the task if it has not yet been started, instruct it to halt at the next convenient stopping point if already running, or do nothing if it has already stopped running.
- Parameters:
uuid (string) – The external ID of a task status record.
- Status Codes:
201 Created – Confirmation that cancellation of the task is being processed.
403 Forbidden – The user is allowed to view this status record, but lacks permission to cancel it.
404 Not Found – There is no such task status record (or the user lacks permission to view it).