High-Level API

New in version 0.5.0.

This API is a high-level api that provides access to nbgrader’s core functionality, for example assigning, releasing, collecting, and autograding assignments. For example:

from nbgrader.apps import NbGraderAPI
from traitlets.config import Config

# create a custom config object to specify options for nbgrader
config = Config()
config.Exchange.course_id = "course101"

api = NbGraderAPI(config=config)

# assuming source/ps1 exists
api.assign("ps1")

For details on how to configure the API, see Configuration options.

class nbgrader.apps.api.NbGraderAPI(coursedir=None, **kwargs)[source]

A high-level API for using nbgrader.

__init__(coursedir=None, **kwargs)[source]

Initialize the API.

Parameters:
  • coursedir (nbgrader.coursedir.CourseDirectory) – (Optional) A course directory object.
  • kwargs – Additional keyword arguments (e.g. parent, config)
gradebook

An instance of nbgrader.api.Gradebook.

Note that each time this property is accessed, a new gradebook is created. The user is responsible for destroying the gradebook through close().

get_source_assignments()[source]

Get the names of all assignments in the source directory.

Returns:assignments – A set of assignment names
Return type:set
get_released_assignments()[source]

Get the names of all assignments that have been released to the exchange directory. If the course id is blank, this returns an empty set.

Returns:assignments – A set of assignment names
Return type:set
get_submitted_students(assignment_id)[source]

Get the ids of students that have submitted a given assignment (determined by whether or not a submission exists in the submitted directory).

Parameters:assignment_id (string) – The name of the assignment. May be * to select for all assignments.
Returns:students – A set of student ids
Return type:set
get_submitted_timestamp(assignment_id, student_id)[source]

Gets the timestamp of a submitted assignment.

Parameters:
  • assignment_id (string) – The assignment name
  • student_id (string) – The student id
Returns:

timestamp – The timestamp of the submission, or None if the timestamp does not exist

Return type:

datetime.datetime or None

get_autograded_students(assignment_id)[source]

Get the ids of students whose submission for a given assignment has been autograded. This is determined based on satisfying all of the following criteria:

  1. There is a directory present in the autograded directory.
  2. The submission is present in the database.
  3. The timestamp of the autograded submission is the same as the timestamp of the original submission (in the submitted directory).
Returns:students – A set of student ids
Return type:set
get_assignment(assignment_id, released=None)[source]

Get information about an assignment given its name.

Parameters:
  • assignment_id (string) – The name of the assignment
  • released (list) – (Optional) A set of names of released assignments, obtained via self.get_released_assignments().
Returns:

assignment – A dictionary containing information about the assignment

Return type:

dict

get_assignments()[source]

Get a list of information about all assignments.

Returns:assignments – A list of dictionaries containing information about each assignment
Return type:list
get_notebooks(assignment_id)[source]

Get a list of notebooks in an assignment.

Parameters:assignment_id (string) – The name of the assignment
Returns:notebooks – A list of dictionaries containing information about each notebook
Return type:list
get_submission(assignment_id, student_id, ungraded=None, students=None)[source]

Get information about a student’s submission of an assignment.

Parameters:
  • assignment_id (string) – The name of the assignment
  • student_id (string) – The student’s id
  • ungraded (set) – (Optional) A set of student ids corresponding to students whose submissions have not yet been autograded.
  • students (dict) – (Optional) A dictionary of dictionaries, keyed by student id, containing information about students.
Returns:

submission – A dictionary containing information about the submission

Return type:

dict

get_submissions(assignment_id)[source]

Get a list of submissions of an assignment. Each submission corresponds to a student.

Parameters:assignment_id (string) – The name of the assignment
Returns:notebooks – A list of dictionaries containing information about each submission
Return type:list
get_notebook_submission_indices(assignment_id, notebook_id)[source]

Get a dictionary mapping unique submission ids to indices of the submissions relative to the full list of submissions.

Parameters:
  • assignment_id (string) – The name of the assignment
  • notebook_id (string) – The name of the notebook
Returns:

indices – A dictionary mapping submission ids to the index of each submission

Return type:

dict

get_notebook_submissions(assignment_id, notebook_id)[source]

Get a list of submissions for a particular notebook in an assignment.

Parameters:
  • assignment_id (string) – The name of the assignment
  • notebook_id (string) – The name of the notebook
Returns:

submissions – A list of dictionaries containing information about each submission.

Return type:

list

get_student(student_id, submitted=None)[source]

Get a dictionary containing information about the given student.

Parameters:
  • student_id (string) – The unique id of the student
  • submitted (set) – (Optional) A set of unique ids of students who have submitted an assignment
Returns:

student – A dictionary containing information about the student, or None if the student does not exist

Return type:

dictionary

get_students()[source]

Get a list containing information about all the students in class.

Returns:students – A list of dictionaries containing information about all the students
Return type:list
get_student_submissions(student_id)[source]

Get information about all submissions from a particular student.

Parameters:student_id (string) – The unique id of the student
Returns:submissions – A list of dictionaries containing information about all the student’s submissions
Return type:list
get_student_notebook_submissions(student_id, assignment_id)[source]

Gets information about all notebooks within a submitted assignment.

Parameters:
  • student_id (string) – The unique id of the student
  • assignment_id (string) – The name of the assignment
Returns:

submissions – A list of dictionaries containing information about the submissions

Return type:

list

assign(assignment_id, force=True, create=True)[source]

Run nbgrader assign for a particular assignment.

Parameters:
  • assignment_id (string) – The name of the assignment
  • force (bool) – Whether to force creating the student version, even if it already exists.
  • create (bool) – Whether to create the assignment in the database, if it doesn’t already exist.
Returns:

result – A dictionary with the following keys (error and log may or may not be present):

  • success (bool): whether or not the operation completed successfully
  • error (string): formatted traceback
  • log (string): captured log output

Return type:

dict

release(assignment_id)[source]

Run nbgrader release for a particular assignment.

Parameters:assignment_id (string) – The name of the assignment
Returns:result – A dictionary with the following keys (error and log may or may not be present):
  • success (bool): whether or not the operation completed successfully
  • error (string): formatted traceback
  • log (string): captured log output
Return type:dict
unrelease(assignment_id)[source]

Run nbgrader list --remove for a particular assignment.

Parameters:assignment_id (string) – The name of the assignment
Returns:result – A dictionary with the following keys (error and log may or may not be present):
  • success (bool): whether or not the operation completed successfully
  • error (string): formatted traceback
  • log (string): captured log output
Return type:dict
collect(assignment_id, update=True)[source]

Run nbgrader collect for a particular assignment.

Parameters:
  • assignment_id (string) – The name of the assignment
  • update (bool) – Whether to update already-collected assignments with newer submissions, if they exist
Returns:

result – A dictionary with the following keys (error and log may or may not be present):

  • success (bool): whether or not the operation completed successfully
  • error (string): formatted traceback
  • log (string): captured log output

Return type:

dict

autograde(assignment_id, student_id, force=True, create=True)[source]

Run nbgrader autograde for a particular assignment and student.

Parameters:
  • assignment_id (string) – The name of the assignment
  • student_id (string) – The unique id of the student
  • force (bool) – Whether to autograde the submission, even if it’s already been autograded
  • create (bool) – Whether to create students in the database if they don’t already exist
Returns:

result – A dictionary with the following keys (error and log may or may not be present):

  • success (bool): whether or not the operation completed successfully
  • error (string): formatted traceback
  • log (string): captured log output

Return type:

dict