API documentation

Module contents

class quizpy.Calculated(title: str, text: str, default_points: float, format: str = 'html', id: int = None, tags: Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: List[quizpy.common.InlineFile] = <factory>, units: List[Tuple[str, float]] = <factory>, units_left: bool = False, unit_grading_type: quizpy.numerical.UnitGradingType = <UnitGradingType.NO_PENALTY: 0>, unit_behaviour: quizpy.numerical.UnitBehaviour = <UnitBehaviour.NoUnits: 3>, unit_penalty: float = 0.1, wildcards: List[quizpy.numerical.Wildcard] = <factory>, accepted_answers: List[quizpy.numerical.CalculatedAnswer] = <factory>)

Bases: Question

class quizpy.CalculatedAnswer(text: str, fraction: float, feedback: str = '', format: str = 'html', tolerance: float = 0.0, tolerance_type: quizpy.numerical.ToleranceType = <ToleranceType.RELATIVE: 1>, answer_format: quizpy.numerical.CalculatedAnswerFormat = <CalculatedAnswerFormat.DECIMAL_PLACES: 1>, precision: int = 2)

Bases: Choice

class quizpy.Category(name: str, description: str = '', questions: ~typing.List[~quizpy.common.Question] = <factory>, format: str = 'html')

Bases: object

Represents a group of questions within one XML-file.

Parameters

  • name (str) – The category name that will be displayed in Moodle.

  • description (str) – A long formatted description of the content.

  • format (str) – The format used to render the description. Can either be html (default), markdown, plain_text or moodle_auto_format.

class quizpy.Choice(text: str, fraction: float, feedback: str = '', format: str = 'html')

Bases: object

Represents an answer option in a Multiple Choice question or a Short Answer question.

Parameters

  • text (str) – The source text to be rendered for this answer option.

  • fraction (float) – The fraction of the total points to be given for this answer as percentage between 0 and 100.

  • feedback (str) – Specific feedback for choosing this answer option

  • format – format for rendering both answer text and feedback. Can either be html (default), markdown, plain_text or moodle_auto_format.

to_cloze() → str

Renders a cloze version of this choice. This method is called by the applicable question classes and should not be used directly.

Returns

A Cloze-representation of this choice.

Return type

str

class quizpy.Cloze(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>)

Bases: Question

The question text will be rendered using the custom Cloze syntax. See https://docs.moodle.org/310/en/Embedded_Answers_(Cloze)_question_type.

You can also use the to_cloze() functions of the relevant question classes to generate the syntax for you.

class quizpy.DDImage(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, base_image: ~typing.Optional[~quizpy.common.InlineFile] = None, options: ~typing.List[~quizpy.drag.DragOption] = <factory>, drops: ~typing.List[~quizpy.drag.DropZone] = <factory>, shuffle: bool = False)

Bases: Question

This question type allows a student to drop answers on custom-placed fields on a background image.

Parameters

  • base_image (quizpy.InlineFile) –

    an InlineFile instance that serves as the background to the question.

    Attention

    Although this (for technical reasons) defaults to None you need to provide a background image before you can call to_xml()!

  • shuffle – If True, drag options will be sorted randomly each time the question is presented.

add_dropzone(location: Tuple[int, int], correct_choice: DragOption, text: str = '') → DropZone

Adds an DropZone to the DDImage question and returns the newly created instance.

Parameters

  • location (Tuple[int, int]) – x,y coordinates of the drop zone relativ to the top left corner of the base image.

  • correct_choice – a reference to the DragOption that represents the correct answer for this field.

Attention

choice must be a valid reference to a DragOption in DDImage.options

Parameters

text –

Note

TODO: Find out what this actually does. It is visible in the editor but seemingly not in the question?!

add_option(text: str, group: int = 1, infinite: bool = False) → DragOption

Adds an DragOption to the DDImage question and returns the newly created instance.

Parameters

  • text (str) – The text on the box. This is treated as plain text without any markup.

  • group (str) – Options can be grouped so that options with the same group number have the same shape that is also represented in the DropZone, i.e. DragOptions can only be dragged on DropZones whos DragOption is in the same group.

  • infinite (bool) – If True the option can be placed on an infinite number of DropZones.

class quizpy.DDText(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, options: ~typing.List[~quizpy.drag.DragOption] = <factory>, shuffle: bool = False)

Bases: Question

This question type allows a student to drop answers on gaps in a given text.

Gaps in the question text are created by using [[n]] references, where n is the 1-based index of the options.

Parameters

shuffle – If True, drag options will be sorted randomly each time the question is presented.

add_option(text: str, group: int = 1, infinite: bool = False) → DragOption

Adds an DragOption to the DDImage question and returns the newly created instance.

Parameters

  • text (str) – The text on the box. This is treated as plain text without any markup. No line breaks!

  • group (str) – Options can be grouped so that options with the same group number have the same color that is also represented in the gap.

  • infinite (bool) – If True the option can be placed on an infinite number of DropZones.

class quizpy.Description(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>)

Bases: Question

Dummy question type with no grading e.g. to establish some context for further questions.

class quizpy.DragOption(text: str, group: int = 1, infinite: bool = False)

Bases: object

Represents an answering option box to be placed on a DropZone within a DDImage.

Parameters

  • text (str) – The text on the box. This is treated as plain text without any markup.

  • group (str) – Options can be grouped so that options with the same group number have the same shape that is also represented in the DropZone, i.e. DragOptions can only be dragged on DropZones whos DragOption is in the same group.

  • infinite (bool) – If True the option can be placed on an infinite number of DropZones.

class quizpy.DropZone(location: Tuple[int, int], choice: DragOption, text: str = '')

Bases: object

Represents a box in which a user can drop an answer on in a DDImage question.

Parameters

  • location (Tuple[int, int]) – x,y coordinates of the drop zone relativ to the top left corner of the base image.

  • choice (DragOption) –

    a reference to the DragOption that represents the correct answer for this field.

    Attention

    choice must be a valid reference to a DragOption in DDImage.options

  • text –

    Note

    TODO: Find out what this actually does. It is visible in the editor but seemingly not in the question?!

class quizpy.Essay(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, grading_info: str = '', response_format: str = 'editor', response_required: bool = True, response_template: str = '', attachements_required: bool = False, max_attachements: int = 0, max_lines: int = 15)

Bases: Question

Question with free-form multiline text answer that must be graded manually.

Note

Moodle allows you to restrict file types of attachements. However, we do not fully understand how this works yet.

Parameters

  • grading_info (str) – Text to be displayed for the grader (students will never see this) e.g. to establish rules for grading. Will be formatted in the question format.

  • response_format (str) –

    Defines how a student can provide an answer. Can be one of the following options:

    • ”editor”: Standard HTML editor (with possibility to add pictures)

    • ”editorfilepicker”: Same as editor but with file upload option

    • ”plain”: Unformatted plain text input.

    • ”monospaced”: Unformatted plain text input in monospace font.

    • ”noinline”: No text input field. This requires attachements_required = True and max_attachments > 0.

  • response_required (bool) – If True, a student must enter some text before submitting the answer.

  • response_template (str) – A formatted text that is automatically entered as a template for the student.

  • attachements_required (bool) – If True, a student must submit a file before submitting the answer.

  • max_attachements (int) – The maximum number of attachements a student can supply for an answer.

  • max_lines (int) – The maximum number of lines of text an answer can have.

class quizpy.InlineFile(name: str, file: BinaryIO)

Bases: object

Helper class to attach and reference files directly in the XML file.

Parameters

  • name (BinaryIO) – Name of the file including the file extension.

  • file – File-like object to read data from. Must be opened in binary mode.

Returns a string that Moodle can use to reference the file. Useful for e.g. links to pictures.

Return type

str

classmethod load(path: str)

Open a file in binary-mode and use the file handle to instantiate an InlineFile.

to_xml() → Element

Reads the file and turns it into file node in XML. If the file is seekable it will be read from the start.

class quizpy.Matching(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, shuffle: bool = True, pairs: ~typing.List[~typing.Tuple[~typing.Optional[str], str]] = <factory>)

Bases: Question

Match drop-down menu items to the correct text.

Parameters

shuffle (bool) – If True, items will be shuffled.

add_pair(text: Optional[str], answer: str)

Adds a matching pair to the question. If the text parameter is None a decoy option is added.

Parameters

  • text (str) – The first element of the pair, displayed as normal text.

  • answer – The corresponding match to the text shown as drop-down menu item.

class quizpy.MultiTrueFalse(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, scoring_method: str = 'subpoints', shuffle: bool = True, options: ~typing.List[str] = <factory>, statements: ~typing.List[~typing.Tuple[str, str, str]] = <factory>)

Bases: Question

Question, which displays a column of statements, which can be answered in a binary fashion (usually True/False).

Parameters

  • scoring_method (str) – Can either be “subpoints” for partial points or “mtfonezero” for all-or-nothing scoring.

  • shuffle (bool) – If True, statements will be displayed randomly.

  • options (List[str]) – A list answering options for each statement. Defaults to [“Wahr”, “Falsch”].

add_statement(text: str, value: str, feedback: str = '')

Adds a True/False statement to the question.

Parameters

  • text (str) – Text of the statement to be shown. Will be formatted in the format of the question itself.

  • value (str) – The correct value out of the available choices in self.options.

  • feedback (str) – Feedback to be shown after the answer was submitted. Will be rendered in the question format.

Raises

ValueError – if value is not an answering option

class quizpy.MultipleChoice(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, shuffle: bool = True, single: bool = False, numbering: str = 'abc', choices: ~typing.List[~quizpy.multipe_choice.Choice] = <factory>, correct_feedback: str = 'Die Antwort ist richtig.', partial_feedback: str = 'Die Antwort ist teilweise richtig.', incorrect_feedback: str = 'Die Antwort ist falsch.')

Bases: Question

Standard Multiple choice question.

Parameters

  • shuffle (bool) – If True then answers will be shuffled every time they are presented in the quiz.

  • single (bool) – If True then only a single answer can be selected.

  • numbering (str) – Number answers with lowercase letters (“abc”), uppercase (“ABC”) or with integers (“123”)

  • correct_feedback (str) – Feedback given for a fully correct answer (100%).

  • partial_feedback (str) – Feedback given for a partially correct answer (<100%).

  • incorrect_feedback (str) – Feedback given for a wrong answer (0%).

add_choice(text: str, fraction: float, feedback: str = '', format: str = 'html')

Convenience method to add a choice to the question.

Parameters

  • text (str) – The source text to be rendered for this answer option.

  • fraction (float) – The fraction of the total points to be given for this answer as percentage between 0 and 100.

  • feedback (str) – Specific feedback for choosing this answer option

  • format – format for rendering both answer text and feedback. Can either be html (default), markdown, plain_text or moodle_auto_format.

Returns

The newly added choice.

Return type

Choice

to_cloze(weight: int, display_type: str = 'dropdown', alignment: str = 'horizontal', shuffle: bool = False) → str

Renders a MC question in Cloze format to be used as an inline question.

Parameters

  • weight (int) – The weight of the question in the total sum of all inline questions.

  • display_type (str) – Determines how the question is rendered. Can either be “dropdown”, “radio” or “checkbox”.

  • alignment (str) – If the display_type is “radio” or “checkbox” then you can choose between “horizontal” and “vertical” display of the radio buttons / checkboxes.

  • shuffle (bool) – If True the choices will be shuffled.

class quizpy.Numerical(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, accepted_answers: ~typing.List[~quizpy.numerical.NumericalAnswer] = <factory>, units: ~typing.List[~typing.Tuple[str, float]] = <factory>, units_left: bool = False, unit_grading_type: ~quizpy.numerical.UnitGradingType = UnitGradingType.NO_PENALTY, unit_behaviour: ~quizpy.numerical.UnitBehaviour = UnitBehaviour.NoUnits, unit_penalty: float = 0.1)

Bases: Question

A question with a one-line answering option that should be a number with optional units.

Parameters

  • units_left (bool) – If True, Moodle will try to parse the unit on the left side of the number e.g. $1.

  • unit_grading_type (UnitBehaviour) –

    Determines the grading for using possibly the wrong unit:

    UnitGradingType.NO_PENALTY

    No penalty is applied for not using the base unit / no unit at all.

    Caution

    This does not imply unit_behaviour = UnitBehaviour.Optional. If unit_behaviour = UnitBehaviour.Force Moodle just ignores this setting on import and assumes a penalty.

    UnitGradingType.FRAC_RESPONSE_GRADE

    A fraction of the grade given for this particular answer is deducted from the total grade. Implies unit_behaviour = UnitBehaviour.Force

    UnitGradingType.FRAC_TOTAL_GRADE

    A fraction of the total grade is deducted. Implies unit_behaviour = UnitBehaviour.Force

    Note

    The penalty is applied when

    1. Using a unit that has a multiplier other than 1.

    2. Using a unit that was not defined

    3. Not using a unit at all

  • unit_behaviour –

    Determines if and how units are used in the question:

    UnitBehaviour.Optional

    Units can be used but if no unit is provided the base unit is assumed

    UnitBehaviour.Force

    Units must be provided.

    UnitBehaviour.NoUnits

    No units are used in the question

  • unit_penalty (float) – The fractional penalty between 0 and 1. This is only used if unit_behaviour = UnitBehaviour.Force

add_answer(number: float, fraction: float, feedback: str = '', format: str = 'html', tolerance: float = 0.0) → NumericalAnswer

Convenience method to add a NumericalAnswer :param number: The correct number (assume the base unit in case that units are used). :type number: float

Parameters

  • fraction (float) – The fraction of the total points to be given for this answer as percentage between 0 and 100.

  • feedback (str) – Specific feedback for choosing this answer option

  • format – format for rendering both answer text and feedback. Can either be html (default), markdown, plain_text or moodle_auto_format.

add_unit(unit: str, conversion_factor: float)

Convenience method to add a unit.

Parameters

  • unit (str) – A string representing the unit. .. note:: Due to this bug <https://tracker.moodle.org/browse/MDL-69597> we strip the whitespaces before adding it to the list.

  • conversion_factor –

    The factor that is applied before comparing it with the correct answer.

    Note

    If you use units you should always add at least one option with conversion factor = 1.0 so that your unit will be accepted as the correct unit.

to_cloze(weight: int)

Turns this question into its Cloze syntax representation to be used in a Cloze question text.

class quizpy.NumericalAnswer(text: str, fraction: float, feedback: str = '', format: str = 'html', tolerance: float = 0.0)

Bases: Choice

A Choice sub-class with added tolerance for Numerical questions.

Parameters

tolerance – The absolute tolerance that a students answer is allowed to deviate from the correct value. .. note:: In case you use units the tolerance is assumed to be in the base unit and is converted accordingly.

to_cloze() → str

Converts answer into cloze representation. Do not use directly. This used by Numerical.to_cloze().

class quizpy.Question(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>)

Bases: ABC

Abstract base class for all question types.

Parameters

  • title (str) – The question title

  • text (str) – The full question text in its raw form.

  • default_points (float) – The base number of points given for this question. This can be scaled in the actual quiz on moodle.

  • format (str) – The format of the question text. Can either be html (default), markdown, plain_text or moodle_auto_format.

  • id (int) – Apparently moodle supports some kind of questions identifiers. We have no idea, how.

  • tags (Iterable[str]) – A set of tags to group questions by. Unfortunately, not yet fully supported in moodle.

  • penalty (float) – A penalty factor for in case of retries. Only applies if retry is possible for the quiz.

  • hidden (bool) – A marker to prevent ‘old’ questions from being displayed in the category.

  • general_feedback (bool) – Feedback that will be shown after the question was answered (but during the quiz!). Will be rendered in the same format as the question text.

  • files (List[InlineFile]) – A list of InlineFiles that can be referenced in the question text (e.g. pictures).

generate_common_xml(qtype: str) → Element

Generates XML node with attributes common to all question types.

Parameters

qtype (str) – the XML-question type

class quizpy.Quiz(categories: List[quizpy.common.Category] = <factory>)

Bases: object

class quizpy.ShortAnswer(title: str, text: str, default_points: float, format: str = 'html', id: ~typing.Optional[int] = None, tags: ~typing.Iterable[str] = <factory>, penalty: float = 0.0, hidden: bool = False, general_feedback: str = '', files: ~typing.List[~quizpy.common.InlineFile] = <factory>, case_sensitive: bool = False, accepted_answers: ~typing.List[~quizpy.multipe_choice.Choice] = <factory>)

Bases: Question

Question type asking for a one-line answer.

Parameters

case_sensitive (bool) – If True, the given answer must match the solution exactly.

add_answer(text: str, fraction: float, feedback: str = '', format: str = 'html') → Choice

Convenience method to add an answer to the question.

The answer itself is the same Choice object that MultipleChoice questions use.

Parameters

  • text (str) – The source text to be rendered for this answer option.

  • fraction (float) – The fraction of the total points to be given for this answer as percentage between 0 and 100.

  • feedback (str) – Specific feedback for choosing this answer option

  • format – format for rendering both answer text and feedback. Can either be html (default), markdown, plain_text or moodle_auto_format.

Returns

The newly added Choice object.

Return type

quizpy.Choice

to_cloze(weight: int) → str

Renders a ShortAnswer question in Cloze format to be used as an inline question.

Parameters

weight (int) – The weight of the question in the total sum of all inline questions.

class quizpy.UnitBehaviour(value)

Bases: Enum

An enumeration.

class quizpy.UnitGradingType(value)

Bases: Enum

An enumeration.