Gradebook

class nbgrader.api.Gradebook(db_url, course_id='default_course', authenticator=None)[source]

The gradebook object to interface with the database holding nbgrader grades.

__init__(db_url, course_id='default_course', authenticator=None)[source]

Initialize the connection to the database.

Parameters
  • db_url (string) – The URL to the database, e.g. sqlite:///grades.db

  • course_id (string, optional) – identifier of the course necessary for supporting multiple classes default course_id is ‘’ to be consistent with :class:~`nbgrader.apps.api.NbGraderAPI`

  • authenticator (:class:~`nbgrader.auth.BaseAuthenticator`) – An authenticator instance for communicating with an external database.

close()[source]

Close the connection to the database.

It is important to call this method after you are done using the gradebook. In particular, if you create multiple instances of the gradebook without closing them, you may run into errors where there are too many open connections to the database.

students

A list of all students in the database.

add_student(student_id, **kwargs)[source]

Add a new student to the database.

Parameters
  • student_id (string) – The unique id of the student

  • **kwargs (dict) – other keyword arguments to the Student object

Returns

student

Return type

Student

find_student(student_id)[source]

Find a student.

Parameters

student_id (string) – The unique id of the student

Returns

student

Return type

Student

update_or_create_student(student_id, **kwargs)[source]

Update an existing student, or create it if it doesn’t exist.

Parameters
  • student_id (string) – The unique id of the student

  • **kwargs – additional keyword arguments for the Student object

Returns

student

Return type

Student

remove_student(student_id)[source]

Deletes an existing student from the gradebook, including any submissions the might be associated with that student.

Parameters

student_id (string) – The unique id of the student

assignments

A list of all assignments in the gradebook.

add_assignment(name, **kwargs)[source]

Add a new assignment to the gradebook.

Parameters
  • name (string) – the unique name of the new assignment

  • **kwargs – additional keyword arguments for the Assignment object

Returns

assignment

Return type

Assignment

find_assignment(name)[source]

Find an assignment in the gradebook.

Parameters

name (string) – the unique name of the assignment

Returns

assignment

Return type

Assignment

update_or_create_assignment(name, **kwargs)[source]

Update an existing assignment, or create it if it doesn’t exist.

Parameters
  • name (string) – the name of the assignment

  • **kwargs – additional keyword arguments for the Assignment object

Returns

assignment

Return type

Assignment

remove_assignment(name)[source]

Deletes an existing assignment from the gradebook, including any submissions the might be associated with that assignment.

Parameters

name (string) – the name of the assignment to delete

add_notebook(name, assignment, **kwargs)[source]

Add a new notebook to an assignment.

Parameters
  • name (string) – the name of the new notebook

  • assignment (string) – the name of an existing assignment

  • **kwargs – additional keyword arguments for the Notebook object

Returns

notebook

Return type

Notebook

find_notebook(name, assignment)[source]

Find a particular notebook in an assignment.

Parameters
  • name (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

notebook

Return type

Notebook

update_or_create_notebook(name, assignment, **kwargs)[source]

Update an existing notebook, or create it if it doesn’t exist.

Parameters
  • name (string) – the name of the notebook

  • assignment (string) – the name of the assignment

  • **kwargs – additional keyword arguments for the Notebook object

Returns

notebook

Return type

Notebook

remove_notebook(name, assignment)[source]

Deletes an existing notebook from the gradebook, including any submissions the might be associated with that notebook.

Parameters
  • name (string) – the name of the notebook to delete

  • assignment (string) – the name of an existing assignment

add_grade_cell(name, notebook, assignment, **kwargs)[source]

Add a new grade cell to an existing notebook of an existing assignment.

Parameters
  • name (string) – the name of the new grade cell

  • notebook (string) – the name of an existing notebook

  • assignment (string) – the name of an existing assignment

  • **kwargs – additional keyword arguments for GradeCell

Returns

grade_cell

Return type

GradeCell

find_grade_cell(name, notebook, assignment)[source]

Find a grade cell in a particular notebook of an assignment.

Parameters
  • name (string) – the name of the grade cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

grade_cell

Return type

GradeCell

update_or_create_grade_cell(name, notebook, assignment, **kwargs)[source]

Update an existing grade cell in a notebook of an assignment, or create the grade cell if it does not exist.

Parameters
  • name (string) – the name of the grade cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

  • **kwargs – additional keyword arguments for GradeCell

Returns

grade_cell

Return type

GradeCell

add_solution_cell(name, notebook, assignment, **kwargs)[source]

Add a new solution cell to an existing notebook of an existing assignment.

Parameters
  • name (string) – the name of the new solution cell

  • notebook (string) – the name of an existing notebook

  • assignment (string) – the name of an existing assignment

  • **kwargs – additional keyword arguments for SolutionCell

Returns

solution_cell

Return type

SolutionCell

find_solution_cell(name, notebook, assignment)[source]

Find a solution cell in a particular notebook of an assignment.

Parameters
  • name (string) – the name of the solution cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

solution_cell

Return type

SolutionCell

update_or_create_solution_cell(name, notebook, assignment, **kwargs)[source]

Update an existing solution cell in a notebook of an assignment, or create the solution cell if it does not exist.

Parameters
  • name (string) – the name of the solution cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

  • **kwargs – additional keyword arguments for SolutionCell

Returns

solution_cell

Return type

SolutionCell

add_source_cell(name, notebook, assignment, **kwargs)[source]

Add a new source cell to an existing notebook of an existing assignment.

Parameters
  • name (string) – the name of the new source cell

  • notebook (string) – the name of an existing notebook

  • assignment (string) – the name of an existing assignment

  • **kwargs – additional keyword arguments for SourceCell

Returns

source_cell

Return type

SourceCell

find_source_cell(name, notebook, assignment)[source]

Find a source cell in a particular notebook of an assignment.

Parameters
  • name (string) – the name of the source cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

source_cell

Return type

SourceCell

update_or_create_source_cell(name, notebook, assignment, **kwargs)[source]

Update an existing source cell in a notebook of an assignment, or create the source cell if it does not exist.

Parameters
  • name (string) – the name of the source cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

  • **kwargs – additional keyword arguments for SourceCell

Returns

source_cell

Return type

SourceCell

add_task_cell(name, notebook, assignment, **kwargs)[source]

Add a new task cell to an existing notebook of an existing assignment.

Parameters
  • name (string) – the name of the new solution cell

  • notebook (string) – the name of an existing notebook

  • assignment (string) – the name of an existing assignment

  • **kwargs – additional keyword arguments for TaskCell

Returns

solution_cell

Return type

TaskCell

find_task_cell(name, notebook, assignment)[source]

Find a task cell in a particular notebook of an assignment.

Parameters
  • name (string) – the name of the solution cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

solution_cell

Return type

TaskCell

update_or_create_task_cell(name, notebook, assignment, **kwargs)[source]

Update an existing task cell in a notebook of an assignment, or create the solution cell if it does not exist.

Parameters
  • name (string) – the name of the solution cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

  • **kwargs – additional keyword arguments for TaskCell

Returns

task_cell

Return type

TaskCell

find_graded_cell(name, notebook, assignment)[source]

Find a graded cell in a particular notebook of an assignment. This can be either a GradeCell or a TaskCell

Parameters
  • name (string) – the name of the grade cell

  • notebook (string) – the name of the notebook

  • assignment (string) – the name of the assignment

Returns

grade_cell

Return type

GradeCell or TaskCell

add_submission(assignment, student, **kwargs)[source]

Add a new submission of an assignment by a student.

This method not only creates the high-level submission object, but also mirrors the entire structure of the existing assignment. Thus, once this method has been called, the new submission exists and is completely ready to be filled in with grades and comments.

Parameters
  • assignment (string) – the name of an existing assignment

  • student (string) – the name of an existing student

  • **kwargs – additional keyword arguments for SubmittedAssignment

Returns

submission

Return type

SubmittedAssignment

find_submission(assignment, student)[source]

Find a student’s submission for a given assignment.

Parameters
  • assignment (string) – the name of an assignment

  • student (string) – the unique id of a student

Returns

submission

Return type

SubmittedAssignment

update_or_create_submission(assignment, student, **kwargs)[source]

Update an existing submission of an assignment by a given student, or create a new submission if it doesn’t exist.

See add_submission() for additional details.

Parameters
  • assignment (string) – the name of an existing assignment

  • student (string) – the name of an existing student

  • **kwargs – additional keyword arguments for SubmittedAssignment

Returns

submission

Return type

SubmittedAssignment

grant_extension(assignment, student, minutes=0, hours=0, days=0, weeks=0)[source]

Gives an extension to a student for an assignment.

Note that extensions do not stack: if you call this method multiple times for the same assignment and student, the extension will be replaced. So if you want to extend an assignment by two days, and then another day, you will need to call this method with days=3 the second time.

If you do not provide any of the time arguments (minutes, hours, days, weeks), then any existing extension will be removed.

Parameters
  • assignment (string) – the name of an assignment

  • student (string) – the unique id of a student

  • minutes (number (default=0)) – The number of minutes in the extension

  • hours (number (default=0)) – The number of hours in the extension

  • days (number (default=0)) – The number of days in the extension

  • weeks (number (default=0)) – The number of weeks in the extension

remove_submission(assignment, student)[source]

Removes a submission from the database.

Parameters
  • assignment (string) – the name of an assignment

  • student (string) – the name of a student

remove_submission_notebook(notebook, assignment, student)[source]

Removes a submitted notebook from the database.

Parameters
  • notebook (string) – the name of a notebook

  • assignment (string) – the name of an assignment

  • student (string) – the name of a student

assignment_submissions(assignment)[source]

Find all submissions of a given assignment.

Parameters

assignment (string) – the name of an assignment

Returns

submissions – A list of SubmittedAssignment objects

Return type

list

notebook_submissions(notebook, assignment)[source]

Find all submissions of a given notebook in a given assignment.

Parameters
  • notebook (string) – the name of a notebook

  • assignment (string) – the name of an assignment

Returns

submissions – A list of SubmittedNotebook objects

Return type

list

student_submissions(student)[source]

Find all submissions by a given student.

Parameters

student (string) – the student’s unique id

Returns

submissions – A list of SubmittedAssignment objects

Return type

list

find_submission_notebook(notebook, assignment, student)[source]

Find a particular notebook in a student’s submission for a given assignment.

Parameters
  • notebook (string) – the name of a notebook

  • assignment (string) – the name of an assignment

  • student (string) – the unique id of a student

Returns

notebook

Return type

SubmittedNotebook

find_submission_notebook_by_id(notebook_id)[source]

Find a submitted notebook by its unique id.

Parameters

notebook_id (string) – the unique id of the submitted notebook

Returns

notebook

Return type

SubmittedNotebook

find_grade(grade_cell, notebook, assignment, student)[source]

Find a particular grade in a notebook in a student’s submission for a given assignment.

Parameters
  • grade_cell (string) – the name of a grade or task cell

  • notebook (string) – the name of a notebook

  • assignment (string) – the name of an assignment

  • student (string) – the unique id of a student

Returns

grade

Return type

Grade

find_grade_by_id(grade_id)[source]

Find a grade by its unique id.

Parameters

grade_id (string) – the unique id of the grade

Returns

grade

Return type

Grade

find_comment(solution_cell, notebook, assignment, student)[source]

Find a particular comment in a notebook in a student’s submission for a given assignment.

Parameters
  • solution_cell (string) – the name of a solution or task cell

  • notebook (string) – the name of a notebook

  • assignment (string) – the name of an assignment

  • student (string) – the unique id of a student

Returns

comment

Return type

Comment

find_comment_by_id(comment_id)[source]

Find a comment by its unique id.

Parameters

comment_id (string) – the unique id of the comment

Returns

comment

Return type

Comment

average_assignment_score(assignment_id)[source]

Compute the average score for an assignment.

Parameters

assignment_id (string) – the name of the assignment

Returns

score – The average score

Return type

float

average_assignment_code_score(assignment_id)[source]

Compute the average code score for an assignment.

Parameters

assignment_id (string) – the name of the assignment

Returns

score – The average code score

Return type

float

average_assignment_written_score(assignment_id)[source]

Compute the average written score for an assignment.

Parameters

assignment_id (string) – the name of the assignment

Returns

score – The average written score

Return type

float

average_assignment_task_score(assignment_id)[source]

Compute the average task score for an assignment.

Parameters

assignment_id (string) – the name of the assignment

Returns

score – The average task score

Return type

float

average_notebook_score(notebook_id, assignment_id)[source]

Compute the average score for a particular notebook in an assignment.

Parameters
  • notebook_id (string) – the name of the notebook

  • assignment_id (string) – the name of the assignment

Returns

score – The average notebook score

Return type

float

average_notebook_code_score(notebook_id, assignment_id)[source]

Compute the average code score for a particular notebook in an assignment.

Parameters
  • notebook_id (string) – the name of the notebook

  • assignment_id (string) – the name of the assignment

Returns

score – The average notebook code score

Return type

float

average_notebook_written_score(notebook_id, assignment_id)[source]

Compute the average written score for a particular notebook in an assignment.

Parameters
  • notebook_id (string) – the name of the notebook

  • assignment_id (string) – the name of the assignment

Returns

score – The average notebook written score

Return type

float

average_notebook_task_score(notebook_id, assignment_id)[source]

Compute the average task score for a particular notebook in an assignment.

Parameters
  • notebook_id (string) – the name of the notebook

  • assignment_id (string) – the name of the assignment

Returns

score – The average notebook task score

Return type

float

student_dicts()[source]

Returns a list of dictionaries containing student data. Equivalent to calling to_dict() for each student, except that this method is implemented using proper SQL joins and is much faster.

Returns

students – A list of dictionaries, one per student

Return type

list

notebook_submission_dicts(notebook_id, assignment_id)[source]

Returns a list of dictionaries containing submission data. Equivalent to calling to_dict() for each submission, except that this method is implemented using proper SQL joins and is much faster.

Parameters
  • notebook_id (string) – the name of the notebook

  • assignment_id (string) – the name of the assignment

Returns

submissions – A list of dictionaries, one per submitted notebook

Return type

list