Gradebook¶

class nbgrader.api.Gradebook(db_url)[source]¶

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

__init__(db_url)[source]¶

Initialize the connection to the database.

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

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(name, **kwargs)[source]¶

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

Parameters:	name (string) – the name of the student **kwargs – additional keyword arguments for the `Student` object
Returns:	student
Return type:	`Student`

remove_student(name)[source]¶

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

Parameters:	name (string) – the name of the student to delete

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_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`

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 an assignment 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 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 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_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

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