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)[source]

“ 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()[source]

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

inginious_container_api.input.get_submission_time()[source]

Returns the submission time of the current submission

inginious_container_api.input.get_username()[source]

Returns the username of the current user being graded

inginious_container_api.input.parse_template(input_filename, output_filename='')[source]

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()[source]

Returns the dictionary containing the feedback

inginious_container_api.feedback.save_feedback(rdict)[source]

Save feedback file

inginious_container_api.feedback.set_custom_value(custom_name, custom_val)[source]

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)[source]

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)[source]

Set global feedback in case of error

inginious_container_api.feedback.set_global_result(result)[source]

Set global result value

inginious_container_api.feedback.set_grade(grade)[source]

Set global grade of this job

inginious_container_api.feedback.set_problem_feedback(feedback, problem_id, append=False)[source]

Set problem specific feedback

inginious_container_api.feedback.set_problem_result(result, problem_id)[source]

Set problem specific result value

inginious_container_api.feedback.set_state(state)[source]

Set the task state

inginious_container_api.feedback.set_tag(tag, value)[source]

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)[source]

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, both_dockers)[source]

Allow to transfer signals

inginious_container_api.run_student.create_student_socket(both_dockers)[source]

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, both_dockers)[source]

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 If the grading or the student container is on Kata, there is nothing to do, the information is directly sent to the agent from the student_container

inginious_container_api.run_student.handle_stdin(stdin, student_container_id)[source]

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='')[source]

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')[source]

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, both_dockers)[source]

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)[source]

Ask the docker agent to create the student container

Unlink unneeded files

inginious_container_api.run_student.wait_until_finished(both_dockers, zmq_socket, stdin, stdout, stderr, student_container_id)[source]

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)[source]

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)[source]

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

inginious_container_api.rst.get_codeblock(language, text)[source]

Generates rst codeblock for given text and language

inginious_container_api.rst.get_imageblock(filename, format='')[source]

Generates rst raw block for given image filename and format

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

Indent (or de-indent) text

Language management

inginious_container_api.lang.get_lang_dir_path()[source]
inginious_container_api.lang.init()[source]

Install gettext with the default parameters