agh

class agh.Assignment(assignment_directory: Path | None = None, *args, **kwargs)[source]

Represents an assignment. At its core, an assignment is a collection of required files and optional files, along with a name, and the submissions for that assignment. The submissions are stored in a list of Submission objects.

The assignment is also associated with tests to run on the submissions.

ASSIGNMENT_FILE_NAME = 'assignment.json'
AddSubmission(submission_file: Path, override_anon: bool | None = None, warning_callback: Callable[[str], None | Any] | None = None) → Submission[source]

Add a new submission to the assignment. :param submission_file: The path to the submission file to add. :param override_anon: If none then abide by the default for the assignment. If True then make it anonymous even if assignment is default non-anonymous. If False then make it non-anonymous even if assignment is default anonymous. :param warning_callback: A callback function to be called when a warning is encountered. :return: The new submission. :rtype: “Submission”

property GraderOptions: <property object at 0x7d66921c4630>
class LinkProto(*values)[source]
RAISE_ERROR = 0
SKIP_FILE = 1
PostProcessSubmission(submission_file: Path | Submission, exists_protocol: LinkProto = LinkProto.RAISE_ERROR, warning_callback: Callable[[str], None | Any] | None = None) → Submission[source]
property Submissions
__init__(assignment_directory: Path | None = None, *args, **kwargs)[source]

Create a new Assignment object.

See Assignment.load for loading an assignment from a JSON file.

Parameters:

  • assignment_directory – Path to the assignment directory root.

  • do – Assignment data object.

addOptionalFile(new_file: SubmissionFileData) → Assignment[source]

Adds a new optional file to the assignment.

Parameters:

new_file – The new optional file to add.

addRequiredFile(new_file: SubmissionFileData) → Assignment[source]

Adds a new required file to the assignment.

Parameters:

new_file – The new required file to add.

Returns:

This assignment object with the new required file added for chaining if desired.

property archive_dir: Path

Directory containing archived submission files.

property assignment_description_dir: Path

Directory containing files that describe the assignment. Instructors can use this to describe the assignment to students as the source of files posted in a LMS system.

This can be empty.

property complete_eval_dir: Path

Directory containing completed evaluation PDFs.

property course

The course name/number for the assignment.

createMissingDirectories()[source]

Create missing directories for the assignment.

property d2l_named_dir: Path

Directory containing de-anonymized files for D2L LMS (OAKS).

property eval_dir: Path

Directory containing submission evaluation files.

property file: Path | None
getMissingDirectories() → list[Path][source]

Get a list of missing directories for the assignment.

property grade_period
property graded_output_dir: Path

Directory containing graded files.

Directory containing files to link into submission directories.

Instructors should use this to link files into the submission directories that are needed to run the tests. This could include Makefiles that work with the build system, or headers that the students were not supposed to edit.

classmethod load(filepath: Path | None = None)[source]

Load an assignment from a JSON file or a directory.

These objects are stored in JSON files in the same directory as the assignment. They are intended to be short lived and dynamically loaded from any sub-directory. Therefore, if you pass in a directory, this will look for the JSON file in that directory and it’s parents.

Parameters:

filepath – Path to the JSON file or directory containing the assignment data.

Raises:

FileNotFoundError – If the file or directory does not exist.

Returns:

The loaded assignment object.

property name
property optional_files
postProcessSubmissionRender(submission: Submission, warning_callback: Callable[[str], None | Any] | None = None) → Submission[source]
property required_files
property root_directory: Path

The root directory of the assignment.

save(filepath: Path | None = None, indent: int = 2)[source]
property tests_dir: Path

Directory containing test files suitable for use with pytest that test the submissions of the assignment.

This directory MUST contain some files. It may just be a single file named _options.default_test_file_name. It could also contain multiple test files that work in combination to test the submissions.

property unprocessed_dir: Path

Directory containing unprocessed submission files.

property year
class agh.OutputSectionData(*, path: pathlib.Path, title: str = '', type: str = 'default', include_in_output: bool = True, description: str = '', unlisted: bool = False, copy_to_sub_if_missing: bool = True, text: str = '', instructor_section: bool = False, heading_level: int = 2, included_files: list[agh.agh_data.SubmissionFileData] = <factory>, included_sections: list['OutputSectionData'] = <factory>, only_output_if_data: bool = False, post_script: str = '', _errors: list[dict[typing.Literal['title', 'message'], str]] = <factory>, _warnings: list[dict[typing.Literal['title', 'message'], str]] = <factory>)[source]
__init__(*, path: ~pathlib.Path, title: str = '', type: str = 'default', include_in_output: bool = True, description: str = '', unlisted: bool = False, copy_to_sub_if_missing: bool = True, text: str = '', instructor_section: bool = False, heading_level: int = 2, included_files: list[~agh.agh_data.SubmissionFileData] = <factory>, included_sections: list[~agh.agh_data.OutputSectionData] = <factory>, only_output_if_data: bool = False, post_script: str = '', _errors: list[dict[~typing.Literal['title', 'message'], str]] = <factory>, _warnings: list[dict[~typing.Literal['title', 'message'], str]] = <factory>) → None
addError(error_title: str, error_msg: str) → Self[source]
addSection(section: OutputSectionData) → Self[source]
addWarning(warn_title: str, warn_msg: str) → Self[source]
asQmdSection() → str[source]
property hasData
heading_level: int = 2
included_files: list[SubmissionFileData]
included_sections: list[OutputSectionData]
instructor_section: bool = False
only_output_if_data: bool = False
post_script: str = ''
text: str = ''
class agh.Submission(**kwargs)[source]

Represents a submission to an assignment.

This class should be subclassed to represent different submission types (zip, tar, etc.). The class maintains an evaluation directory for the submission, compiles source code from the submission in this directory, and stores information about the submission.

The source files are stored in the ‘as_submitted’ directory, and required files are copied to the evaluation directory. This is so the evaluator can fix any compilation errors before testing the submission, but the submission documentation will still reflect the original submission files.

Perhaps in the future the documentation will automatically reflect a git diff between the original submission and any necessary changes made during testing.

AS_SUBMITTED_DIR_NAME = 'as_submitted'
SUBMISSION_FILE_NAME = 'submission.json'
__init__(**kwargs)[source]

Get an object instance representing a submission to an assignment.

See load for loading a submission from a JSON file. See new for creating a brand-new submission from a submission file.

Parameters:

  • assignment – This is the assignment this submission belongs to.

  • kwargs – Keyword arguments to initialize the Submission object.

addError(key: str, txt_or_markdown: str) → Submission[source]

Add an error to the submission. These are NOT testing errors, but anything preventing the submission from being tested.

addWarning(key: str, txt_or_markdown: str) → Submission[source]

Add a warning to the submission. These are NOT testing warnings, but anything possibly preventing the submission from being tested.

property as_submitted_dir

The directory where the submission files are stored.

The contents of this directory are copied to the root of the evaluation directory. This is so the evaluator can fix any compilation errors before testing the submission, but the submission file contents printed in the output will still reflect the original submission files.

check_missing_files(assignment: Assignment) → list[Path][source]

Check if the submission is missing required files. :param assignment: The assignment this submission belongs to. :return: A list of missing required file names, or an empty list if the submission is missing no required files.

delError(key: str) → Submission[source]
delWarning(key: str) → Submission[source]
property errors: None | list[str]

Check if the submission has errors. These are NOT testing errors, but anything preventing the submission from being tested.

fix(assignment: Assignment)[source]

Try to fix errors in the submission directory.

classmethod get_anon_name(assignment: Assignment, submission_file: Path)[source]

Generate an anonymous name for the submission.

Parameters:

  • assignment (Assignment) – The assignment this submission belongs to

  • submission_file (pathlib.Path) – Path to the submission file

Returns:

str – Anonymous name for the submission

classmethod load(filepath: Path | None = None)[source]

Load a submission from a JSON file or a directory.

These objects are stored in JSON files in the same directory as the assignment. They are intended to be short lived and dynamically loaded from any sub-directory. Therefore, if you pass in a directory, this will look for the JSON file in that directory and it’s parents.

Parameters:

filepath – Path to the JSON file or directory containing the assignment data.

Raises:

FileNotFoundError – If the file or directory does not exist.

Returns:

The loaded assignment object.

property main_output_files: list[Path | None]

Return the submission’s output files. :return: A list of output files as follows: [<main-output-file-where-rendered>, <output-file-with-anon-name-in-output-directory>, <output-file-with-anon-name-in-GRADED-output-directory>, <output-file-with-NON-anon-name-in-output-directory>]

property name

The name of the submission.

classmethod new(assignment: Assignment, submission_file: Path, override_anon: bool | None = None)[source]

_Submission.new: Create a brand-new submission from a submission file.

Create a brand-new submission from a submission file.

save() → Self[source]
property warnings: None | list[str]

Check if the submission has warnings. These are NOT testing warnings, but anything possibly preventing the submission from being tested.

class agh.SubmissionFileData(*, path: pathlib.Path, title: str = '', type: str = 'default', include_in_output: bool = True, description: str = '', unlisted: bool = False, copy_to_sub_if_missing: bool = True)[source]
__init__(*, path: Path, title: str = '', type: str = 'default', include_in_output: bool = True, description: str = '', unlisted: bool = False, copy_to_sub_if_missing: bool = True) → None
property anchorText: str

Returns the anchor text for the section suitable in use for Markdown links.

asQmdSection(heading_level: int, max_file_size: int = 20480) → str[source]
copy_to_sub_if_missing: bool = True
description: str = ''
include_in_output: bool = True
path: Path
property sectionAttr: str
title: str = ''
type: str = 'default'
unlisted: bool = False
agh.start(args)[source]