Welcome to the Devilry documentation¶

Special terms and concepts¶

Devilry has some special terms and concepts. The most important (that cause most confusion) is:

• Term: A range of time. Typically a semester or a year.
• Examiner: Someone that provides feedback.
• Group: Students are always in a (project) group even when they work alone on an assignment.

More details about these and more terms and concepts follows below.

When does Devilry send email?¶

Whenever a student makes a delivery, and whenever they get a new feedback.

How to test email sending (for system admins)¶

Go to the frontpage, select the Superuser role, select Users, select a user and click Send a test-email to USERNAME in the upper right corner.

How it works¶

Project groups are created on a per assignment basis. Features:

• Any member of the group can make deliveries on behalf of the group.
• Any feedback given to the project group is for all group members. If you are supposed to get individual feedback, you should not be in a project group.
• When you join a group, you get any deliveries and feedback made by the group before joining, and they get any deliveries and feedback you may have had when joining the group.
• When you leave a group, you do not loose any deliveries and feedback. You even keep deliveries and feedback made before you joined the group.

Invite other students to join your group¶

If your course administrator have enabled collaboration, you can invite other students to join your group as follows:

1. Log in to Devilry.
2. Select the Student role on the frontpage.
3. Select the assignment.
4. Select Project group in the list on the left.
5. It will say Invite someone to join your group? at the top of the page. Under you can select the student you want to invite to your group, and send an invite. Other students will get their invite via email, and they can accept or decline the invite. You can delete an unanswered invite. If any, your group members will be in the list Project group members at the bottom of the page.

Leave a group / kick a member¶

You need to ask a course administrator if you want to leave a group or kick a group member. Leaving a group or kicking a member is perfectly safe. Any member leaving a group is simply moved into a complete copy of the group including all deliveries and feedback. The only difference is that the original group gets one less member, and the new group will only have one member.

Getting started¶

Getting started guide for examiners¶

Note

To avoid confusion when reading this guide, please read Common concepts, at least the Group, Candidate and Student section.

Note

This guide is under construction. Please contact devilry-support@ifi.uio.no if you have questions of any kind related to Devilry.

Choose the examiner role¶

After successful login you need to choose Examiner from the list of available roles.

Select an assignment¶

On the examiner dashboard, assignments where you are examiners are listed. To start correcting, you must choose the spesific assignment in which you want to work with. The list are ordered by the time the assignments where published in descending order. This ensure that your latest assignment are listed on top.

Select the group to correct¶

After the assignment is choosen you are redirected to a view that list all groups on the assignment.

The list may be filtered to show a more fine grained selection:

Waiting for feedback

Shows the assignment groups that have at least one valid delivery and are waiting for feedback to be provided by the examiner.

Waiting for deliveries

Shows the assignment groups that have not provided a valid delivery yet.

Corrected

Shows the assignment groups that are corrected. Be aware that Corrected will list both failed and passed groups as long as they are corrected.

All

Shows every assignment group on the assignment where yourself are the assigned examiner. This is the default filter upon entering the view.

To start correcting you would normally filter with the Waiting for feedback option. The Write feedback button on the group item in the list will take you directly to the latest delivery provided by the group. see Add feedback to the delivery for further details.

If you need access to older deliveries provided by the group you must click on the group name header in the list item which redirect you a detailed view for that assignment. More information on this view in Correct an earlier delivery

Add feedback to the delivery¶

Upon entering the delivery you will need to click the Provide feedback button to start giving feedback.

Provide Feedback¶

This view may vary depending on the grading system configured for the assignment. The picture show a simple points system with a form to provide the number points achieved.

Every grading system features the ability to provide a feedback text in addition to the grade information. Click inside the textbox and a WYSIWYG Markdown editor will be shown. Just type in the feedback and push the Publish button to publish the feedback without examine a preview. If you lack experience with Markdown you would probably want to click the Preview button to be able to secure that the feedback appear as supposed.

Feedback drafts and history¶

You may save you work for later by clicking the Save Draft button

Correct the next delivery¶

When there is multiple groups Waiting for feedback you can loop through each group by clicking the arrow button in the upper right corner of the view.

Correct an earlier delivery¶

When choosing the spesific group every delivery attempts will be listed categorised by the their respective deadlines. This makes it possible to correct a delivery that is not the latest one.

How to examine in bulk or correct non electronic deliveries¶

Note

To avoid total confusion when reading this guide, please read Common concepts, at least the Group, Candidate and Student-section.

Introduction¶

This is a guide for examiners who want to give the same feedback to multiple groups at once and for examiners giving feedback to assignments where Devilry is only used to register results(not for deliveries).

Choose the examiner role¶

It should be one of the available roles on your frontpage.

Select an assignment¶

On the examiner dashboard, assignments where you are examiners are listed ordered by publishing time in descending order. Choose an assignment from this list to get start giving feedback on that assignment.

Group overview¶

When you enter the examiner interfance, you will see an overview of all groups on that assignment. Choose one or more groups and click Give feedback to selected. A window containing the grade editor is shown. Click the Help-button in the lower left corner of the grade editor for more help.

Note

You can right-click anywhere in the group overview for quick access to everything in the toolbar.

Other examiner guides¶

How to correct several groups at once¶

Note

To avoid confusion when reading this guide, please read Common concepts, at least the Group, Candidate and Student-section.

Introduction¶

This guide show you how to edit feedback for a selection of groups. To get to the view described here you must first choose the examiner role in the Devilry frontpage and then choose an assignment.

Editing of multiple groups is easy and straightforward. Activate the checkboxes next to the group of interest to add it to your selection. If you want to choose all groups within the active filter you may click Select All button to speed up the process. When you have created your selection click the Write feedback button to start providing feedback.

Provide feedback¶

The groups that you selected are listed after the Edit feedback for: text, please make sure that it is complete and correct before you take further actions. Provide your feedback. Click Preview button to get a glimpse on how your feedback will look when completely rendered. Be aware that Preview will save your feedback draft on each group. You will be able to come back and edit further in the next step.

If you want to publish your work right away just click Publish.

Manage deadlines — for Examiners¶

Add a deadline¶

When an assignment is created, an initial deadline is set. You can not change this deadline, however you can extend the deadline by creating a new deadline. You usually create deadlines for the following reasons:

A student gets a failing grade¶

If you want to give the student a change to get a new attempt Devilry will ask you (when you publish a failing feedback) if you wish to give the group a new deadline.

Move a deadline¶

Currently, examiners can not move deadlines. This is coming along with an update of the examiner UI. For now, you have to ask an administrator if you need to move a deadline.

How to add feedback to a student without deliveries¶

Note

This guide is a supplement to Getting started guide for examiners.

Choose the examiner role¶

It should be one of the available roles on your frontpage.

Select an assignment¶

On the examiner dashboard, assignments where you are examiners are listed ordered by publishing time in descending order. Choose an assignment from this list to get start giving feedback on that assignment.

Select a group without any deliveries¶

Select a group that waiting for feedback, but does not have any deliveries, as illustrated in the figure below:

Click the “add non-electronic delivery” button¶

If the group: - Has no deliveries. - Is waiting for feedback (their last deadline has expired).

You will see a orange warning-box like the one in this illustration:

Click the add non-electronic delivery button, and follow the instructions on the next page.

Devilry flavoured Markdown¶

When you write feedback to your students, you use the Markdown text formatting language.

With Markdown, you to write using an easy-to-read, easy-to-write plain text format, and let someone else (Devilry) worry about how the results will look. This makes it possible to write feedback text that Devilry can optimize for anything from smartphones to large desktop displays.

Basics¶

Paragraphs¶

Paragraphs are just one or more lines of consecutive text followed by one or more blank lines:

Maecenas faucibus mollis interdum. Vestibulum id ligula porta felis euismod
semper. Vestibulum id ligula porta felis euismod semper. Aenean lacinia
bibendum nulla sed consectetur.

Donec id elit non mi porta gravida at eget metus. Vestibulum id ligula
porta felis euismod semper. Praesent commodo cursus magna, vel scelerisque
nisl consectetur et.

Headings¶

# Largest heading
## Second largest heading
...
##### Very small heading

Text styles¶

*Italic text*
**Bold text**

Links¶

Check out [http://devilry.org](The devilry website).

Lists¶

Unordered lists (bullet lists):

* This
* is
* a
* test

Ordered lists (numbered lists):

1. Item one
2. Item two
3. Item three

Blockquotes¶

As stated on the first page of the 101 guide:

> You have to learn to walk before you can learn how to run

Advanced¶

Escape Markdown characters¶

If you want to use a special Markdown character in your document (such as displaying literal asterisks), you can escape the character with a backslash. Markdown will ignore the character directly after a backslash. Example:

This is how the \_ (underscore) and \* asterisks characters look.

LaTeX Math¶

Devilry Markdown supports LaTeX math through the MathJAX library/renderer. Examples:

A simple example:
$mathblock$
^3/_7
$/mathblock$

The Lorenz Equations:
$mathblock$
\begin{aligned}
\dot{x} & = \sigma(y-x) \\\\
\dot{y} & = \rho x - y - xz \\\\
\dot{z} & = -\beta z + xy
\end{aligned}
$/mathblock$

You have to escape special Markdown characters such as \, which is why we have \\\\ at the end of our lines in the example above instead of just \\.

Code blocks¶

You can easily show syntax highlighted code blocks:

Java code:
``` java
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello world");
    }
}
```

Python code:
``` python
if __name__ == "__main__":
    print "Hello world"
```

C code:
``` c
#include<stdio.h>
int main() {
    printf("Hello World");
    return 0;
}
```

C++ code:
``` c++
#include <iostream>
int main() {
    std::cout << "Hello World!";
    return 0;
}
```

HTML example:
``` html
<html>
    <body>
        <h1>Hello world</h1>
    </body>
</html>
```

CSS example:
``` css
body {
    background-color: pink;
    color: green;
    font-size: 80px;
}
```

Any code:
```
for x in 1 through 3
    show x
```

Devilry supports all languages supported by Pygments.

Frequently asked questions¶

What can an examiner do?¶

Examiners can basically do anything non-destructive with groups (see Group, Candidate and Student) that they have been assigned to:

• View all feedback for the groups.
• Add new deadlines to their groups.
• Give feedback.
• Change feedback. Each change to the published feedback is logged, and the students can view all published feedback.

Examiners can not:

• Delete groups.
• Add new groups.
• Add or remove students to groups.
• Move deadlines. This is a missing feature, which will be implemented in a future release. It will be safe becuase students will remain protected because of logging of all changes. Moving deadlines is already implemented for administrators.
• Remove deadlines from groups. We will probably allow examiners to remove deadlines without deliveries when we start allowing them to move deadlines.

Who this guide is for¶

A subject is, as explained in the common concepts guide, typically a course. This means that this guide is for administrators managing a course or a term (semester) within a course. If you have orange background color in your header, you are using the user interface for the Subjectadmin role.

The responibilities of a Subjectadmin¶

A Subjectadmin manage one or more Subject (course), and/or Term (semester, year, ...). They set up assignments, organize students into Groups, and assignment Examiners to give feedback to students.

Commmon tasks¶

Overview of the deadline view¶

The image below is a typical deadline overview. Each of the red-marked areas is explained below the image.

Hard VS soft deadlines¶

Soft or hard deadlines is configured on the left hand side in the assignment overview under the Deadline handling heading. Use the More info button to get detailed information about soft and hard deadlines.

What about examiners?¶

Examiners can add deadlines. It is a natural part of their workflow. Whenever they fail a student, they are asked to do one of the following:

• Leave the student with a failing grade.
• Give them another chance — create a new deadline.

Concepts and features¶

Devilry is designed with cooperative deliveries in mind.

• Students are always in a group even when they work alone.
• Course admins can safely create and split up project groups at any time.
• You can enable students to create project groups on their own.
• Groups are created and managed per assignment. This means that changing a group on one assignment does not affect that group on another assignment. You can copy groups from another assignment when you create a new assignment.
• Students can be organized in groups even after they have made deliveries and been given feedback. They their respective groups are simply merged into a single group with all deliveries and feedback. The last feedback (if any) is made the active feedback.

How to enable students to create project groups on their own¶

If you want to allow students to form project groups on their own, you have to enable this option on the assignment:

1. Go to the overview page for an assignment where you have administrator rights.
2. Click any of the edit buttons in the sidebar to your left, except the edit button for Grading system.
3. Edit the options in the Allow students to form project groups section.

How to manually create a project group¶

1. Open the students overview on the relevant assignment.
2. Select two or more groups/students.
3. Select Create project group.

Exactly what this means is explained when you click Create project group, and you have to confirm before the group is created. In short,

How to remove a student from a group¶

Students can not leave groups on their own (yet). So an admin has to manage that:

1. Open the students overview on the relevant assignment.
2. Select the group.
3. Click the red minus button on the right hand side of the student you wish to remove from the group.

This will do the following:

• Create a copy of the group with all deliveries and feedback, even deliveries made by other students before the student you are removing joined the group.
• Add the student you are removing to the copy of the original group.

How to give feedback to students when you are Subjectadmin¶

Starting with Devilry 1.2.1 it is no longer possible to give feedback using the Subjectadmin role. You have to make yourself examiner.

How to make yourself examiner¶

The easiest way of making yourself examiner is to make yourself examiner when creating a new assignment. If you are one of many examiners, you will have to make sure you are tagged appropriately. The Create new assignment wizard helps you with this when you get to that step.

The other way of making yourself examiner is to do it manually after the assignment has been created. Select an assignment, and select the Students-link. The see the help-column for more help.

How to make others examiner¶

This is basically the same as the previous section. Just choose other users than yourself.

What do examiners have permission to do¶

See What can an examiner do?.

Quickstart¶

We have an interractive guide for this on your right-hand side on the Subjectadmin frontpage (see Finding the Subjectadmin frontpage). Select the guide, and follow its instructions.

How the qualified for final exams system works¶

You select the students that qualify for final exams using one of the provided plugins. Nodeadmins, or automatic exporters, read these lists to determine who can participate in the final exams.

Students can see if they are qualified for exams or not, but they can not se why they are qualified (they can not see what plugin was used, and with what settings). You should use the course website, or other approprite channels to inform your students about the requirements for final exams.

Changing or retracting¶

You can retract or change a saved qualified for final exams-status.

To change a status, simply use the button at the bottom of the box at the top of the page showing a status.

No plugin fits my needs!¶

Contact the Devilry developers and we will try to help you.

The responibilities of a Nodeadmin¶

A Nodeadmin manage one or more Node. They typically have responsibility for an entire department or organizational unit, where a node represents a department/organizational unit.

Finding the Nodeadmin frontpage¶

The Nodeadmin frontpage is the page that you navigate to when you select the Node administrator role (may be something like Department administrator in your local dialect), from the Devilry frontpage. The button is orange.

Please read¶

The guide for subject/course admins, to know how they interract with the Qualified for final exams system.

Backup database and files¶

BACKUP. YOUR. DATABASE. AND. FILES.

Update devilry¶

Follow the Update guide, and set the version in requirements.txt to:

devilry==2.0.3

Backup database and files¶

BACKUP. YOUR. DATABASE. AND. FILES.

Update devilry¶

Follow the Update guide, and set the version in requirements.txt to:

devilry==2.0.4

Backup database and files¶

BACKUP. YOUR. DATABASE. AND. FILES.

Update devilry¶

This is the first release using the new deployment/production setup. Please follow the Getting started guide.

Check out from GIT¶

If you plan to develop devilry, you should fork the devilry-django repo, changes to your own repo and request inclusion to the master repo using github pull requests. If you are just trying out Devilry, use:

$ git clone https://github.com/devilry/devilry-django.git

The master branch, which git checks out by default, is usually the latest semi-stable development version. The latest stable version is in the latest-stable branch.

Install dependencies/requirements¶

$ sudo apt-get install build-essential python-dev python-virtualenv libncurses5-dev virtualenvwrapper libxslt1-dev libxml2 libxml2-dev zlib1g-dev

$ mkvirtualenv devilry-django
$ pip install -r requirements/development.txt

Create a database¶

We have several alternatives for setting up a demo database. They all use Fabric tasks. See Fabric.

First, make sure you are in the devilry-django virtualenv:

$ workon devilry-django

You can create a fairly full featured demo database with:

$ fab autodb

... or you can create a much more minimalistic demo database with:

$ fab demodb

... or you can create an empty database with:

$ fab reset_db

Note: Creating the testdata with autodb takes a lot of time, but you can start using the server as soon as the users have been created (one of the first things the script does).

Run the Django development server¶

First, make sure you are in the devilry-django virtualenv:

$ workon devilry-django

Start the Django development server with:

$ python manage.py runserver

Go to http://localhost:8000/ and log in as a superuser using:

user: grandma
password: test

Or as a user which is student, examiner and admin using:

user: thor
password: test

Note: All users have password==test, and you can see all users in the superadmin interface. See the demo page on the wiki for more info about the demo database, including recommended test users for each role.

Fabric¶

We use Fabric to simplify common tasks. Fabric simply runs the requested @task decorated functions in fabfile.py.

fabfile.py is very straigt forward to read if you wonder what the tasks actually do. The fabric.api.local(...) function runs an executable on the local machine.

When to use¶

Use this for end-to-end tests and tests where you really need real data. Always try to mock objects instead of creating real data unless you are actually testing something that needs real data. See Mocking tests.

Howto¶

Each class in the core has a wrapper class in devilry.project.develop.testhelpers.corebuilder that makes it easy to perform operations that we need to setup tests. We call these wrappers builders, and they are all prefixed with the name of their corresponding core model and suffixed with Builder.

Using the builders is very easy:

from devilry.project.develop.testhelpers.corebuilder import NodeBuilder
duck1010builder = NodeBuilder('duckuniversity').add_subject('duck1010')
assert(duck1010builder.subject == Subject.objects.get(short_name='duck1010'))

They can all easily be updated with new attributes:

duck1010builder.update(long_name='DUCK1010 - Programming')
assert(duck1010builder.subject.long_name == 'DUCK1010 - Programming')

And they have sane defaults optimized for testing, so you can easily create a deeply nested core object. This creates the duck1010-subject with an active period that started 3 months ago and ends in 3 months, with a single assignment (week1), with a single group, with deadline one week from now with a single helloworld.txt delivery:

from devilry.project.develop.testhelpers.corebuilder import NodeBuilder
from devilry.project.develop.testhelpers.corebuilder import UserBuilder
peterpan = UserBuilder(username='peterpan')
helloworld_filemetabuilder = NodeBuilder('ducku')\
    .add_subject('duck1010')\
    .add_6month_active_period('current')\
    .add_assignment('week1')\
    .add_group(students=[peterpan.user])\
    .add_deadline_in_x_weeks(weeks=1)\
    .add_delivery()\
    .add_filemeta(filename='helloworld.txt', data='Hello world')

Since we often need to add a single subject or a single active period, we have shortcuts for that:

from devilry.project.develop.testhelpers.corebuilder import SubjectBuilder
from devilry.project.develop.testhelpers.corebuilder import PeriodBuilder
duck1010_builder = SubjectBuilder.quickadd_ducku_duck1010()
currentperiod_builder = PeriodBuilder.quickadd_ducku_duck1010_active()

Magic and defaults¶

The builders have very little magic, but they have some defaults that make sense when testing:

• long_name is set to short_name when it is not specified explicitly.
• All BaseNodes (the models with short and long name) takes the short_name as the first argument and the long_name as the second argument.
• Time of delivery (for DeliveryBuilder and DealdineBuilder.add_delivery()) default to now.
• Default publishing_time for assignments is now.
• UserBuilder defaults to setting email to <username>@example.com.

These defaults are all handled in the constructor of their builder-class. All the defaults can be overridden by specifying a value for them.

Reload from DB¶

You often need to create an object that is changed by the code you are testing, and then check that the change has made it to the database. All our builders implement ReloadableDbBuilderInterface which includes reload_from_db().

ReloadableDbBuilderInterface¶

class devilry.project.develop.testhelpers.corebuilder.ReloadableDbBuilderInterface¶

All the builders implement this interface.

update(**attributes)¶

Update the object wrapped by the builder with the given attributes. Saves the object, and reloads it from the database.

reload_from_db(**attributes)¶

Reloads the object wrapped by the builder from the database. Perfect when you create an object that is changed by the code you are testing, and you want to check that the change has made it to the database.

UserBuilder¶

class devilry.project.develop.testhelpers.corebuilder.UserBuilder¶

Creates a User object for testing. Also creates the DevilryUserProfile, and methods for editing both the User and the profile.

__init__(username, full_name=None, email=None)¶

Creates a new User with password set to test, and the devilry.apps.core.models.DevilryUserProfile created.

Parameters:	username – The username of the new user. full_name – Optional full_name. Defaults to None. email – Optional email. Defaults to <username>@example.com.

update(**attributes)¶

Update the User with the given attributes. Reloads the object from the database.

update_profile(**attributes)¶

Update the devilry.apps.core.models.DevilryUserProfile with the given attributes. Reloads the object from the database.

NodeBuilder¶

class devilry.project.develop.testhelpers.corebuilder.NodeBuilder¶

node¶

The Node wrapped by this builder.

__init__(short_name, long_name=None, **kwargs)¶

Creates a new Node with the given attributes.

Parameters:	short_name – The short_name of the Node. long_name – The long_name of the Node. Defaults to short_name if None. kwargs – Other arguments for the Node constructor.

add_node(*args, **kwargs)¶

Adds a childnode to the node. args and kwargs are forwarded to NodeBuilder with kwargs['parentnode'] set to this node.

Return type:	NodeBuilder.

add_subject(*args, **kwargs)¶

Adds a subject to the node. args and kwargs are forwarded to SubjectBuilder with kwargs['parentnode'] set to this node.

Return type:	SubjectBuilder.

SubjectBuilder¶

class devilry.project.develop.testhelpers.corebuilder.SubjectBuilder¶

subject¶

The Subject wrapped by this builder.

__init__(short_name, long_name=None, **kwargs)¶

Creates a new Subject with the given attributes.

Parameters:	short_name – The short_name of the Subject. long_name – The long_name of the Subject. Defaults to short_name if None. kwargs – Other arguments for the Subject constructor.

classmethod quickadd_ducku_duck1010()¶

When we need just a single subject, we use this shortcut method instead of writing:

NodeBuilder('ducku').add_subject('duck1010')

This is not just to save a couple of letters, but also to promote a common setup for simple tests.

add_period(*args, **kwargs)¶

Adds a period to the subject. args and kwargs are forwarded to PeriodBuilder with kwargs['parentnode'] set to this subject.

Return type:	PeriodBuilder.

add_6month_active_period(*args, **kwargs)¶

Shortcut for adding add_period() with start_time 3*30 days ago, and end_time in 3*30 days. args and kwargs is forwarded to add_period, but with start_time and end_time set in kwargs.

If no short_name is provided, it defaults to active.

Return type:	PeriodBuilder.

add_6month_lastyear_period(*args, **kwargs)¶

Shortcut for adding add_period() with start_time 365-30*3 days ago, and end_time 365+3*30 days ago. args and kwargs is forwarded to add_period, but with start_time and end_time set in kwargs.

If no short_name is provided, it defaults to lastyear. :rtype: PeriodBuilder.

add_6month_nextyear_period(*args, **kwargs)¶

Shortcut for adding add_period() with start_time in 365-30*3 days, and end_time in 365+3*30 days. args and kwargs is forwarded to add_period, but with start_time and end_time set in kwargs.

If no short_name is provided, it defaults to nextyear.

Return type:	PeriodBuilder.

PeriodBuilder¶

class devilry.project.develop.testhelpers.corebuilder.PeriodBuilder¶

period¶

The Period wrapped by this builder.

__init__(short_name, long_name=None, **kwargs)¶

Creates a new Period with the given attributes.

Parameters:	short_name – The short_name of the Period. long_name – The long_name of the Period. Defaults to short_name if None. kwargs – Other arguments for the Period constructor.

add_assignment(*args, **kwargs)¶

Adds an assignment to the period. args and kwargs are forwarded to AssignmentBuilder with kwargs['parentnode'] set to this period.

Return type:	AssignmentBuilder.

classmethod quickadd_ducku_duck1010_active()¶

When we need just a single active period, we use this shortcut method instead of writing:

NodeBuilder('ducku').add_subject('duck1010').add_6month_active_period('current')

This is not just to save a couple of letters, but also to promote a common setup for simple tests.

AssignmentBuilder¶

class devilry.project.develop.testhelpers.corebuilder.AssignmentBuilder¶

assignment¶

The Assignment wrapped by this builder.

__init__(short_name, long_name=None, **kwargs)¶

Creates a new Assignment with the given attributes.

Parameters:	short_name – The short_name of the Assignment. long_name – The long_name of the Assignment. Defaults to short_name if None. publishing_time – The publishing_time of the Assignment. Defaults to now. kwargs – Other arguments for the Assignment constructor.

add_group(*args, **kwargs)¶

Adds an assignment group to the period. args and kwargs are forwarded to AssignmentGroupBuilder with kwargs['parentnode'] set to this assignment.

Return type:	AssignmentGroupBuilder.

AssignmentGroupBuilder¶

class devilry.project.develop.testhelpers.corebuilder.AssignmentGroupBuilder¶

assignment_group¶

The AssignmentGroup wrapped by this builder.

__init__(students=, []candidates=, []examiners=, []**kwargs)¶

Creates a new AssignmentGroup with the given attributes.

Parameters:	students – Forwarded to add_students(). candidates – Forwarded to add_candidates(). examiners – Forwarded to add_examiners(). kwargs – Arguments for the AssignmentGroup constructor.

add_students(*users)¶

Add the given users as candidates without a candidate ID on this assignment group.

Returns:	self (to enable us to nest the method call).

add_examiners(*users)¶

Add the given users as examiners on this assignment group.

Returns:	self (to enable us to nest the method call).

add_students(*candidates)

Add the given candidates to this assignment group.

Parameters:	candidates – devilry.apps.core.models.Candidate objects.
Returns:	self (to enable us to nest the method call).

add_deadline(*args, **kwargs)¶

Adds an deadline to the assignment. args and kwargs are forwarded to DeadlineBuilder with kwargs['assignment_group'] set to this assignment_group.

Return type:	AssignmentGroupBuilder.

add_deadline_in_x_weeks(weeks, *args, **kwargs)¶

Calls add_deadline() with kwargs[deadline] set weeks weeks in the future.

Return type:	AssignmentGroupBuilder.

add_deadline_x_weeks_ago(weeks, *args, **kwargs)¶

Calls add_deadline() with kwargs[deadline] set weeks weeks in the past.

Return type:	DeadlineBuilder.

DeadlineBuilder¶

class devilry.project.develop.testhelpers.corebuilder.DeadlineBuilder¶

deadline¶

The Deadline wrapped by this builder.

__init__(**kwargs)¶

Creates a new AssignmentGroup with the given attributes.

Parameters:	kwargs – Arguments for the Deadline constructor.

add_delivery(**kwargs)¶

Adds a delivery to the deadline. args and kwargs are forwarded to DeliveryBuilder with kwargs['deadline'] set to this deadline and kwargs['successful'] defaulting to True.

Parameters:	kwargs – Extra kwargs for the DeliveryBuilder constructor.
Return type:	DeliveryBuilder.

add_delivery_after_deadline(timedeltaobject, **kwargs)¶

Add a delivery timedeltaobject time after this deadline expires.

Shortcut that calls add_delivery() with kwargs['time_of_delivery'] set to deadline.deadline + timedeltaobject.

Example - add delivery 3 weeks and 2 hours after deadline:

from datetime import datetime, timedelta
deadlinebuilder = DeadlineBuilder(deadline=datetime(2010, 1, 1))
deadlinebuilder.add_delivery_after_deadline(timedelta(weeks=3, hours=2))

Parameters:	kwargs – Extra kwargs for the DeliveryBuilder constructor.
Return type:	DeliveryBuilder.

add_delivery_before_deadline(timedeltaobject, **kwargs)¶

Add a delivery timedeltaobject time before this deadline expires.

Shortcut that calls add_delivery() with kwargs['time_of_delivery'] set to deadline.deadline + timedeltaobject.

Example - add delivery 5 hours before deadline:

from datetime import datetime, timedelta
deadlinebuilder = DeadlineBuilder(deadline=datetime(2010, 1, 1))
deadlinebuilder.add_delivery_before_deadline(timedelta(hours=5))

Parameters:	kwargs – Extra kwargs for the DeliveryBuilder constructor.
Return type:	DeliveryBuilder.

add_delivery_x_hours_after_deadline(timedeltaobject, **kwargs)¶

Add a delivery hours hours after this deadline expires.

Shortcut that calls add_delivery_after_deadline() with timedeltaobject set to timedelta(hours=hours).

Parameters:	hours – Number of hours. kwargs – Extra kwargs for the DeliveryBuilder constructor.
Return type:	DeliveryBuilder.

add_delivery_x_hours_before_deadline(timedeltaobject, **kwargs)¶

Add a delivery hours hours before this deadline expires.

Shortcut that calls add_delivery_before_deadline() with timedeltaobject set to timedelta(hours=hours).

Parameters:	hours – Number of hours. kwargs – Extra kwargs for the DeliveryBuilder constructor.
Return type:	DeliveryBuilder.

DeliveryBuilder¶

class devilry.project.develop.testhelpers.corebuilder.DeliveryBuilder¶

delivery¶

The Delivery wrapped by this builder.

__init__(**kwargs)¶

Creates a new Delivery with the given attributes. If time_of_delivery is not provided, it defaults to now.

Parameters:	kwargs – Arguments for the Delivery constructor.

add_filemeta(**kwargs)¶

Adds a filemeta to the delivery. kwargs is forwarded to FilteMetaBuilder with kwargs['delivery'] set to this delivery.

Example:

deliverybuilder.add_filemeta(
    filename='test.txt',
    data='This is a test.'
)

Parameters:	kwargs – Kwargs for the FileMetaBuilder constructor.
Return type:	FileMetaBuilder.

add_feedback(**kwargs)¶

Adds a feedback to the delivery. kwargs is forwarded to StaticFeedbackBuilder with kwargs['delivery'] set to this delivery.

Example:

deliverybuilder.add_feedback(
    points=10,
    grade='10/100',
    is_passing_grade=False,
    saved_by=UserBuilder('testuser').user
)

Parameters:	kwargs – Kwargs for the StaticFeedbackBuilder constructor.
Return type:	StaticFeedbackBuilder.

add_passed_feedback(**kwargs)¶

Shortcut that adds a passed feedback to the delivery. kwargs is forwarded to add_feedback() with:

• points=1
• grade="Passed"
• is_passing_grade=True

Example:

deliverybuilder.add_passed_feedback(saved_by=UserBuilder('testuser').user)

Parameters:	kwargs – Extra kwargs for add_feedback(). Is updated with :points, grade and is_passing_grade as documented above.
Return type:	StaticFeedbackBuilder.

add_failed_feedback(**kwargs)¶

Shortcut that adds a failed feedback to the delivery. kwargs is forwarded to add_feedback() with:

• points=0
• grade="Failed"
• is_passing_grade=False

Example:

deliverybuilder.add_failed_feedback(saved_by=UserBuilder('testuser').user)

Parameters:	kwargs – Extra kwargs for add_feedback(). Is updated with :points, grade and is_passing_grade as documented above.
Return type:	StaticFeedbackBuilder.

FileMetaBuilder¶

class devilry.project.develop.testhelpers.corebuilder.FileMetaBuilder¶

filemeta¶

The FileMeta wrapped by this builder.

__init__(delivery, filename, data)¶

Creates a new FileMeta. Since FileMeta just points to files on disk, and creating those files requires iterators and extra stuff that is almost never needed for tests, we provide an easier method for creating files with FileMetaBuilder.

Parameters:	delivery – The Delivery object. filename – A filename. data – The file contents as a string.

StaticFeedbackBuilder¶

class devilry.project.develop.testhelpers.corebuilder.StaticFeedbackBuilder¶

feedback¶

The StaticFeedback wrapped by this builder.

__init__(**kwargs)¶

Creates a new StaticFeedback with the given attributes.

Parameters:	kwargs – Arguments for the StaticFeedback constructor.

Functions and attributes¶

devilry.apps.core.models.model_utils.pathsep¶

Path separator used by node-paths. The value is '.', and it must not be changed.

devilry.apps.core.models.model_utils.splitpath(path, expected_len=0)¶

Split the path on pathsep and return the resulting list. Example:

>>> splitpath('uio.ifi.matnat')
['uio', 'ifi', 'matnat']
>>> splitpath('uio.ifi.matnat', expected_len=2)
Traceback (most recent call last):
...
ValueError: Path must have exactly 2 parts

Parameters:	expected_len – Expected length of the resulting list. If the resulting list is not exactly the given length, ValueError is raised. If expected_len is 0 (default), no checking is done.

BaseNode¶

class devilry.apps.core.models.BaseNode¶

Bases: devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin, devilry.apps.core.models.save_interface.SaveInterface

The base class of the Devilry hierarchy. Implements basic functionality used by the other Node classes. This is an abstract datamodel, so it is never used directly.

short_name¶

A django.db.models.SlugField with max 20 characters. Only numbers, letters, ‘_’ and ‘-‘.

long_name¶

A django.db.models.CharField with max 100 characters. Gives a longer description than short_name.

AbstractIsAdmin¶

class devilry.apps.core.models.AbstractIsAdmin¶

Bases: object

Abstract class implemented by all classes where it is natural to need to check if a user has admin rights.

classmethod q_is_admin(user_obj)¶

Get a django.db.models.Q object matching all objects of this type where the given user is admin. The matched result is not guaranteed to contain unique items, so you should use distinct() on the queryset if this is required.

This must be implemented in all subclassed.

classmethod where_is_admin(user_obj, *related_fields)¶

Get all objects of this type where the given user is admin.

classmethod where_is_admin_or_superadmin(user_obj, *related_fields)¶

Get all objects of this type where the given user is admin, or all objects if the user is superadmin.

AbstractIsExaminer¶

class devilry.apps.core.models.AbstractIsExaminer¶

Bases: object

Abstract class implemented by all classes where it is natural to need to check if a user is examiner.

classmethod q_published(old=True, active=True)¶

Return a django.models.Q object which matches all items of this type where Assignment.publishing_time is in the past.

Parameters:	old – Include assignments where Period.end_time is in the past? active – Include assignments where Period.end_time is in the future?

classmethod q_is_examiner(user_obj)¶

Return a django.models.Q object which matches items where the given user is examiner.

classmethod where_is_examiner(user_obj)¶

Get all items of this type where the given user_obj is examiner on one of the assignment groups.

Parameters:	user_obj – A django.contrib.auth.models.User object.
Return type:	QuerySet

classmethod published_where_is_examiner(user_obj, old=True, active=True)¶

Get all published items of this type where the given user_obj is examiner on one of the assignment groups. Combines q_is_examiner() and q_published().

Parameters:	user_obj – q_is_examiner(). old – q_published(). active – q_published().
Returns:	A django.db.models.query.QuerySet with duplicate assignments eliminated.

classmethod active_where_is_examiner(user_obj)¶

Shortcut for published_where_is_examiner() with old=False.

classmethod old_where_is_examiner(user_obj)¶

Shortcut for published_where_is_examiner() with active=False.

Node¶

A node at the top of the navigation tree. It is a generic element used to organize administrators. A Node can be organized below another Node, and it can only have one parent.

Let us say you use Devilry within two departments at Fantasy University; informatics and mathematics. The university has an administration, and each department have their own administration. You would end up with this node-hierarchy:

• Fantasy University

  • Department of informatics
  • Department of mathematics

class devilry.apps.core.models.Node(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.basenode.BaseNode, devilry.apps.core.models.model_utils.Etag

This class is typically used to represent a hierarchy of institutions, faculties and departments.

parentnode¶

A django.db.models.ForeignKey that points to the parent node, which is always a Node.

admins¶

A django.db.models.ManyToManyField that holds all the admins of the Node.

child_nodes¶

A set of child_nodes of type Node for this node

subjects¶

A set of subjects for this node

etag¶

A DateTimeField containing the etag for this object.

iter_childnodes()¶

Recursively iterates over all child nodes, and their child nodes. For a list of direct child nodes, use atribute child_nodes instead.

clean(*args, **kwargs)¶

Validate the node, making sure it does not do something stupid.

Always call this before save()! Read about validation here: http://docs.djangoproject.com/en/dev/ref/models/instances/#id1

Raises ValidationError if:

• The node is it’s own parent.
• The node is the child of itself or one of its childnodes.

is_empty()¶

Returns True if this Node does not contain any childnodes or subjects.

Subject¶

A subject is a course, seminar, class or something else being given regularly. A subject is further divided into periods.

class devilry.apps.core.models.Subject(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.basenode.BaseNode, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate, devilry.apps.core.models.model_utils.Etag

parentnode¶

A django.db.models.ForeignKey that points to the parent node, which is always a Node.

admins¶

A django.db.models.ManyToManyField that holds all the admins of the Node.

short_name¶

A django.db.models.SlugField with max 20 characters. Only numbers, letters, ‘_’ and ‘-‘. Unlike all other children of BaseNode, Subject.short_name is unique. This is mainly to avoid the overhead of having to recurse all the way to the top of the node hierarchy for every unique path.

periods¶

A set of periods for this subject.

etag¶

A DateTimeField containing the etag for this object.

get_path()¶

Only returns short_name for subject since it is guaranteed to be unique.

is_empty()¶

Returns True if this Subject does not contain any periods.

Period¶

A Period is a limited period of time, like spring 2009, week 34 2010 or even a single day.

class devilry.apps.core.models.Period(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.basenode.BaseNode, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate, devilry.apps.core.models.model_utils.Etag

A Period represents a period of time, for example a half-year term at a university.

parentnode¶

A django.db.models.ForeignKey that points to the parent node, which is always a Subject.

start_time¶

A django.db.models.DateTimeField representing the starting time of the period.

end_time¶

A django.db.models.DateTimeField representing the ending time of the period.

admins¶

A django.db.models.ManyToManyField that holds all the admins of the node.

assignments¶

A Django RelatedManager of assignments for this period.

relatedexaminer_set¶

A Django RelatedManager of RelatedExaminers for this period.

relatedstudent_set¶

A Django RelatedManager of RelatedStudents for this period.

etag¶

A DateTimeField containing the etag for this object.

clean(*args, **kwargs)¶

Validate the period.

Always call this before save()! Read about validation here: http://docs.djangoproject.com/en/dev/ref/models/instances/#id1

Raises ValidationError if start_time is after end_time.

is_active()¶

Returns true if the period is active

classmethod q_is_active()¶

Get a django.db.models.Q object that matches all active periods (periods where start_time is in the past, and end_time is in the future).

Example:

activeperiods = Period.objects.filter(Period.q_is_active())

is_empty()¶

Returns True if this Period does not contain any assignments.

subject¶

More readable alternative to self.parentnode.

RelatedUserBase¶

Base class for devilry.apps.core.models.RelatedStudent and devilry.apps.core.models.RelatedExaminer.

class devilry.apps.core.models.relateduser.RelatedUserBase(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin

Common fields for examiners and students related to a period.

period¶

The period that the user is related to.

user¶

A django.contrib.auth.models.User object. Must be unique within this period.

tags¶

Comma-separated list of tags. Each tag is a word with the following letters allowed: a-z and 0-9. Each word is separated by a comma, and no whitespace.

RelatedStudent — Student on a period¶

A RelatedStudent is a student related to a devilry.apps.core.models.Period.

class devilry.apps.core.models.RelatedStudent(*args, **kwargs)¶

Bases: devilry.apps.core.models.relateduser.RelatedUserBase

Related student.

candidate_id¶

If a candidate has the same Candidate ID for all or many assignments in a semester, this field can be set to simplify setting candidate IDs on each assignment.

RelatedExaminer — Examiner on a period¶

A RelatedExaminer is an examiner related to a devilry.apps.core.models.Period.

class devilry.apps.core.models.RelatedExaminer(*args, **kwargs)¶

Bases: devilry.apps.core.models.relateduser.RelatedUserBase

Related examiner.

Adds no fields to RelatedUserBase.

Assignment¶

Represents one assignment within a given Period in a given Subject. Each assignment contains one AssignmentGroup for each student or group of students permitted to submit deliveries.

We have three main classifications of assignments:

1. A old assignment is a assignment where Period.end_time is in the past.
2. A published assignment is a assignment where publishing_time is in the past.
3. A active assignment is a assignment where publishing_time is in the past and current time is before Period.end_time.

class devilry.apps.core.models.Assignment(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.basenode.BaseNode, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate

parentnode¶

A django.db.models.ForeignKey that points to the parent node, which is always a Period.

publishing_time¶

A django.db.models.DateTimeField representing the publishing time of the assignment.

anonymous¶

A models.BooleanField specifying if the assignment should be anonymously for correcters.

admins¶

A django.db.models.ManyToManyField that holds all the admins of the Node.

assignmentgroups¶

A set of assignmentgroups for this assignment

examiners_publish_feedbacks_directly¶

Should feedbacks published by examiners be made avalable to the students immediately? If not, an administrator have to publish feedbacks. See also Deadline.feedbacks_published.

scale_points_percent¶

Percent to scale points on this assignment by for period overviews. The default is 100, which means no change to the points.

delivery_types¶

An integer identifying the type of deliveries allowed. Possible values:

0

Electronic deliveries using Devilry

1

Non-electronic deliveries, or deliveries made through another electronic system.

2

An alias/link to a delivery made in another Period.

deadline_handling¶

An integer identifying how deadlines are handled.

0

Soft deadlines. Deliveries can be added until groups are closed.

1

Hard deadlines. Deliveries can not be added after the deadline has expired.

first_deadline¶

A DateTimeField containing an optional first deadline for this assignment. This is metadata that the UI can use where it is natural.

max_points¶

An IntegerField that contains the maximum number of points possible to achieve on this assignment. This field may be None, and it is normally set by the grading system plugin.

DO NOT UPDATE MANUALLY. You can safely set an initial value for this manually when you create a new assignment, but when you update this field, do so using set_max_points().

passing_grade_min_points¶

An IntegerField that contains the minimum number of points required to achive a passing grade on this assignment. This means that any feedback with more this number of points or more is considered a passing grade.

WARNING: Changing this does not have any effect on existing feedback. To actually change existing feedback, you would have to update all feedback on the assignment, effectively creating new StaticFeedbacks from the latest published FeedbackDrafts for each AssignmentGroup.

points_to_grade_mapper¶

Configures how points should be mapped to a grade. Valid choices:

• passed-failed - Points is mapped directly to passed/failed. Zero points results in a failing grade, other points results in a passing grade.
• raw-points - The grade is <points>/<max-points>.
• table-lookup - Points is mapped to a grade via a table lookup. This means that someone configures a mapping from point thresholds to grades using devilry.apps.core.models.PointRangeToGrade.

grading_system_plugin_id¶

A CharField containing the ID of the grading system plugin this assignment uses.

students_can_create_groups¶

BooleanField specifying if students can join/leave groups on their own.

If this is True students should be allowed to join/leave groups. If students_can_not_create_groups_after is specified, this students can not create groups after students_can_not_create_groups_after even if this is True.

This does not in any way affect an admins ability to organize students in groups manually.

students_can_not_create_groups_after¶

Students can not create project groups after this time. Ignored if students_can_create_groups is False.

DateTimeField that defaults to None (null).

students_can_create_groups_now¶

Return True if students_can_create_groups is True, and students_can_not_create_groups_after is in the future or None.

is_electronic()¶

Returns True if deliverytypes is 0 (electric).

New in version 1.4.0.

is_nonelectronic()¶

Returns True if deliverytypes is 1 (non-electric).

New in version 1.4.0.

set_max_points(max_points)¶

Sets max_points, and invalidates any PointToGradeMap configured for this assignment if the new value for max_points differs from the old one.

Invalidating the PointToGradeMap ensures that the course admin has to re-evaluate the grade to point mapping when they change max_points.

NOTE: This saves the PointToGradeMap, but not the assignment.

get_gradingsystem_plugin_api()¶

Shortcut for:

devilry.devilry_gradingsystem.pluginregistry.gradingsystempluginregistry.get(
    self.grading_system_plugin_id)(self)

See: devilry.devilry_gradingsystem.pluginregistry.GradingSystemPluginRegistry.get().

has_valid_grading_setup()¶

Checks if this assignment is configured correctly for grading.

setup_grading(grading_system_plugin_id, points_to_grade_mapper, passing_grade_min_points=None, max_points=None)¶

Setup all of the simple parts of the grading system:

• grading_system_plugin_id
• points_to_grade_mapper
• passing_grade_min_points
• max_points

Does not setup:

• Grading system plugin specific configuration.
• A PointToGradeMap.

get_point_to_grade_map()¶

Get the PointToGradeMap for this assinment, creating if first if it does not exist.

points_is_passing_grade(points)¶

Checks if the given points represents a passing grade.

WARNING: This will only work if passing_grade_min_points is set. The best way to check that is with has_valid_grading_setup().

points_to_grade(points)¶

Convert the given points into a grade.

WARNING: This will not work if has_valid_grading_setup() is not True.

clean(*args, **kwargs)¶

Validate the assignment.

Always call this before save()! Read about validation here: http://docs.djangoproject.com/en/dev/ref/models/instances/#id1

Raises ValidationError if publishing_time is not between Period.start_time and Period.end_time.

is_empty()¶

Returns True if this Assignment does not contain any deliveries.

is_active()¶

Returns True if this assignment is published, and the period has not ended yet.

Examiner¶

class devilry.apps.core.models.Examiner(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin

assignmentgroup¶

The AssignmentGroup where this groups belongs.

user¶

A foreign key to a User.

Candidate¶

class devilry.apps.core.models.Candidate(*args, **kwargs)¶

Bases: django.db.models.base.Model

assignment_group¶

The AssignmentGroup where this groups belongs.

student¶

A student (a foreign key to a User).

candidate_id¶

A optional candidate id. This can be anything as long as it is not more than 30 characters. When the assignment is anonymous, this is the “name” shown to examiners instead of the username of the student.

AssignmentGroup¶

class devilry.apps.core.models.AssignmentGroup(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.model_utils.Etag

Represents a student or a group of students.

parentnode¶

A django.db.models.ForeignKey that points to the parent node, which is always an Assignment.

name¶

An optional name for the group.

candidates¶

A django RelatedManager that holds the candidates on this group.

examiners¶

A django.db.models.ManyToManyField that holds the examiner(s) that are to correct and grade the assignment.

is_open¶

A django.db.models.BooleanField that tells you if the group can add deliveries or not.

deadlines¶

A django RelatedManager that holds the deadlines on this group.

tags¶

A django RelatedManager that holds the tags on this group.

feedback¶

The last StaticFeedback (by save timestamp) on this assignmentgroup.

last_deadline¶

The last devilry.apps.core.models.Deadline for this assignmentgroup.

etag¶

A DateTimeField containing the etag for this object.

delivery_status¶

A CharField containing the status of the group. Valid status values:

• “no-deadlines”
• “corrected”
• “closed-without-feedback”
• “waiting-for-something”

save(*args, **kwargs)¶

Parameters:	update_delivery_status – Update the delivery_status? This is a somewhat expensive operation, so we provide the option to avoid it if needed. Defaults to True. autocreate_first_deadline_for_nonelectronic – Autocreate the first deadline if non-electronic assignment? Defaults to True.

classmethod q_is_candidate(user_obj)¶

Returns a django.models.Q object matching AssignmentGroups where the given student is candidate.

classmethod where_is_candidate(user_obj)¶

Returns a QuerySet matching all AssignmentGroups where the given user is student.

Parameters:	user_obj – A django.contrib.auth.models.User object.
Return type:	QuerySet

classmethod published_where_is_candidate(user_obj, old=True, active=True)¶

Returns a QuerySet matching all published assignment groups where the given user is student.

Parameters:	user_obj – A django.contrib.auth.models.User object.
Return type:	QuerySet

classmethod active_where_is_candidate(user_obj)¶

Returns a QuerySet matching all active assignment groups where the given user is student.

Parameters:	user_obj – A django.contrib.auth.models.User object.
Return type:	QuerySet

classmethod old_where_is_candidate(user_obj)¶

Returns a QuerySet matching all old assignment groups where the given user is student.

Parameters:	user_obj – A django.contrib.auth.models.User object.
Return type:	QuerySet

should_ask_if_examiner_want_to_give_another_chance¶

True if the current state of the group is such that the examiner should be asked if they want to give them another chance.

True if corrected with failing grade or closed without feedback.

missing_expected_delivery¶

Return True if the group has no deliveries, and we are expecting them to have made at least one delivery on the last deadline.

subject¶

Shortcut for parentnode.parentnode.parentnode.

period¶

Shortcut for parentnode.parentnode.

assignment¶

Alias for parentnode.

short_displayname¶

A short displayname for the group. If the assignment is anonymous, we list the candidate IDs. If the group has a name, the name is used, else we fall back to a comma separated list of usernames. If the group has no name and no students, we use the ID.

See also

https://github.com/devilry/devilry-django/issues/498

long_displayname¶

A long displayname for the group. If the assignment is anonymous, we list the candidate IDs.

If the assignment is not anonymous, we use a comma separated list of the displaynames (full names with fallback to username) of the students. If the group has a name, we use the groupname with the names of the students in parenthesis.

See also

https://github.com/devilry/devilry-django/issues/499

get_students()¶

Get a string containing all students in the group separated by comma and a space, like: superman, spiderman, batman.

WARNING: You should never use this method when the user is not an administrator.

get_examiners(separator=u', ')¶

Get a string contaning the username of all examiners in the group separated by comma (',').

Parameters:	separator – The unicode string used to separate candidates. Defaults to u', '.

is_examiner(user_obj)¶

Return True if user is examiner on this assignment group

can_delete(user_obj)¶

Check if the given user is permitted to delete this AssignmentGroup. A user is permitted to delete an object if the user is superadmin, or if the user is admin on the assignment (uses is_admin()). Only superusers are allowed to delete AssignmentGroups where AssignmentGroup.is_empty() returns False.

Note

This method can also be used to check if candidates can be removed from the group.

Returns:	True if the user is permitted to delete this object.

is_empty()¶

Returns True if this AssignmentGroup does not contain any deliveries.

get_active_deadline()¶

Get the active Deadline.

This is always the last deadline on this group.

Returns:	The latest deadline or None.

can_save(user_obj)¶

Check if the user has permission to save this AssignmentGroup.

can_add_deliveries()¶

Returns true if a student can add deliveries on this assignmentgroup

Both the assignmentgroups is_open attribute, and the periods start and end time is checked.

copy_all_except_candidates()¶

Note

Always run this is a transaction.

pop_candidate(candidate)¶

Make a copy of this group using copy_all_except_candidates, and add given candidate to the copied group and remove the candidate from this group.

Parameters:	candidate – A devilry.apps.core.models.Candidate object. The candidate must be among the candidates on this group.

Note

Always run this is a transaction.

recalculate_delivery_numbers()¶

Query all successful deliveries on this AssignmentGroup, ordered by time_of_delivery ascending, and number them with the oldest delivery as number 1.

merge_into(target)¶

Merge this AssignmentGroup into the target AssignmentGroup. Algorithm:

• Copy in all candidates and examiners not already on the AssignmentGroup.

• Delete all copies where the original is in self or target:

  • Delete all deliveries from target that are copy_of a delivery self.
  • Delete all deliveries from self that are copy_of a delivery in target.

• Loop through all deadlines in this AssignmentGroup, and for each deadline:

  If the datetime and text of the deadline matches one already in target, move the remaining deliveries into the target deadline.

  If the deadline and text does NOT match a deadline already in target, change assignmentgroup of the deadline to the master group.

• Recalculate delivery numbers of target using recalculate_delivery_numbers().

• Run self.delete().

• Set the latest feedback on target as the active feedback.

Note

The target.name or target.is_open is not changed.

Note

Everything except setting the latest feedback runs in a transaction. Setting the latest feedback does not run in transaction because we need to save the with feedback=None, and then set the new latest feedback to avoid IntegrityError.

classmethod merge_many_groups(sources, target)¶

Loop through the sources-iterable, and for each source in the iterator, run source.merge_into(target).

get_status()¶

Get the status of the group. Calculated with this algorithm:

if ``delivery_status == 'waiting-for-something'``
    if assignment.delivery_types==NON_ELECTRONIC:
        "waiting-for-feedback"
    else
        if before deadline
            "waiting-for-deliveries"
        if after deadline:
            "waiting-for-feedback"
else
    delivery_status

AssignmentGroupTag¶

class devilry.apps.core.models.AssignmentGroupTag(*args, **kwargs)¶

Bases: django.db.models.base.Model

An AssignmentGroup can be tagged with zero or more tags using this class.

assignment_group¶

The AssignmentGroup where this groups belongs.

tag¶

The tag. Max 20 characters. Can only contain a-z, A-Z, 0-9 and “_”.

Deadline¶

Each AssignmentGroup have zero or more deadlines.

class devilry.apps.core.models.Deadline(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate

A deadline on an AssignmentGroup. A deadline contains zero or more deliveries, the time of the deadline and an optional text.

assignment_group¶

The AssignmentGroup where the deadline is registered.

deadline¶

The deadline a DateTimeField.

text¶

A optional deadline text.

deliveries¶

A django RelatedManager that holds the deliveries on this group. NOTE: You should normally not use this directly, but rather use meth:.query_successful_deliveries.

deliveries_available_before_deadline¶

Should deliveries on this deadline be available to examiners before the deadline expires? This is set by students.

feedbacks_published¶

If this boolean field is True, the student can see all StaticFeedback objects associated with this Deadline through a Delivery. See also Assignment.examiners_publish_feedbacks_directly.

added_by¶

The User that added this deadline. Can be None, and all deadlines created before Devilry version 1.4.0 has this set to None.

New in version 1.4.0.

why_created¶

Why was this deadline created? Valid choices:

• None: Why the deadline was created is unknown.
• "examiner-gave-another-chance": Created because the examiner elected to give the student another chance to pass the assignment.

Can be None, and all deadlines created before Devilry version 1.4.0 has this set to None.

New in version 1.4.0.

classmethod reduce_datetime_precision(datetimeobj)¶

Reduce the precition of the datetimeobj to make it easier to compare and harder to make distinct deadlines that is basically the same time. We:

• Set seconds and microseconds to 0. This makes “Friday 14:59”, “Friday 14:59:00” and “Friday 14:59:59” equal. We do not allow specifying seconds in the UI, and handling this right in the core makes this easier to handle across the board.
• Set tzinfo to None. We do not support timezones in Devilry, so including it makes no sense.

Returns:	A copy of datetimeobj with second and microsecond set to 0, and tzinfo set to None.

clean(*args, **kwargs)¶

Validate the deadline.

Always call this before save()! Read about validation here: http://docs.djangoproject.com/en/dev/ref/models/instances/#id1

Raises ValidationError if:

• deadline is before Assignment.publishing_time.
• deadline is not before Period.end_time.

save(*args, **kwargs)¶

Parameters:	autocreate_delivery_if_nonelectronic – Autocreate a delivery if this save creates the deadline, and the assignment is non-electronic. Defaults to True.

query_successful_deliveries()¶

Returns a django QuerySet that filters all the successful deliveries on this group.

is_empty()¶

Returns True if this Deadline does not contain any deliveries.

can_delete(user_obj)¶

Check if the given user is permitted to delete this object. A user is permitted to delete an Deadline if the user is superadmin, or if the user is admin on the assignment. Only superusers are allowed to delete deadlines with any deliveries.

Returns:	True if the user is permitted to delete this object.

copy(newgroup)¶

Copy this deadline into newgroup, including all deliveries and filemetas, with the actual file data.

Note

Always run this is a transaction.

Warning

This does not autoset the latest feedback as active on the group. You need to handle that yourself after the copy.

is_in_the_future()¶

Return True if this deadline is in the future.

is_in_the_past()¶

Return True if this deadline is in the past.

has_text()¶

Checks that the text is not None or an empty string.

Delivery¶

assignmentgroup = AssignmentGroup.objects.get(id=1)
assignmentgroup.deliveries.create(delivered_by=student1,
                                  successful=True)

assignmentgroup = AssignmentGroup.objects.get(id=1)
delivery = assignmentgroup.deliveries.create(delivered_by=student1,
                                             successful=False)
delivery.add_file('test.py', ['print', 'hello world'])
delivery.add_file('test2.py', ['print "hi"'])
delivery.successful = True
delivery.save()

StaticFeedback¶

class devilry.apps.core.models.StaticFeedback(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate

Represents a feedback for a Delivery.

Each delivery can have zero or more feedbacks. Each StaticFeedback object stores static data that an examiner has published on a delivery. StaticFeedback is created and edited in a grade+feedback editor in a grade plugin, and when an examiner choose to publish feedback, a static copy of the data he/she created in the grade+feedback editor is stored in a StaticFeedback.

Feedbacks are only visible to students when Deadline.feedbacks_published on the related deadline is True. Feedbacks are related to Deadlines through its delivery.

Students are presented with the last feedback on a delivery, however they can browse every StaticFeedback on their deliveries. This history is to protect the student from administrators or examiners that change published feedback to avoid that a student can make an issue out of a bad feedback.

NOTE: When a StaticFeedback is saved, the corresponding AssignmentGroup.feedback is updated to the newly created StaticFeedback.

rendered_view¶

The rendered HTML view.

saved_by¶

The django.contrib.auth.models.User that created the StaticFeedback.

save_timestamp¶

Date/time when this feedback was created.

delivery¶

A django.db.models.ForeignKey that points to the Delivery where this feedback belongs.

grade¶

The grade as a short string (max 12 chars).

points¶

The number of points (integer).

is_passing_grade¶

Boolean is passing grade?

classmethod q_is_candidate(user_obj)¶

Returns a django.models.Q object matching Deliveries where the given student is candidate.

classmethod q_is_examiner(user_obj)¶

Returns a django.models.Q object matching Feedbacks where the given student is candidate.

classmethod from_points(points, assignment=None, **kwargs)¶

Shortcut method to initialize the StaticFeedback object from points.

Initializes a StaticFeedback with the given points, with grade and is_passing_grade inferred from the points with the help of devilry.apps.core.models.Assignment.points_to_grade() and devilry.apps.core.models.Assignment.points_is_passing_grade().

Example:

feedback = StaticFeedback.from_points(
    assignment=myassignment,
    points=10,
    delivery=mydelivery,
    saved_by=someuser)
assert(feedback.id == None)
assert(feedback.grade != None)

Parameters:

points – The number of points for the feedback. assignment – An Assignment object. Should be the assignment where delivery this feedback is for belongs, but that is not checked. Defaults to self.delivery.deadline.assignment_group.assignment. We provide the ability to take the assignment as argument instead of looking it up via self.delivery.deadline.assignment_group because we want to to be efficient when creating feedback in bulk. kwargs – Extra kwargs for the StaticFeedback constructor.

Returns:

An (unsaved) StaticFeedback.

save(*args, **kwargs)¶

Parameters:

autoset_timestamp_to_now – Automatically set the timestamp-attribute of this model to now? Defaults to True. autoupdate_related_models – Automatically update related models: Sets the last_feedback-attribute of self.delivery and saved the delivery. Sets the feedback and is_open attributes of self.delivery.deadline.assignment_group to this feedback, and False. Saves the AssignmentGroup. Defaults to True.

copy(newdelivery)¶

Copy this StaticFeedback into newdeadline.

Note

This only copies the StaticFeedback, not any data related to it via any grade editors.

Warning

This does not autoset the feedback as active on the group or as latest on the delivery. You need to handle that yourself after the copy.

FileMeta¶

class devilry.apps.core.models.FileMeta(*args, **kwargs)¶

Bases: django.db.models.base.Model, devilry.apps.core.models.abstract_is_admin.AbstractIsAdmin, devilry.apps.core.models.abstract_is_examiner.AbstractIsExaminer, devilry.apps.core.models.abstract_is_candidate.AbstractIsCandidate

Represents the metadata for a file belonging to a Delivery.

A file meta is just information about a single file, which is stored in a deliverystore. Use the deliverystore to manage the file stored in its physical location. Example:

filemeta = FileMeta.objects.get(pk=0)
if filemeta.deliverystore.exists(filemeta):
    filemeta.deliverystore.remove(filemeta)

# Write or read just as with the builtin open()
fobj = filemeta.deliverystore.write_open(filemeta)
fobj.write('Hello')
fobj.write('World')
fobj.close()
fobj = filemeta.deliverystore.read_open(filemeta)
print fobj.read()

See DeliveryStore for more details on deliverystores.

delivery¶

A django.db.models.ForeignKey that points to the Delivery of the given feedback.

filename¶

Name of the file.

size¶

Size of the file in bytes.

deliverystore¶

The current DeliveryStore. Class variable.

get_all_data_as_string()¶

Get all data store in the deliverystore for this FileMeta as a string. THIS IS ONLY FOR TESTING, and should NEVER be used for production code, since it will eat all memory on the server for huge files.

copy(newdelivery)¶

Copy this filemeta into newdelivery. Copies the database object and the data in the deliverystore.

DevilryUserProfile¶

See also: The Devilry User object.

class devilry.apps.core.models.DevilryUserProfile(*args, **kwargs)¶

Bases: django.db.models.base.Model

User profile with a one-to-one relation to django.contrib.auth.models.User.

Ment to be used as a Django user profile (AUTH_PROFILE_MODULE).

full_name¶

Django splits names into first_name and last_name. They are only 30 chars each. Read about why this is not a good idea here:

http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/

Since we require support for any name, we use our own full_name field, and ignore the one in Django. Max length 300.

languagecode¶

Used to store the preferred language for a user. Not required (The UI defaults to the default language)

get_displayname()¶

Get a name for this user, preferrably the full name, but falls back to username of that is unavailable.

Django user¶

Devilry users are Django django.contrib.auth.models.User objects. However we only use a subset of the fields:

• username
• email
• is_superuser
• password (if authenticating using the default Django auth)

Additional data¶

Additional data is stored in a one-to-one relation to devilry.apps.core.models.DevilryUserProfile. The profile object is available through the devilryuserprofile attribute of any django.contrib.auth.models.User object in devilry. It can be used in queries just like any other one-to-one relation, like this:

from django.contrib.auth.models import User
supermen = User.objects.filter(devilryuserprofile__full_name__contains="Superman")

Selecting a DeliveryStore¶

Devilry on comes with one DeliveryStore ready for production use, FsDeliveryStore. To enable a DeliveryStore, you have to set the DELIVERY_STORE_BACKEND-setting in your settings.py like this:

DELIVERY_STORE_BACKEND = 'devilry.apps.core.deliverystore.FsDeliveryStore'

The FsDeliveryStore also require you to define where on the disk you wish to store your files in the DELIVERY_STORE_ROOT-setting like this:

DELIVERY_STORE_ROOT = '/path/to/root/directory/of/my/deliverystore'

Creating your own DeliveryStore¶

To create your own DeliveryStore you have to implement DeliveryStoreInterface. A good example is FsDeliveryStore:

class FsDeliveryStore(DeliveryStoreInterface):
    """
    Filesystem-based DeliveryStore suitable for production use.

    It stores files in a filesystem hierarcy with one directory for each
    Delivery, with the delivery-id as name. In each delivery-directory, the
    files are stored by FileMeta id.
    """
    def __init__(self, root=None):
        """
        :param root: The root-directory where files are stored. Defaults to the value of the ``DELIVERY_STORE_ROOT``-setting.
        """
        self.root = root or settings.DELIVERY_STORE_ROOT

    def _get_dirpath(self, delivery_obj):
        return join(self.root, str(delivery_obj.pk))

    def _get_filepath(self, filemeta_obj):
        return join(self._get_dirpath(filemeta_obj.delivery),
                    str(filemeta_obj.pk))

    def read_open(self, filemeta_obj):
        filepath = self._get_filepath(filemeta_obj)
        if not exists(filepath):
            raise FileNotFoundError(filemeta_obj)
        return open(filepath, 'rb')

    def _create_dir(self, filemeta_obj):
        dirpath = self._get_dirpath(filemeta_obj.delivery)
        if not exists(dirpath):
            makedirs(dirpath)

    def write_open(self, filemeta_obj):
        self._create_dir(filemeta_obj)
        return open(self._get_filepath(filemeta_obj), 'wb')

    def remove(self, filemeta_obj):
        filepath = self._get_filepath(filemeta_obj)
        if not exists(filepath):
            raise FileNotFoundError(filemeta_obj)
        remove(filepath)

    def exists(self, filemeta_obj):
        filepath = self._get_filepath(filemeta_obj)
        return exists(filepath)

    def copy(self, filemeta_obj_from, filemeta_obj_to):
        frompath = self._get_filepath(filemeta_obj_from)
        topath = self._get_filepath(filemeta_obj_to)
        self._create_dir(filemeta_obj_to)
        shutil_copy(frompath, topath)

Setting the DeliveryStore manually - for tests¶

You might need to set the DeliveryStore manually if you need to handle deliveries in your own tests. Just set devilry.apps.core.FileMeta.deliveryStore like this:

from django.test import TestCase
from devilry.apps.core.models import FileMeta, Delivery
from devilry.apps.core.deliverystore import MemoryDeliveryStore

class MyTest(TestCase):
    def test_something(self):
        FileMeta.deliverystore = MemoryDeliveryStore()
        delivery = Delivery.begin(assignmentgroup, user)
        delivery.add_file('hello.txt', ['hello', 'world'])
        delivery.finish()

The recommended production deliverystore¶

The recommended DeliveryStore is devilry.apps.core.deliverystore.FsHierDeliveryStore.

It stores files in a filesystem hierarcy with one directory for each Delivery, with the delivery-id as name. In each delivery-directory, the files are stored by FileMeta id.

0/
    0/
        0/
        1/
        .
        .
    1/
        1000/
        2000/
        .
        .
    2/
    .
    .
    999/
1/
    0/
        1000000/
        1000001/
        .
        .
    1/
        1001000/
        1001001/
    2/
    .
    .
    999/
2/
.
.
999/

API¶

exception devilry.apps.core.deliverystore.FileNotFoundError(filemeta_obj)¶

Bases: exceptions.Exception

Exception to be raised when the remove method of a DeliveryStore does not find the given file.

class devilry.apps.core.deliverystore.DeliveryStoreInterface¶

Bases: object

The interface all deliverystores must implement. All methods raise NotImplementedError.

read_open(filemeta_obj)¶

Return a file-like object opened for reading.

The returned object must have close() and read() methods as defined by the documentation of the standard python file-class.

Parameters:	filemeta_obj – A devilry.core.models.FileMeta-object.

write_open(filemeta_obj)¶

Return a file-like object opened for writing.

The returned object must have close() and write() methods as defined by the documentation of the standard python file-class.

Parameters:	filemeta_obj – A devilry.core.models.FileMeta-object.

remove(filemeta_obj)¶

Remove the file.

Note that this method is called before the filemeta_obj is removed. This means that the file might be removed, and the removal of the filemeta_obj can still fail. To prevent users from having to manually resolve such cases implementations should check if the file exists, and raise FileNotFoundError if it does not.

The calling function has to check for FileNotFoundError and handle any other error.

Parameters:	filemeta_obj – A devilry.core.models.FileMeta-object.

exists(filemeta_obj)¶

Return True if the file exists, False if not.

Parameters:	filemeta_obj – A devilry.core.models.FileMeta-object.

copy(filemeta_obj_from, filemeta_obj_to)¶

Copy the underlying file-object for filemeta_obj_from into the file-object for filemeta_obj_to.

Defaults to an inefficient implementation using read_open() and meth:.write_open. Should be overridden for backends with some form of native copy-capability.

class devilry.apps.core.deliverystore.FsDeliveryStore(root=None)¶

Bases: devilry.apps.core.deliverystore.DeliveryStoreInterface

Filesystem-based DeliveryStore suitable for production use.

It stores files in a filesystem hierarcy with one directory for each Delivery, with the delivery-id as name. In each delivery-directory, the files are stored by FileMeta id.

Parameters:	root – The root-directory where files are stored. Defaults to the value of the DELIVERY_STORE_ROOT-setting.

class devilry.apps.core.deliverystore.FsHierDeliveryStore(root=None, interval=None)¶

Bases: devilry.apps.core.deliverystore.FsDeliveryStore

Filesystem-based DeliveryStore suitable for production use with huge amounts of deliveries.

Parameters:	root – The root-directory where files are stored. Defaults to the value of the DEVILRY_FSHIERDELIVERYSTORE_ROOT-setting. interval – The interval. Defaults to the value of the DEVILRY_FSHIERDELIVERYSTORE_INTERVAL-setting.

get_path_from_deliveryid(deliveryid)¶

>>> fs = FsHierDeliveryStore('/stuff/', interval=1000)
>>> fs.get_path_from_deliveryid(deliveryid=2001000)
(2, 1)
>>> fs.get_path_from_deliveryid(deliveryid=1000)
(0, 1)
>>> fs.get_path_from_deliveryid(deliveryid=1005)
(0, 1)
>>> fs.get_path_from_deliveryid(deliveryid=2005)
(0, 2)
>>> fs.get_path_from_deliveryid(deliveryid=0)
(0, 0)
>>> fs.get_path_from_deliveryid(deliveryid=1)
(0, 0)
>>> fs.get_path_from_deliveryid(deliveryid=1000000)
(1, 0)