The inginious_container_api package (commands inside containers)

This package contains all methods accessible from inside the containers.

In the default shell of the `run` scripts, all these function are included in the global namespace.

Gathering the student’s input

inginious_container_api.input.get_input(problem)

“ Returns the specified problem answer in the form problem: problem id Returns string, or bytes if a file is loaded

inginious_container_api.input.get_lang()

Returns the language of the current user (as a two-character ISO-639-1 code) being graded

inginious_container_api.input.get_submission_time()

Returns the submission time of the current submission

inginious_container_api.input.get_username()

Returns the username of the current user being graded

inginious_container_api.input.parse_template(input_filename, output_filename='')

Parses a template file Replaces all occurences of @@problem_id@@ by the value of the ‘problem_id’ key in data dictionary

input_filename: file to parse output_filename: if not specified, overwrite input file

Feedback

inginious_container_api.feedback.get_feedback()

Returns the dictionary containing the feedback

inginious_container_api.feedback.save_feedback(rdict)

Save feedback file

inginious_container_api.feedback.set_custom_value(custom_name, custom_val)

Set a custom value to be given back in the feedback :type custom_name: :param custom_name: name/key of the entry to be placed in the custom dict :type custom_val: :param custom_val: content of the entry to be placed in the custom dict

inginious_container_api.feedback.set_feedback_from_tpl(tpl_name, parameters, problem_id=None, append=False)

Parse a template, using the given parameters, and set it as the feedback message.

tpl_name must indicate a file. Given that XX_XX is the lang code of the current user (‘en_US’ or ‘fr_FR’, for example), this function will search template file in different locations, in the following order: - [current_dir]/tpl_name.XX_XX.tpl - [task_dir]/lang/XX_XX/tpl_name.tpl (this is the preferred way, as it contributes to store all translations in the same folder) - [current_dir]/tpl_name.tpl

Note that you can indicate “../otherdir/mytpl” to force the function to search in the “../otherdir” directory. Simply omit the final “.tpl”.

If no file is found or a parsing exception occured, an error is displayed as feedback message, and False is returned. If everything went well, True is returned.

The parsing uses Jinja2.

Parameters is a dictionnary that will be given to the Jinja template.

inginious_container_api.feedback.set_global_feedback(feedback, append=False)

Set global feedback in case of error

inginious_container_api.feedback.set_global_result(result)

Set global result value

inginious_container_api.feedback.set_grade(grade)

Set global grade of this job

inginious_container_api.feedback.set_problem_feedback(feedback, problem_id, append=False)

Set problem specific feedback

inginious_container_api.feedback.set_problem_result(result, problem_id)

Set problem specific result value

inginious_container_api.feedback.set_state(state)

Set the task state

inginious_container_api.feedback.set_tag(tag, value)

Set the tag ‘tag’ to the value True or False. :type value: :param value: should be a boolean :type tag: :param tag: should be the id of the tag. Can not starts with *auto-tag-

inginious_container_api.feedback.tag(value)

Add a tag with generated id. :type value: :param value: everything working with the str() function

Running subcontainers

inginious_container_api.run_student.allow_to_send_signals(signal_handler_callback, connection, student_container_id)

Allow to transfer signals

inginious_container_api.run_student.create_student_socket()

Create a socket for the grading - student containers communication. Only used when both are using docker runtimes

inginious_container_api.run_student.handle_ssh(ssh, connection, student_container_id)

If ssh is required and both containers are on docker runtime, get the id and password (generated by the student_container) and sent them to the agent.

inginious_container_api.run_student.handle_stdin(stdin, student_container_id)

Read the specified stdin and send content to the student container

inginious_container_api.run_student.run_student(cmd, container=None, time_limit=0, hard_time_limit=0, memory_limit=0, share_network=False, working_dir=None, stdin=None, stdout=None, stderr=None, signal_handler_callback=None, ssh=False, start_student_as_root=False, teardown_script='')

Run a command inside a student container

Parameters:

• cmd – command to be ran (as a string, with parameters). If ssh is set to True, this command will be run before launching the ssh server acting as a setup script.

• container – container to use. Must be present in the current agent. By default it is None, meaning the current container type will be used.

• time_limit – time limit in seconds. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container timeout!)

• hard_time_limit – hard time limit. By default it is 0, which means that it will be the same as the current container (NB: it does count in the “host” container hard timeout!)

• memory_limit – memory limit in megabytes. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container memory limit!)

• share_network – share the network with the host container if True. Default is False.

• working_dir – The working directory for the distant command. By default, it is os.getcwd().

• stdin – File descriptor for stdin. Can be None, in which case a file descriptor is open to /dev/null.

• stdout – File descriptor for stdout. Can be None, in which case a file descriptor is open to /dev/null.

• stderr – File descriptor for stderr. Can be None, in which case a file descriptor is open to /dev/null.

• signal_handler_callback – If not None, run will call this callback with a function as single argument. this function can itself be called with a signal value that will immediately be sent to the remote process. See the run_student script command for an example, or the hack_signals function below.

• ssh – If set to True, it starts an ssh server for the student after the command finished.

• start_student_as_root – If set to True, it tries to execute the command as root (for ssh, it accepts connection as root). Default is False. This is a Beta feature and should not be used yet.

• teardown_script – command to be ran (as a string, with parameters) in the student container before closing it. This parameter is mainly useful when ssh is set to True.

:remark Calling run_student on a grading container running as root with Kata is not a possible feature yet. :return: the return value of the calling process. There are special values:

• 251 means that run_student is not available in this container/environment

• 252 means that the command was killed due to an out-of-memory

• 253 means that the command timed out

• 254 means that an error occurred while running the proxy

inginious_container_api.run_student.run_student_simple(cmd, cmd_input=None, container=None, time_limit=0, hard_time_limit=0, memory_limit=0, share_network=False, working_dir=None, stdout_err_fuse=False, text='utf-8')

A simpler version of run, which takes an input string and return the output of the command. This disallows interactive processes.

Parameters:

• cmd – cmd to be run.

• cmd_input – input of the command. Can be a string or a bytes object, or None.

• container – container to use. Must be present in the current agent. By default it is None, meaning the current container type will be used.

• time_limit – time limit in seconds. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container timeout!)

• hard_time_limit – hard time limit. By default it is 0, which means that it will be the same as the current container (NB: it does count in the “host” container hard timeout!)

• memory_limit – memory limit in megabytes. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container memory limit!)

• share_network – share the network with the host container if True. Default is False.

• working_dir – The working directory for the distant command. By default, it is os.getcwd().

• stdout_err_fuse – Weither to fuse stdout and stderr (i.e. make them use the same file descriptor)

• text – By default, run_simple assumes that stdout/stderr will be encoded in UTF-8. Putting another encoding will make the streams encoded using this encoding. text=False indicates that the streams should be opened in binary mode. In this case, run_simple returns streams in the form of binary, unencoded, strings.

Returns:

The output of the command, as a tuple of objects (stdout, stderr, retval). If stdout_err_fuse is True, the output is in the form (stdout, retval) is returned. The type of the returned strings (stdout, stderr) is dependent of the text arg.

inginious_container_api.run_student.send_initial_command(socket_id, server, stdin, stdout, stderr, zmq_socket, student_container_id, cmd, teardown_script, working_dir, ssh, user)

Send the commands (aka: student code) to be run in the student container

inginious_container_api.run_student.start_student_container(container, time_limit, hard_time_limit, memory_limit, share_network, socket_id, ssh, run_as_root)

Ask the docker agent to create the student container

inginious_container_api.run_student.unlink_unneeded_files(socket_path, path)

Unlink unneeded files

inginious_container_api.run_student.wait_until_finished(zmq_socket, stdin, stdout, stderr, student_container_id)

Dynamically handle stdin, stdout and stderr while waiting for final message

inginious_container_api.ssh_student.ssh_student(setup_script=None, memory_limit=0, hard_time_limit=0, time_limit=0, container=None, run_as_root=False, teardown_script=None)

If a command is specified, runs it in a student container. Then gives ssh access to that container to the student. The student has 2 min to connect (copy paste the ssh command shown) otherwise it will timeout. Note this feature requires to allow internet access during connection (within the environment configuration tab).

Parameters:

• setup_script – command to be ran (as a string, with parameters) before launching the ssh server. This command, in the case of a script, is allowed to start new subprocess. If you want subprocess to run in background while the student has ssh access, pay attention to launch them in a non-blocking way. In the case of script files, it is recommended to put them in the student/scripts directory since this specific subdirectory will be isolated from the student

• memory_limit – memory limit in megabytes. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container memory limit!).

• hard_time_limit – hard time limit. By default it is 0, which means that it will be the same as the current container (NB: it does count in the “host” container hard timeout!).

• time_limit – time limit in seconds. By default it is 0, which means that it will be the same as the current container (NB: it does not count in the “host” container timeout!).

• container – container to use. Must be present in the current agent. By default it is None, meaning the current container type will be used.

• run_as_root – If set to True, try to give root access to the student via ssh. Default is False. This feature is still in Beta and should not be used for now.

• teardown_script – command to be ran (as a string, with parameters) in the student container after the student closed the ssh session. In the case of script files, it is recommended to put them in the student/scripts directory since this specific subdirectory will be isolated from the student

RST helpers

inginious_container_api.rst.get_admonition(cssclass, title, text)

Generates rst admonition block given a bootstrap alert css class, title, and text

inginious_container_api.rst.get_codeblock(language, text)

Generates rst codeblock for given text and language

inginious_container_api.rst.get_imageblock(filename, format='')

Generates rst raw block for given image filename and format

inginious_container_api.rst.indent_block(amount, text, indent_char='\t')

Indent (or de-indent) text

Language management

inginious_container_api.lang.get_lang_dir_path()

inginious_container_api.lang.init()

Install gettext with the default parameters