Database models

In general, these database models should never be modified by hand. You should only ever modify them using a Gradebook object, so that changes are properly persisted to the database, and so that the models don’t end up in an inconsistent state. However, some methods of the Gradebook object return database model objects, so those models and their attributes are documented here for reference.

class nbgrader.api.Student(**kwargs)[source]

Database representation of a student.

id

Unique id of the student. This could be a student ID, a username, an email address, etc., so long as it is unique.

first_name

(Optional) The first name of the student

last_name

(Optional) The last name of the student

email

(Optional) The student’s email address, if the id does not correspond to an email address

score

The overall score of the student across all assignments, computed automatically from the score of each submitted assignment.

max_score

The maximum possible score the student could achieve across all assignments, computed automatically from the max_score of each assignment.

lms_user_id

The LMS user ID, this is mainly for identifying students in your LMS system and was added so teachers and TA’s can easily send grades to a LMS such as Canvas and Blackboard.

submissions

A collection of assignments submitted by the student, represented as SubmittedAssignment objects

to_dict()[source]

Convert the student object to a JSON-friendly dictionary representation.

Master version of an assignment

class nbgrader.api.Assignment(name, duedate=None, course_id='default_course', **kwargs)[source]

Database representation of the master/source version of an assignment.

id

Unique id of the assignment (automatically generated)

name

Unique human-readable name for the assignment, such as “Problem Set 1”

duedate

(Optional) Duedate for the assignment in datetime format, with UTC timezone

course_id

The course for this assignment

course
notebooks

A collection of notebooks contained in this assignment, represented by Notebook objects

submissions

A collection of submissions of this assignment, represented by SubmittedAssignment objects.

num_submissions

The number of submissions of this assignment

max_score

Maximum score achievable on this assignment, automatically calculated from the max_score of each notebook

max_code_score

Maximum coding score achievable on this assignment, automatically calculated from the max_code_score of each notebook

max_written_score

Maximum written score achievable on this assignment, automatically calculated from the max_written_score of each notebook

to_dict()[source]

Convert the assignment object to a JSON-friendly dictionary representation.

class nbgrader.api.Notebook(**kwargs)[source]

Database representation of the master/source version of a notebook.

id

Unique id of the notebook (automatically generated)

name

Unique human-readable name for the notebook, such as “Problem 1”. Note the uniqueness is only constrained within assignments (e.g. it is ok for two different assignments to both have notebooks called “Problem 1”, but the same assignment cannot have two notebooks with the same name).

assignment

The Assignment object that this notebook is a part of

assignment_id

Unique id of assignment

kernelspec

The json string representation of the kernelspec for this notebook

grade_cells
solution_cells
task_cells
source_cells

A collection of source cells contained within this notebook, represented by SourceCell objects

submissions

A collection of submitted versions of this notebook, represented by SubmittedNotebook objects

num_submissions

The number of submissions of this notebook

max_score

Maximum score achievable on this notebook, automatically calculated from the max_score of each grade cell

max_code_score

Maximum coding score achievable on this notebook, automatically calculated from the max_score and cell_type of each grade cell

max_written_score

Maximum written score achievable on this notebook, automatically calculated from the max_score and cell_type of each grade cell

needs_manual_grade

Whether there are any submitted versions of this notebook that need to be manually graded, automatically determined from the needs_manual_grade attribute of each submitted notebook

to_dict()[source]

Convert the notebook object to a JSON-friendly dictionary representation.

class nbgrader.api.GradedMixin[source]

Mixin class providing the reference to a grade and the data members relevant for graded cells.

max_score = Column(None, Float(), table=None, nullable=False)
cell_type = Column(None, Enum('code', 'markdown', name='grade_cell_type'), table=None, nullable=False)
class nbgrader.api.BaseCell(**kwargs)[source]

Database representation of a cell. It is meant as a base class for cells where additional behavior is added through mixin classes.

id

Unique id of the grade cell (automatically generated)

name

Unique human-readable name of the cell. This need only be unique within the notebook, not across notebooks.

notebook

The notebook that this cell is contained within, represented by a Notebook object

notebook_id

Unique id of the notebook

assignment
class nbgrader.api.GradeCell(**kwargs)[source]

Bases: BaseCell, GradedMixin

Database representation of the master/source version of a grade cell.

id

Unique id of the cell (automatically generated from BaseCell)

grades

A collection of grades associated with this cell, represented by Grade objects

to_dict()[source]

Convert the grade cell object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the names of the notebook and assignment, not the objects themselves.

class nbgrader.api.SolutionCell(**kwargs)[source]
id

Unique id of the cell (automatically generated from BaseCell)

comments

A collection of comments associated with this cell, represented by Comment objects

to_dict()[source]

Convert the solution cell object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the names of the notebook and assignment, not the objects themselves.

class nbgrader.api.TaskCell(**kwargs)[source]

Bases: BaseCell, GradedMixin

Database representation of a task cell.

id

Unique id of the cell (automatically generated from BaseCell)

grades

A collection of grades associated with this cell, represented by Grade objects

comments

A collection of comments associated with this cell, represented by Comment objects

to_dict()[source]

Convert the task cell object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the names of the notebook and assignment, not the objects themselves.

class nbgrader.api.SourceCell(**kwargs)[source]
id

Unique id of the source cell (automatically generated)

name

Unique human-readable name of the source cell. This need only be unique within the notebook, not across notebooks.

cell_type

The cell type, either “code” or “markdown”

locked

Whether the cell is locked (e.g. the source saved in the database should be used to overwrite the source of students’ cells)

source

The source code or text of the cell

checksum

A checksum of the cell contents. This should usually be computed using nbgrader.utils.compute_checksum()

notebook

The Notebook that this source cell is contained in

notebook_id

Unique id of the notebook

assignment = ObjectAssociationProxyInstance(AssociationProxy('notebook', 'assignment'))

The assignment that this cell is contained within, represented by a Assignment object

to_dict()[source]

Convert the source cell object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the names of the notebook and assignment, not the objects themselves.

Submitted assignments

class nbgrader.api.SubmittedAssignment(**kwargs)[source]

Database representation of an assignment submitted by a student.

id

Unique id of the submitted assignment (automatically generated)

name = ColumnAssociationProxyInstance(AssociationProxy('assignment', 'name'))

Name of the assignment, inherited from Assignment

assignment

The master version of this assignment, represented by a Assignment object

assignment_id

Unique id of assignment

student

The student who submitted this assignment, represented by a Student object

student_id

Unique id of student

timestamp

(Optional) The date and time that the assignment was submitted, in date time format with a UTC timezone

extension

(Optional) An extension given to the student for this assignment, in time delta format

duedate

The duedate of this student’s assignment, which includes any extension given, if applicable, and which is just the regular assignment duedate otherwise.

Return type

datetime

total_seconds_late

The number of seconds that this assignment was turned in past the duedate (including extensions, if any). If the assignment was turned in before the deadline, this value will just be zero.

Return type

float

notebooks

A collection of notebooks contained within this submitted assignment, represented by SubmittedNotebook objects

score

The score assigned to this assignment, automatically calculated from the score of each notebook within this submitted assignment.

max_score

The maximum possible score of this assignment, inherited from Assignment

code_score

The code score assigned to this assignment, automatically calculated from the code_score of each notebook within this submitted assignment.

max_code_score

The maximum possible code score of this assignment, inherited from Assignment

written_score

The written score assigned to this assignment, automatically calculated from the written_score of each notebook within this submitted assignment.

max_written_score

The maximum possible written score of this assignment, inherited from Assignment

needs_manual_grade

Whether this assignment has parts that need to be manually graded, automatically determined from the needs_manual_grade attribute of each notebook.

late_submission_penalty

The penalty (>= 0) given for submitting the assignment late. Automatically determined from the late_submission_penalty attribute of each notebook.

to_dict()[source]

Convert the submitted assignment object to a JSON-friendly dictionary representation. Note that this includes a student key which is the unique id of the student, not the object itself.

class nbgrader.api.SubmittedNotebook(**kwargs)[source]

Database representation of a notebook submitted by a student.

id

Unique id of the submitted notebook (automatically generated)

name = ColumnAssociationProxyInstance(AssociationProxy('notebook', 'name'))

Name of the notebook, inherited from Notebook

assignment

The submitted assignment this notebook is a part of, represented by a SubmittedAssignment object

assignment_id

Unique id of assignment

notebook

The master version of this notebook, represented by a Notebook object

notebook_id

Unique id of notebook

grades

Collection of associated with this submitted notebook, represented by Grade objects

comments

Collection of comments associated with this submitted notebook, represented by Comment objects

student = ObjectAssociationProxyInstance(AssociationProxy('assignment', 'student'))

The student who submitted this notebook, represented by a Student object

flagged

Whether this assignment has been flagged by a human grader

score

The score assigned to this notebook, automatically calculated from the score of each grade cell within this submitted notebook.

max_score

The maximum possible score of this notebook, inherited from Notebook

code_score

The code score assigned to this notebook, automatically calculated from the score and cell_type of each grade within this submitted notebook.

max_code_score

The maximum possible code score of this notebook, inherited from Notebook

written_score

The written score assigned to this notebook, automatically calculated from the score and cell_type of each grade within this submitted notebook.

max_written_score

The maximum possible written score of this notebook, inherited from Notebook

needs_manual_grade

Whether this notebook has parts that need to be manually graded, automatically determined from the needs_manual_grade attribute of each grade.

failed_tests

Whether this notebook contains autograder tests that failed to pass, automatically determined from the failed_tests attribute of each grade.

late_submission_penalty

The penalty (>= 0) given for submitting the assignment late. Updated by the LateSubmissionPlugin.

class nbgrader.api.Grade(**kwargs)[source]

Database representation of a grade assigned to the submitted version of a grade cell.

id

Unique id of the grade (automatically generated)

name = ColumnAssociationProxyInstance(AssociationProxy('cell', 'name'))

Unique name of the grade cell, inherited from GradeCell

assignment = ObjectAssociationProxyInstance(AssociationProxy('notebook', 'assignment'))

The submitted assignment that this grade is contained in, represented by a SubmittedAssignment object

notebook

The submitted notebook that this grade is assigned to, represented by a SubmittedNotebook object

notebook_id

Unique id of notebook

cell

The master version of the cell this grade is assigned to, represented by a GradeCell object.

cell_id

Unique id of cell

cell_type

The type of cell this grade corresponds to, inherited from GradeCell

student = ObjectAssociationProxyInstance(AssociationProxy('notebook', 'student'))

The student who this grade is assigned to, represented by a Student object

auto_score

Score assigned by the autograder

manual_score

Score assigned by a human grader

extra_credit

Extra credit assigned by a human grader

score

The overall score, computed automatically from the auto_score and manual_score values. If neither are set, the score is zero. If both are set, then the manual score takes precedence. If only one is set, then that value is used for the score.

max_score
needs_manual_grade

Whether a score needs to be assigned manually. This is True by default.

failed_tests

Whether the autograded score is a result of failed autograder tests. This is True if the autograder score is zero and the cell type is “code”, and otherwise False.

to_dict()[source]

Convert the grade object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the name of the notebook and assignment, not the actual objects. It also includes a key for student which corresponds to the unique id of the student, not the actual student object.

class nbgrader.api.Comment(**kwargs)[source]

Database representation of a comment on a cell in a submitted notebook.

id

Unique id of the comment (automatically generated)

name = ColumnAssociationProxyInstance(AssociationProxy('cell', 'name'))

Unique name of the solution cell, inherited from SolutionCell

assignment = ObjectAssociationProxyInstance(AssociationProxy('notebook', 'assignment'))

The submitted assignment that this comment is contained in, represented by a SubmittedAssignment object

notebook

The submitted notebook that this comment is assigned to, represented by a SubmittedNotebook object

notebook_id

Unique id of notebook

cell

The master version of the cell this comment is assigned to, represented by a SolutionCell object.

cell_id

Unique id of cell

student = ObjectAssociationProxyInstance(AssociationProxy('notebook', 'student'))

The student who this comment is assigned to, represented by a Student object

auto_comment

A comment which is automatically assigned by the autograder

manual_comment

A comment which is assigned manually

comment

The overall comment, computed automatically from the auto_comment and manual_comment values. If neither are set, the comment is None. If both are set, then the manual comment takes precedence. If only one is set, then that value is used for the comment.

to_dict()[source]

Convert the comment object to a JSON-friendly dictionary representation. Note that this includes keys for notebook and assignment which correspond to the name of the notebook and assignment, not the actual objects. It also includes a key for student which corresponds to the unique id of the student, not the actual student object.

class nbgrader.api.Course(**kwargs)[source]

Table to store the courses

id
assignments