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.CourseDirectory.course_id = "course101"

api = NbGraderAPI(config=config)

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

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

class nbgrader.apps.api.NbGraderAPI(**kwargs)[source]

A high-level API for using nbgrader.

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

Initialize the API.

Parameters
  • coursedir (nbgrader.coursedir.CourseDirectory) – (Optional) A course directory object.

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

  • exchange (:class:~`nbgrader.exchange.ExchangeFactory`) – (Optional) A factory for creating the exchange classes used for distributing assignments and feedback.

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

Deprecated, please use generate_assignment instead.

release(*args, **kwargs)[source]

Deprecated, please use release_assignment instead.

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

generate_feedback(assignment_id, student_id=None, force=True)[source]

Run nbgrader generate_feedback for a particular assignment and student.

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

  • student_id (string) – The name of the student (optional). If not provided, then generate feedback from autograded submissions.

  • force (bool) – Whether to force generating feedback, even if it already exists.

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_feedback(assignment_id, student_id=None)[source]

Run nbgrader release_feedback for a particular assignment/student.

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

  • assignment_id – The name of the student (optional). If not provided, then release all generated feedback.

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

fetch_feedback(assignment_id, student_id)[source]

Run nbgrader fetch_feedback for a particular assignment/student.

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

  • student_id (string) – The name of the student.

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

  • value (list of dict): all submitted assignments

Return type

dict