Documentation

class ygrader.grader.Grader(lab_name: str, class_list_csv_path: Path, work_path: Path = pathlib.Path.cwd() / 'temp')

Grader class

Parameters:

lab_name (str) – Name of the lab/assignment that you are grading (ie. ‘lab3’). This is used for logging messages and passed back to your callback functions.
class_list_csv_path (pathlib.Path) – Path to CSV file with class list exported from LearningSuite. You need to export netid, first and last name columns.
work_path (pathlib.Path) – Path to directory where student files will be placed. For example, if you pass in ‘.’, then student code would be placed in ‘./lab3’. By default the working path is a “temp” folder created in your working directory.

add_item_to_grade(item_name, grading_fcn, deductions_yaml_path, *, grading_fcn_args_dict=None, max_points=None)

Add a new item you want to grade.

Parameters:

grading_fcn (Callable) –
The callback function that will perform all your grading work. Your callback function will be provided with the following arguments:
- lab_name (str): This will pass back the lab name you passed to __init__. Useful if you use the same callback function to grade multiple different assignments.
- item_name (str): The name of the item being graded (e.g., “answers.txt”).
- student_code_path (pathlib.Path): The location where the unzipped/cloned student files are stored.
- points (int): The maximum number of points possible for the item being graded, used for validating the grade when prompting the user to input a grade. If your callback function automatically calcuates and returns a grade, this argument is ignored.
- first_names: (list(str)) First name(s) of students in the group
- last_names: (list(str)) Last name(s) of students in the group
- net_ids: (list(str)) Net ID(s) of students in the group.
- build: (bool) Whether files should be built/compiled.
- run: (bool) Whether milestone should be run.
In addition, if your grades CSV exported from Learning Suite has the following information, it will also be provided to your callback function:
- section: (str) Student section number, assuming ‘Section Number’ was contained in grades_csv exported from Learning Suite.
- homework_id: (str) Student homework ID, assuming ‘Course Homework ID’ was contained in grades_csv exported from Learning Suite.
Your callback should return None or an int/float. If you return None, then the user will be prompted to input a grade. If you already know the grade you want to assign, and don’t want to prompt the user, return the grade value. If feedback is enabled, return a tuple of (score, feedback).

If there’s a problem with the student’s submission and you want to skip them, then raise CallbackFailed. You can provide an argument to this exception with any error message you want printed.

Since your callback functions will be provided with many arguments, it’s best to use keyword arguments:
```
def my_callback(**kw):
    lab_name = kw["lab_name"]
    first_name = kw["first_names"][0]
```
deductions_yaml_path (pathlib.Path) – Path to the YAML file for storing deductions and tracking grading status.
grading_fcn_args_dict (dict) – (Optional) A dictionary of additional arguments that will be passed to your grading function.
max_points (int) – (Optional) Number of max points for the graded column.

add_item_to_grade_from_config(grade_item_config, grading_fcn)

Add a new item to grade using a GradeItemConfig object.

This is a convenience method that extracts all necessary information from a GradeItemConfig object and calls add_item_to_grade.

Parameters:

grade_item_config (GradeItemConfig) – The configuration object for the grade item, containing points, feedback_path, and other_data.
grading_fcn (Callable) – The callback function that will perform the grading work. See add_item_to_grade for details on the callback function signature.

run(): Call this to start (or resume) the grading process

set_learning_suite_groups(csv_path, col_name='group')

This function is used to provide treams to the grader when grading a team-based assignment from Learning Suite. (If grading from Github, the Github URL will be used to determine teams)

Parameters:

csv_path (str) – The path to a CSV file containing group names. This CSV file must have a column called ‘Net ID’.
col_name (str) – The column name in the CSV file that indicates the group name.

set_other_options(*, format_code=False, build_only=False, run_only=False, allow_rebuild=False, allow_rerun=True, prep_fcn=None, dry_run_first=False, dry_run_all=False, workflow_hash=None, parallel_workers=None, show_completion_menu=True)

This can be used to set other options for the grader.

Parameters:

format_code (bool) – Whether you want the student code automatically formatted using clang-format
build_only (bool) – Whether you only want to build and not run/grade the students code. This will be passed to your callback function, and is useful for labs that take a while to build. You can build all the code in one pass, then return and grade the code later.
run_only (bool) – Whether you only want to run/grade and not build the students code. This will be passed to your callback function, and is useful for labs that take a while to build. You can build all the code in one pass, then return and grade the code later. When using GitHub submissions, this will skip fetching/cloning repositories and assume they already exist in a good state. If a student’s repository does not exist, an error will be reported and that student will be skipped.
allow_rebuild (bool) – By default, the program will pass build=True and run=True to your callback on the first invocation, and then allow the grader the option to “re-run” the student’s code, where build=False and run=True would be provided. If you want to allow the grader to specifically request a rebuild, set this to True (default False).
allow_rerun (bool) – By default, the program will pass build=True and run=True to your callback on the first invocation, and then allow the grader the option to “re-run” the student’s code, where build=False and run=True would be provided. If your grader can’t rerun without rebuilding, then set this to False (default True).
prep_fcn (Callable) – If you are grading multiple items, then you can use this optional callback to do any one-time prep work. This callback is provided the same arguments as the grading callback function, except for cols_to_grade and max_points. You should not return any value from this callback, but you can raise CallbackFailed to skip the student.
dry_run_first (bool) – Perform a dry run, calling your callback function to perform grading, but not updating the grades CSV file. The callback is only run for the first student.
dry_run_all (bool) – Perform a dry run, calling your callback function to perform grading, but not updating the grades CSV file. The callback is run for each student.
workflow_hash (str) – (Optional) Expected hash of the GitHub workflow file. If provided, the workflow file will be verified before grading each student. If the hash doesn’t match, a warning will be displayed indicating the student may have modified the workflow system.
parallel_workers (int or None) – If set to an integer, process students in parallel using that many workers. Only works with build_only mode since interactive grading cannot be parallelized. Default is None (sequential processing).
show_completion_menu (bool) – Whether to show the completion menu when all students are graded. Default is True.

set_submission_system_github(tag, github_url_csv_path, repo_col_name='github_url', *, use_https=False, build_from_classroster=None)

Call this function if you are using student submissions on Github.

Parameters:

tag (str) – The tag on the students github repository that is used for the submission.
github_url_csv_path (pathlib.Path | str) – The path to a CSV file containing student Github repository URLs. This CSV file must have a column called ‘Net ID’. The repos can be listed as an http:// address or in SSH format (git@). They will be coverted as needed depending on the use_https argument.
repo_col_name (str) – The column name in the CSV file that contains the Github URLs.
use_https (bool) – By default SSH will be used to clone the student repos. If you want to use an access token or stored credentials over https, set this to True.
build_from_classroster ((str, str)) – If the CSV file does not contain the github URLs, but instead contains a class roster from Git Classroom, then this should provide the organization and classroom prefix name to build the github URLs.

set_submission_system_learning_suite(zip_path)

Call this function if you are using student submissions from Learning Suite.

Parameters:: zip_path (pathlib.Path | str) – Path to the zip file that was downloaded from Learning Suite using Batch Download.