High-Level API¶
Added 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: Any)[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:
- 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:
- 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:
- 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:
There is a directory present in the autograded directory.
The submission is present in the database.
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:
- get_assignment(assignment_id, released=None)[source]¶
Get information about an assignment given its name.
- get_assignments()[source]¶
Get a list of information about all assignments.
- Returns:
assignments – A list of dictionaries containing information about each assignment
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- autograde(assignment_id, student_id, force=True, create=True)[source]¶
Run
nbgrader autograde
for a particular assignment and student.- Parameters:
- 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:
- 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:
- 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:
- 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: