ZipCollect plugins

Added in version 0.5.0.

Extractor plugin

Extract archive (zip) files in the archive_directory. Archive files are extracted to the extracted_directory. Non-archive (zip) files found in the archive_directory are copied to the extracted_directory. Archive files will be extracted into their own sub-directory within the extracted_directory and any archive files within archives will also be extracted into their own sub-directory along the path.

Creating a plugin

To add your own extractor you can create a plugin class that inherits from ExtractorPlugin. This class needs to only implement one method, which is the extract() method (see below). Let’s say you create your own plugin in the myextractor.py file, and your plugin is called MyExtractor. Then, on the command line, you would run:

nbgrader zip_collect --extractor=myextractor.MyExtractor

which will use your custom extractor rather than the built-in one.

API

class nbgrader.plugins.zipcollect.ExtractorPlugin(**kwargs)

Submission archive files extractor plugin for the ZipCollectApp. Extractor plugin subclasses MUST inherit from this class.

extract(archive_path, extracted_path)

Extract archive (zip) files and submission files in the archive_directory. Files are extracted to the extracted_directory. Non-archive (zip) files found in the archive_directory are copied to the extracted_directory. This is the main function called by the ZipCollectApp for each archive file to be extracted.

Parameters:

• archive_path (str) – Absolute path to the archive_directory.

• extracted_path (str) – Absolute path to the extracted_directory.

Return type:

None

FileNameCollector plugin

Apply a named group regular expression to each filename received from the ZipCollectApp and return None if the file should be skipped or a dictionary that, at the very least, contains the student_id and file_id key value pairs; and optionally contains the timestamp key value pair, for example:

dict(
    file_id='problem1.ipynb',
    student_id='hacker',
    timestamp='2017-01-30 15:30:10 UCT'
)

For more information about named group regular expressions see https://docs.python.org/3/howto/regex.html

Note: file_id must contain the relative path to the assignment when collecting submission files in assignment sub-folders, for example:

dict(
    file_id='data/sample.txt',
    student_id='hacker',
    timestamp='2017-01-30 15:30:10 UCT'
)

Creating a plugin

To add your own collector you can create a plugin class that inherits from FileNameCollectorPlugin. This class needs to only implement one method, which is the collect() method (see below). Let’s say you create your own plugin in the mycollector.py file, and your plugin is called MyCollector. Then, on the command line, you would run:

nbgrader zip_collect --collector=mycollector.MyCollector

which will use your custom collector rather than the built-in one.

API

class nbgrader.plugins.zipcollect.FileNameCollectorPlugin(**kwargs)

Submission filename collector plugin for the ZipCollectApp. Collect plugin subclasses MUST inherit from this class.

collect(submitted_file)

This is the main function called by the ZipCollectApp for each submitted file. Note this function must also return a dictionary or None for sub-classed plugins.

Parameters:

submitted_file (str) – Each submitted file in the extracted_directory (absolute path).

Returns:

Collected data from the filename or None if the file should be skipped. Collected data is a dict of the form:

{
    file_id: file_id,  # MUST be provided
    student_id: student_id,  # MUST be provided
    timestamp: timestamp  # Can optional be provided
}

Note: file_id MUST include the the relative path to the assignment if you are collecting files in assignment sub-folders.

Return type:

groupdict