Collect assignments from archives (zip files).
Options
-------
Arguments that take values are actually convenience aliases to full
Configurables, whose aliases are listed on the help line. For more information
on full configurables, see '--help-all'.
--debug
set log level to DEBUG (maximize logging output)
--force
Force overwrite of existing files.
-f
Force overwrite of existing files.
--strict
Skip submitted notebooks with invalid names.
--log-level=<Enum> (Application.log_level)
Default: 30
Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
Set the log level by value or name.
--extractor=<Type> (ZipCollectApp.extractor_plugin)
Default: 'nbgrader.plugins.zipcollect.ExtractorPlugin'
The plugin class for extracting the archive files in the
`archive_directory`.
--collector=<Type> (ZipCollectApp.collector_plugin)
Default: 'nbgrader.plugins.zipcollect.FileNameCollectorPlugin'
The plugin class for processing the submitted file names after they have
been extracted into the `extracted_directory`.
--zip_ext=<List> (ExtractorPlugin.zip_ext)
Default: ['.zip', '.gz']
List of valid archive (zip) filename extensions to extract. Any archive
(zip) files with an extension not in this list are copied to the
`extracted_directory`.
Class parameters
----------------
Parameters are set from command-line arguments of the form:
`--Class.trait=value`. This line is evaluated in Python, so simple expressions
are allowed, e.g.:: `--C.a='range(3)'` For setting C.a=[0,1,2].
NbGrader options
----------------
--NbGrader.answer_yes=<Bool>
Default: False
Answer yes to any prompts.
--NbGrader.config_file=<Unicode>
Default: ''
Full path of a config file.
--NbGrader.config_file_name=<Unicode>
Default: ''
Specify a config file to load.
--NbGrader.generate_config=<Bool>
Default: False
Generate default config file.
--NbGrader.log_datefmt=<Unicode>
Default: '%Y-%m-%d %H:%M:%S'
The date format used by logging formatters for %(asctime)s
--NbGrader.log_format=<Unicode>
Default: '[%(name)s]%(highlevel)s %(message)s'
The Logging format template
--NbGrader.log_level=<Enum>
Default: 30
Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
Set the log level by value or name.
--NbGrader.logfile=<Unicode>
Default: ''
Name of the logfile to log to. By default, log output is not written to any
file.
CourseDirectory options
-----------------------
--CourseDirectory.assignment_id=<Unicode>
Default: ''
The assignment name. This MUST be specified, either by setting the config
option, passing an argument on the command line, or using the --assignment
option on the command line.
--CourseDirectory.autograded_directory=<Unicode>
Default: 'autograded'
The name of the directory that contains assignment submissions after they
have been autograded. This corresponds to the `nbgrader_step` variable in
the `directory_structure` config option.
--CourseDirectory.course_id=<Unicode>
Default: ''
A key that is unique per instructor and course. This can be specified,
either by setting the config option, or using the --course option on the
command line.
--CourseDirectory.db_assignments=<List>
Default: []
A list of assignments that will be created in the database. Each item in the
list should be a dictionary with the following keys:
- name
- duedate (optional)
The values will be stored in the database. Please see the API documentation
on the `Assignment` database model for details on these fields.
--CourseDirectory.db_students=<List>
Default: []
A list of student that will be created in the database. Each item in the
list should be a dictionary with the following keys:
- id
- first_name (optional)
- last_name (optional)
- email (optional)
The values will be stored in the database. Please see the API documentation
on the `Student` database model for details on these fields.
--CourseDirectory.db_url=<Unicode>
Default: ''
URL to the database. Defaults to sqlite:///<root>/gradebook.db, where <root>
is another configurable variable.
--CourseDirectory.directory_structure=<Unicode>
Default: '{nbgrader_step}/{student_id}/{assignment_id}'
Format string for the directory structure that nbgrader works over during
the grading process. This MUST contain named keys for 'nbgrader_step',
'student_id', and 'assignment_id'. It SHOULD NOT contain a key for
'notebook_id', as this will be automatically joined with the rest of the
path.
--CourseDirectory.feedback_directory=<Unicode>
Default: 'feedback'
The name of the directory that contains assignment feedback after grading
has been completed. This corresponds to the `nbgrader_step` variable in the
`directory_structure` config option.
--CourseDirectory.groupshared=<Bool>
Default: False
Make all instructor files group writeable (g+ws, default g+r only) and
exchange directories group readable/writeable (g+rws, default g=nothing only
) by default. This should only be used if you carefully set the primary
groups of your notebook servers and fully understand the unix permission
model. This changes the default permissions from 444 (unwriteable) to 664
(writeable), so that other instructors are able to delete/overwrite files.
--CourseDirectory.ignore=<List>
Default: ['.ipynb_checkpoints', '*.pyc', '__pycache__', 'feedback']
List of file names or file globs. Upon copying directories recursively,
matching files and directories will be ignored with a debug message.
--CourseDirectory.include=<List>
Default: ['*']
List of file names or file globs. Upon copying directories recursively, non
matching files will be ignored with a debug message.
--CourseDirectory.max_file_size=<Int>
Default: 100000
Maximum size of files (in kilobytes; default: 100Mb). Upon copying
directories recursively, larger files will be ignored with a warning.
--CourseDirectory.notebook_id=<Unicode>
Default: '*'
File glob to match notebook names, excluding the '.ipynb' extension. This
can be changed to filter by notebook.
--CourseDirectory.release_directory=<Unicode>
Default: 'release'
The name of the directory that contains the version of the assignment that
will be released to students. This corresponds to the `nbgrader_step`
variable in the `directory_structure` config option.
--CourseDirectory.root=<Unicode>
Default: ''
The root directory for the course files (that includes the `source`,
`release`, `submitted`, `autograded`, etc. directories). Defaults to the
current working directory.
--CourseDirectory.source_directory=<Unicode>
Default: 'source'
The name of the directory that contains the master/instructor version of
assignments. This corresponds to the `nbgrader_step` variable in the
`directory_structure` config option.
--CourseDirectory.student_id=<Unicode>
Default: '*'
File glob to match student IDs. This can be changed to filter by student.
Note: this is always changed to '.' when running `nbgrader assign`, as the
assign step doesn't have any student ID associated with it. With `nbgrader
submit`, this instead forces the use of an alternative student ID for the
submission. See `nbgrader submit --help`.
If the ID is purely numeric and you are passing it as a flag on the command
line, you will need to escape the quotes in order to have it detected as a
string, for example `--student=""12345""`. See:
https://github.com/jupyter/nbgrader/issues/743
for more details.
--CourseDirectory.student_id_exclude=<Unicode>
Default: ''
Comma-separated list of student IDs to exclude. Counterpart of student_id.
This is useful when running commands on all students, but certain students
cause errors or otherwise must be left out. Works at least for autograde,
generate_feedback, and release_feedback.
--CourseDirectory.submitted_directory=<Unicode>
Default: 'submitted'
The name of the directory that contains assignments that have been submitted
by students for grading. This corresponds to the `nbgrader_step` variable in
the `directory_structure` config option.
ExtractorPlugin options
-----------------------
--ExtractorPlugin.force=<Bool>
Default: False
Force overwrite of existing files.
--ExtractorPlugin.zip_ext=<List>
Default: ['.zip', '.gz']
List of valid archive (zip) filename extensions to extract. Any archive
(zip) files with an extension not in this list are copied to the
`extracted_directory`.
FileNameCollectorPlugin options
-------------------------------
--FileNameCollectorPlugin.named_regexp=<Unicode>
Default: ''
This regular expression is applied to each submission filename and MUST be
supplied by the instructor. This regular expression MUST provide the
`(?P<student_id>...)` and `(?P<file_id>...)` named group expressions.
Optionally this regular expression can also provide the
`(?P<first_name>...)`, `(?P<last_name>...)`, `(?P<email>...)`, and
`(?P<timestamp>...)` named group expressions. For example if the filename
is:
`ps1_bitdiddle_attempt_2016-01-30-15-00-00_problem1.ipynb`
then this `named_regexp` could be:
".*_(?P<student_id>\w+)_attempt_(?P<timestamp>[0-9\-]+)_(?P<file_id>\w+)"
For named group regular expression examples see
https://docs.python.org/3/howto/regex.html
--FileNameCollectorPlugin.valid_ext=<List>
Default: ['.ipynb']
List of valid submission filename extensions to collect. Any submitted file
with an extension not in this list is skipped.
ZipCollectApp options
---------------------
--ZipCollectApp.answer_yes=<Bool>
Default: False
Answer yes to any prompts.
--ZipCollectApp.archive_directory=<Unicode>
Default: 'archive'
The name of the directory that contains assignment submission files and/or
archives (zip) files manually downloaded from a LMS. This corresponds to the
`collect_step` variable in the `collect_structure` config option.
--ZipCollectApp.collect_directory_structure=<Unicode>
Default: '{downloaded}/{assignment_id}/{collect_step}'
Format string for the directory structure that nbgrader works over during
the zip collect process. This MUST contain named keys for 'downloaded',
'assignment_id', and 'collect_step'.
--ZipCollectApp.collector_plugin=<Type>
Default: 'nbgrader.plugins.zipcollect.FileNameCollectorPlugin'
The plugin class for processing the submitted file names after they have
been extracted into the `extracted_directory`.
--ZipCollectApp.config_file=<Unicode>
Default: ''
Full path of a config file.
--ZipCollectApp.config_file_name=<Unicode>
Default: ''
Specify a config file to load.
--ZipCollectApp.downloaded_directory=<Unicode>
Default: 'downloaded'
The main directory that corresponds to the `downloaded` variable in the
`collect_structure` config option.
--ZipCollectApp.extracted_directory=<Unicode>
Default: 'extracted'
The name of the directory that contains assignment submission files
extracted or copied from the `archive_directory`. This corresponds to the
`collect_step` variable in the `collect_structure` config option.
--ZipCollectApp.extractor_plugin=<Type>
Default: 'nbgrader.plugins.zipcollect.ExtractorPlugin'
The plugin class for extracting the archive files in the
`archive_directory`.
--ZipCollectApp.force=<Bool>
Default: False
Force overwrite of existing files.
--ZipCollectApp.generate_config=<Bool>
Default: False
Generate default config file.
--ZipCollectApp.log_datefmt=<Unicode>
Default: '%Y-%m-%d %H:%M:%S'
The date format used by logging formatters for %(asctime)s
--ZipCollectApp.log_format=<Unicode>
Default: '[%(name)s]%(highlevel)s %(message)s'
The Logging format template
--ZipCollectApp.log_level=<Enum>
Default: 30
Choices: (0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL')
Set the log level by value or name.
--ZipCollectApp.logfile=<Unicode>
Default: ''
Name of the logfile to log to. By default, log output is not written to any
file.
--ZipCollectApp.strict=<Bool>
Default: False
Skip submitted notebooks with invalid names.
Examples
--------
Collect assignment submissions from files and/or archives (zip) files
manually downloaded from a LMS. For the usage of instructors.
This command is run from the top-level nbgrader folder. In order to
facilitate the collect process, nbgrader places some constraints on how
the manually downloaded archive (zip) files must be structured. By
default, the directory structure must look like this:
{downloaded}/{assignment_id}/{collect_step}
where `downloaded` is the main directory, `assignment_id` is the name
of the assignment and `collect_step` is the step in the collect
process.
Manually downloaded assignment submissions files and/or archives (zip)
files must be placed in the `archive_directory`:
{downloaded}/{assignment_id}/{archive_directory}
It is expected that the instructor has already created this directory
and placed the downloaded assignment submissions files and/or archives
(zip) files in this directory.
Archive (zip) files in the `archive_directory` will be extracted, and
any non-archive files will be copied, to the `extracted_directory`:
{downloaded}/{assignment_id}/{extracted_directory}
After which the files in the `extracted_directory` will be collected
and copied into the students `submitted_directory`:
{submitted_directory}/{student_id}/{assignment_id}/{notebook_id}.ipynb
By default the collection of files in the `extracted_directory` is
managed via the :class:`~nbgrader.plugins.zipcollect.FileNameCollectorPlugin`
plugin. Each filename is sent to the plugin, which in turn returns an
object containing the `student_id`, `file_id`, `first_name`,
`last_name`, `email`, and `timestamp` data. For more information run:
nbgrader zip_collect --help-all
To change the default plugin, you will need a class that inherits from
:class:`~nbgrader.plugins.zipcollect.FileNameCollectorPlugin`. If your
collector is named `MyCustomCollector` and is saved in the file
`mycollector.py`, then:
nbgrader zip_collect --collector=mycollector.MyCustomCollector