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 (
str
) – The URL to the database, e.g.sqlite:///grades.db
course_id (
str
) – identifier of the course necessary for supporting multiple classes default course_id is ‘’ to be consistent with :class:~`nbgrader.apps.api.NbGraderAPI`authenticator (
Optional
[Authenticator
]) – 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.
- find_student(student_id)[source]¶
Find a student.
- Parameters:
student_id (
str
) – The unique id of the student- Return type:
student
- update_or_create_student(student_id, **kwargs)[source]¶
Update an existing student, or create it if it doesn’t exist.
- 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 (
str
) – the unique name of the new assignment**kwargs – additional keyword arguments for the
Assignment
object
- Return type:
assignment
- find_assignment(name)[source]¶
Find an assignment in the gradebook.
- Parameters:
name (
str
) – the unique name of the 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 (
str
) – the name of the assignment**kwargs – additional keyword arguments for the
Assignment
object
- 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
- update_or_create_notebook(name, assignment, **kwargs)[source]¶
Update an existing notebook, or create it if it doesn’t exist.
- 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.
- find_grade_cell(name, notebook, assignment)[source]¶
Find a grade cell in a particular notebook of an assignment.
- 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.
- add_solution_cell(name, notebook, assignment, **kwargs)[source]¶
Add a new solution cell to an existing notebook of an existing assignment.
- Parameters:
name (
str
) – the name of the new solution cellnotebook (
str
) – the name of an existing notebookassignment (
str
) – the name of an existing assignment**kwargs – additional keyword arguments for
SolutionCell
- Returns:
solution_cell
- Return type:
- 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:
- 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 (
str
) – the name of the solution cellnotebook (
str
) – the name of the notebookassignment (
str
) – the name of the assignment**kwargs – additional keyword arguments for
SolutionCell
- Return type:
solution_cell
- 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:
- find_source_cell(name, notebook, assignment)[source]¶
Find a source cell in a particular notebook of an assignment.
- Parameters:
- Returns:
source_cell
- Return type:
- 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 (
str
) – the name of the source cellnotebook (
str
) – the name of the notebookassignment (
str
) – the name of the assignment**kwargs – additional keyword arguments for
SourceCell
- Return type:
source_cell
- add_task_cell(name, notebook, assignment, **kwargs)[source]¶
Add a new task cell to an existing notebook of an existing assignment.
- 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:
- 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.
- 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
- 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 (
str
) – the name of an existing assignmentstudent (
str
) – the name of an existing student**kwargs – additional keyword arguments for
SubmittedAssignment
- Return type:
submission
- 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:
- 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 (
str
) – the name of an existing assignmentstudent (
str
) – the name of an existing student**kwargs – additional keyword arguments for
SubmittedAssignment
- Return type:
submission
- 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:
- 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:
- 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:
- find_submission_notebook(notebook, assignment, student)[source]¶
Find a particular notebook in a student’s submission for a given assignment.
- 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:
- find_grade(grade_cell, notebook, assignment, student)[source]¶
Find a particular grade in a notebook in a student’s submission for a given assignment.
- 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:
- find_comment(solution_cell, notebook, assignment, student)[source]¶
Find a particular comment in a notebook in a student’s submission for a given assignment.
- 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:
- 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:
- 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:
- 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:
- 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:
- average_notebook_score(notebook_id, assignment_id)[source]¶
Compute the average score for a particular notebook in an assignment.
- average_notebook_code_score(notebook_id, assignment_id)[source]¶
Compute the average code score for a particular notebook in an assignment.
- average_notebook_written_score(notebook_id, assignment_id)[source]¶
Compute the average written score for a particular notebook in an assignment.
- average_notebook_task_score(notebook_id, assignment_id)[source]¶
Compute the average task score for a particular notebook in an assignment.
- 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:
- submission_dicts(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:
assignment_id (string) – the name of the assignment
- Returns:
submissions – A list of dictionaries, one per submitted assignment
- Return type:
- 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: