Library Reference

moodleteacher.assignments

Functionality dealing with Moodle assignments.

class moodleteacher.assignments.MoodleAssignment(course, assignment_id, course_module_id=None, duedate=None, cutoffdate=None, deadline=None, name=None, allows_feedback_comment=None)

A single Moodle assignment.

classmethod from_assignment_id(course, assignment_id)

Create a MoodleAssignment object just from an assignment ID.

classmethod from_course_module_id(course, course_module_id)

Create a MoodleAssignment object just from a course module ID.

classmethod from_raw_json(course, raw_json)

Create a MoodleAssignment object from raw JSON information.

get_user_submission(user_id, must_have_files=False)

Create a new MoodleSubmission object with the submission of the given user in this assignment, or None.

When must_have_files is set to True, only submissions with files are considered.

submissions(must_have_files=False)

Get a list of MoodleSubmission objects for this assignment.

class moodleteacher.assignments.MoodleAssignments(conn, course_filter=None, assignment_filter=None)

A list of MoodleAssignment instances.

moodleteacher.compiler

Functions dealing with the compilation of code.

moodleteacher.compiler.compiler_cmdline(compiler=['gcc', '-o', '{output}', '{inputs}'], output=None, inputs=None)

Determine the command-line to be run for a compiler execution.

Parameters:

• compiler (tuple) – A compiler definition. Predefined values are GCC, GPP, and JAVAC.
• output (str) – The file path for the compiler output.
• inputs (tuple) – A list of input files for the compiler.

moodleteacher.connection

A connection to a chosen Moodle server.

class moodleteacher.connection.MoodleConnection(moodle_host=None, token=None, interactive=False, is_fake=False, timeout=5)

A connection to a Moodle installation.

__init__(moodle_host=None, token=None, interactive=False, is_fake=False, timeout=5)

Configures a connection to a Moodle server.

Parameters:

• moodle_host – The base URL of the Moodle installation.
• token – The client security token for the Moodle API access.
• interactive (bool) – Prompt interactively for parameters, if needed.
• is_fake (bool) – Create fake connection for testing purposes.
• timeout (int) – Timeout for HTTP requests.

moodleteacher.courses

Functionality to deal with Moodle courses.

class moodleteacher.courses.MoodleCourse(conn, course_id, fullname='', shortname='')

A single Moodle course.

classmethod from_course_id(conn, course_id)

Create a MoodleCourse object just from a course ID.

classmethod from_raw_json(conn, raw_json)

Create a MoodleCourse object from raw JSON information.

get_folders()

Determine folders that are part of the course.

Returns:List of MoodleFolder objects.

get_group(group_id)

Determines the user group for a given group ID.

Returns:MoodleGroup object for this user id, or None if not known.

get_user(user_id)

Determine the user for a given user ID.

Returns:MoodleUser object for this user id, or None if not known.

get_user_grades(user_id)

Fetch grade table for this user, or all users, in the given course.

moodleteacher.exceptions

Defintion of common exceptions in MoodleTeacher.

exception moodleteacher.exceptions.JobException(info_student=None, info_tutor=None)

An exception that occured while using the Job API.

exception moodleteacher.exceptions.NestedException(instance, real_exception, output=None)

An exception occured while running the student program.

exception moodleteacher.exceptions.NoFilesException(info_student=None, info_tutor=None)

Indication that the student submission contains no files.

exception moodleteacher.exceptions.RunningProgramException(instance, output=None)

A problem that occured while running a student program.

Parameters:

• instance (RunningProgram) – The RunningProgram instance raising this issue.
• output (str) – All the output data being produced so far.

exception moodleteacher.exceptions.TerminationException(instance, real_exception, output=None)

exception moodleteacher.exceptions.TimeoutException(instance, real_exception, output=None)

exception moodleteacher.exceptions.ValidatorBrokenException(info_student=None, info_tutor=None)

Indication that the validator script is broken.

exception moodleteacher.exceptions.WrongExitStatusException(instance, expected, got=None, output=None)

moodleteacher.runnable

class moodleteacher.runnable.RunningProgram(name, arguments=[], working_dir='.', timeout=30, encoding=None)

A running program that you can interact with.

This class is a thin wrapper around the functionality of pexpect (http://pexpect.readthedocs.io/en/stable/overview.html).

name

The name of the binary that is executed.

Type:str

working_dir

The working directory to be used during execution.

Type:str

arguments

The command-line arguments being used for execution.

Type:tuple

__init__(name, arguments=[], working_dir='.', timeout=30, encoding=None)

Initialize a running program.

Parameters:

• name – The file path for the executable.
• arguments – The command-line arguments for the executable.
• working_dir – The current working directory when running the program.
• timeout – The timeout for program execution.
• encoding – The text encoding for the program output, e.g. ‘utf-8’. If this parameter is not set, then the output is interpreted as bytes.

expect_end()

Wait for the running program to finish.

Returns:A tuple with the exit code, as reported by the operating system, and the output produced.

expect_exitstatus(exit_status)

Wait for the running program to finish and expect some exit status.

Parameters:exit_status (int) – The expected exit status. Raises:WrongExitStatusException – The produced exit status is not the expected one.

expect_output(pattern, timeout=-1)

Wait until the running program performs some given output, or terminates.

Parameters:

• pattern – The pattern the output should be checked for.
• timeout (int) – How many seconds should be waited for the output.

The pattern argument may be a string, a compiled regular expression, or a list of any of those types. Strings will be compiled into regular expressions.

Returns:

The index into the pattern list. If the pattern was not a list, it returns 0 on a successful match.

Return type:

int

Raises:

• TimeoutException – The output did not match within the given time frame.
• TerminationException – The program terminated before producing the output.
• NestedException – An internal problem occured while waiting for the output.

get_exitstatus()

Get the exit status of the program execution.

Returns:

Exit status as reported by the operating system,

or None if it is not available.

Return type:int

get_output()

Get the program output produced so far.

Returns:Program output as text. May be incomplete. Return type:str

sendline(text)

Sends an input line to the running program, including os.linesep.

Parameters:

text (str) – The input text to be send.

Raises:

• TerminationException – The program terminated before / while / after sending the input.
• NestedException – An internal problem occured while waiting for the output.

moodleteacher.submissions

class moodleteacher.submissions.MoodleSubmission(conn=None, submission_id=None, assignment=None, user_id=None, group_id=None, status=None, gradingstatus=None, textfield=None, files=[])

A single student submission in Moodle.

classmethod from_local_file(assignment, fpath)

Creation of a local-only fake submission object. Mainly needed for the test suite.

load_feedback()

Retreives the current feedback for this submission from the Moodle server.

load_grade()

Loads the grade currently set for this assignment.

parse_plugin_json(raw_json)

Parses a plugin block from Moodle JSON and updates the object accordingly.

save_feedback(feedback)

Saves new feedback information on the Moodle server.

See also https://moodle.org/mod/forum/discuss.php?d=384108.

save_grade(grade, feedback=None)

Saves new grading information for this student on the Moodle server, and sets the workflow state to “graded”.

moodleteacher.validation

Implementation of validation jobs.

class moodleteacher.validation.Job(submission, validator_file, preamble)

A validation job checks a single student submission, based on a validator script written by the tutor.

Check the validation section in the moodleteacher documentation for more details.

__init__(submission, validator_file, preamble)

Prepares a validation job by putting all relevant files into a temporary directory.

submission

The student submission object.

Type:MoodleSubmission

validator_file

The validator file object.

Type:MoodleFile

preamble

The preamble text for each feedback message targeting students.

Type:str

ensure_files(filenames)

Checks the student submission for specific files.

Parameters:filenames (tuple) – The list of file names to be checked for. Returns:Indicator if all files are found in the student archive. Return type:bool

grep(regex)

Scans the student files for text patterns.

Parameters:regex (str) – Regular expression used for scanning inside the files. Returns:Names of the matching files in the working directory. Return type:tuple

prepare_student_files(remove_directories=True, recode=False)

Unarchive student files in temporary directory.

Parameters:

• remove_directories (boolean) – When the student submission is an archive, remove all contained directories and unpack flat. This makes sense for all but Java code. When the student submission is not an archive, this flag has no effect.
• recode (boolean) – Recode the submission files to UTF-8 text, to avoid compiler problems. When the student submission is an archive, this flag has no effect.

run_build(compiler=['gcc', '-o', '{output}', '{inputs}'], inputs=None, output=None, timeout=30)

Combined call of ‘configure’, ‘make’ and the compiler.

The success of ‘configure’ and ‘make’ is optional. The arguments are the same as for run_compiler.

run_compiler(compiler=['gcc', '-o', '{output}', '{inputs}'], inputs=None, output=None, timeout=30)

Runs a compiler in the working directory.

Parameters:

• compiler (tuple) – The compiler program and its command-line arguments, including placeholders for output and input files.
• inputs (tuple) – The list of input files for the compiler.
• output (str) – The name of the output file.

run_configure(mandatory=True, timeout=30)

Runs the ‘configure’ program in the working directory.

Parameters:mandatory (bool) – Throw exception if ‘configure’ fails or a ‘configure’ file is missing.

run_make(mandatory=True, timeout=30)

Runs the ‘make’ program in the working directory.

Parameters:mandatory (bool) – Throw exception if ‘make’ fails or a ‘Makefile’ file is missing.

run_program(name, arguments=[], timeout=30, encoding=None)

Runs a program in the working directory to completion.

Parameters:

• name (str) – The name of the program to be executed.
• arguments (tuple) – Command-line arguments for the program.
• timeout (int) – The timeout for execution.
• encoding (str) – The text encoding for the program output, e.g. ‘utf-8’. If this parameter is not set, then the output is interpreted as bytes.

Returns:

A tuple of the exit code, as reported by the operating system, and the output produced during the execution.

Return type:

tuple

send_fail_result(info_student, info_tutor='Test failed.')

Reports a negative result for this validation job.

Parameters:

• info_student (str) – Information for the student(s)
• info_tutor (str) – Information for the tutor(s)

send_pass_result(info_student='All tests passed. Awesome!', info_tutor='All tests passed.')

Reports a positive result for this validation job.

Parameters:

• info_student (str) – Information for the student(s)
• info_tutor (str) – Information for the tutor(s)

spawn_program(name, arguments=[], timeout=30, encoding=None)

Spawns a program in the working directory.

This method allows the interaction with the running program, based on the returned RunningProgram object.

Parameters:

• name (str) – The name of the program to be executed.
• arguments (tuple) – Command-line arguments for the program.
• timeout (int) – The timeout for execution.
• encoding (str) – The text encoding for the program output, e.g. ‘utf-8’. If this parameter is not set, then the output is interpreted as bytes.

Returns:

An object representing the running program.

Return type:

RunningProgram

start(log_level=20)

Execute the validate() method in the validator script belonging to this job.