API Reference

cleanupfiles

This module can be called to cleanup file names by removing version numbers.

It will remove the automatic version numbering applied by the Mac or PC OS when multiple copies of the same file are saved in a directory. This module assumes there are no duplicate file names in the current path. It can remove the numbering from all files with particular extensions in a directory. If called with a path as a command line argument, the file names in that directory will be cleaned. If called without a command line argument, the files in the current directory will be cleaned.

Example usage:

python cleanupfiles.py path/to/directory

python cleanupfiles.py # run on the current directory

python -m cleanupfiles path/to/directory

agrtool.cleanupfiles.clean_files(path=None)

Given a path to a folder of files, clean the file names

Get a list of all the file names in the folder. For files with extensions in the default list (or other supplied list), remove any occurrences of numbers added by Mac or PC, like FileName-1.java (Mac) becomes FileName.java or data (2).txt (PC) becomes data.txt. Rename the files in the folder with the cleaned names.

Parameters:

path (Path/str, optional) – a Path or str object that points to the folder where the file names are to be cleaned. If None, the current path is used. defaults to None

agrtool.cleanupfiles.clean_name(name, exts=['.java', '.py', '.txt', '.csv', '.c'])

Remove number versions automatically added to files on pc or Mac

When a file of the same name is saved in the same directory, a number is often added to the end of the name of the additional file(s). This can cause problems for Java class source code where the file and the class name need to match, or for programs that read in from data files but the data file no longer matches the hard-coded name due to the number being added to the file name.

Parameters:

• name (str) – Name of file

• exts (list, optional.) – List of extensions for which the file names should be cleaned of any numbers, defaults to ['.java', '.py', '.txt', '.csv', '.c'].

Returns:

A cleaned version of the name (without any number versions)

Return type:

str

combine_results

Create Gradescope-style of results.json results file.

Combine all results json files created by different processes into one singular results.json for Gradescope to read and create its autograder output.

This module looks through all json files in the Gradescope results folder, set within the checklocal module, to combine into one results json file. It looks to see if any of the files are called leaderboard.json and if so, includes the contents of that file in a separate leaderboard key of the json structure.

Example usage::

python combine_results.py

python -m combine_results

agrtool.combine_results.generate_results()

Create a summary results json for Gradescope from all results

Create a placeholder output that reports on compilation and running of the program. Then, loop through all the other (results) files in the results directory. If there are any results files aside from the leaderboard, remove the placeholder output and open the results file(s) and load them in. Ensure the json is correct. Add some general feedback or tips for students based on their overall score.

If there is a leaderboard file available, load it in as the leaderboard field contents.

Create a new json structure from all the available results and save it in a results file where Gradescope can find it.

Then, print out the history of submissions so it is available in the autograder results on the Gradescope site.

agrtool.combine_results.getdate(datestr)

Convert a Gradescope datetime stamp to a datetime object

This function takes in a string of a Gradescope datetime stamp (probably the submission time) and converts it into a datetime object, adds 3 hours (for US Eastern time) and then converts the datetime back to a string, formatted differently than the input.

Parameters:

datestr (str) – A string containing a datetime stamp

Returns:

A datetime string, formatted differently, representing the datetime from the string parameter (with three hours added for US East Coast time)

Return type:

str

agrtool.combine_results.getokjson(fname)

Cleans common escape-related errors from a json file

This function opens up a json file (fname), reads it in, and while there are any errors parsing the json content of the file, it checks the error location for any un-escaped or improperly escaped characters, swaps them out, and continues checking and swapping (up to 10 times). Then, it creates the json structure and returns that along with the (corrected) string input.

Parameters:

fname (str) – name of a json file

Returns:

a json structure, and stringified json

Return type:

json, str

agrtool.combine_results.lateness(f_results)

Computes the penalty for late submissions

Given the submission date(s) and the due date, calculates how much of a penalty to assess. If the student turns in their work before the due date, this function returns 0. If the student turned in multiple submissions, and the first one was before the due date but the latest one is after the due date, the student’s penalty will be smaller. The penalty is capped at 0.5.

Parameters:

f_results (dict) – a dictionary of Gradescope submission data

Returns:

size of the penality to assess, between 0 and 0.5

Return type:

float or int

agrtool.combine_results.makedate(datestr)

Convert a Gradescope datetime stamp to a datetime object

This function takes in a string of a Gradescope datetime stamp (probably the submission time) and converts it into a datetime object. It also adds 3 hours to account for the timezones (assuming the user is on US East Coast)

Parameters:

datestr (str) – A string containing a datetime stamp

Returns:

A datetime object representing the datetime from the string parameter

Return type:

datetime object

agrtool.combine_results.print_history(f_results)

Reads submission metadata, prints out all submission datetimes and points

Given a json structure (dict) read from a file of Gradescope submission metadata, this function extracts all submission datetimes and points achieved and prints them out, which can be collected into a hidden autograder listing to view while grading or reviewing submissions on the Gradescope site.

Parameters:

f_results (json) – a dict from a json file of Gradescope submission data

error_nocompile

Generate autograder output when compilation fails.

Produce a stock autograder output when files fail to compile. Include the compilation error message(s) for details.

agrtool.error_nocompile.check_compile()

Produce a result file with one failed test for compilation

If compiling the program produced a compile_errortester.txt file, there was a compilation error. This function will check for the file and if it finds the file, indicating an error, it will create a results file (for the autograder in Gradescope) to indicate the failure and will include the specific error message given.

error_nodriver

Generate autograder output when submission lacks client code.

Create a stock output for autograder when the student forgets to upload their client class.

agrtool.error_nodriver.check_client()

Produce a result file with one failed test for missing client

If an expected client file is missing, the program may not run. This function will check for the required file (driver) / class. If the file is not found, this function will create a results file (for the autograder in Gradescope) to indicate the failure.

error_norun

Create autograder output when the program produces a runtime exception.

Produce stock autograder output when a runtime error occurs. Include any error specifices in the output.

agrtool.error_norun.check_runtime()

Produce a result file with one failed test for program run

If the running of the program produced a test_error.txt file, there was a runtime error. This function will check for the file and if it finds the file, indicating an error, it will create a results file (for the autograder in Gradescope) to indicate the failure and will include the specific error message given.

guidance

Create strings of guidance for common autograder results

For each of the following variables, adjust the docstring to your liking; it will be imported by modules that refer to it when adding feedback for submitters to Gradescope assignments.

leaderboard

Create data for a leaderboard entry.

Creates a leaderboard (if desired). Modify the logic below to adjust the leaderboard categories and weighting. The combine_results.py module will incorporate the leaderboard logic below into its results.json as a separate key. When Gradescope receiveds a results.json with a ‘leaderboard’ key, it includes a leaderboard that is viewable to submitters.

agrtool.leaderboard.leaderboard()

Create a leaderboard json for use by Gradescope

For this submission, read in the submission_metadata.json created by Gradescope, get the submitters and their timeliness, and then create the leaderboard json structure and data, and write it out to leaderboard.json for Gradescope to create the leaderboard from.

rename_class

Correct class name errors.

Given an expected class name, rename the submitted file if its name does not match. Also rename any usages of the class name inside the file.

agrtool.rename_class.rename(file, realclass)

Renames a Java class and all usages within the class file

Given a desired filename, this function uses regex to find all usages of the class (declaration, instantiation) and the class header. It renames all of them to the realclass argument and then saves the updated file with the realclass file name.

Parameters:

• file (str) – name/path of the file to rename/fix naming

• realclass (str) – desired name of the class