Skip to content

Questions

Utilities for dealing with questions.

from prairielearn import ...

PartialScore

A class with type signatures for the partial scores dict.

For more information see the element developer guide.

Attributes:

Name Type Description
score float | None

The score for the partial score.
weight NotRequired[int]

The weight of the partial score.
feedback NotRequired[str | dict[str, str] | Any]

Feedback for the partial score. Typically used by elements.

QuestionData

The data dictionary passed to the question element throughout the lifecycle of the question.

For more information see the element developer guide.

Attributes:

Name Type Description
params dict[str, Any]

Parameters that describe the question variant.
preferences dict[str, Any]

Preferences for the question variant. These can be set to different values in different assessments.
correct_answers dict[str, Any]

The true answer (if any) for the variant.
submitted_answers dict[str, Any]

The answer submitted by the student (after parsing).
format_errors dict[str, Any]

Any errors encountered while parsing the student input.
partial_scores dict[str, PartialScore]

Partial scores for individual variables in the question.
score float

The total final score for the question.
feedback dict[str, Any]

Any feedback to the student on their submitted answer.
variant_seed str

The random seed for this question variant.
options dict[str, Any]

Any options associated with the question.
raw_submitted_answers dict[str, Any]

The answer submitted by the student before parsing.
editable bool

Whether the question is currently in an editable state.
panel Literal['question', 'submission', 'answer']

The panel that is being rendered.
correct_answer_shown bool

Whether the correct answer is currently shown to the student.
extensions dict[str, Any]

A list of extensions that are available to be loaded by this element.
num_valid_submissions int

The number of valid submissions by the student for the current variant.
manual_grading bool

Whether manual-grading content should be shown.
ai_grading bool

Whether the question is being rendered for AI grading.
gradable bool

Whether the submission can be graded.
answers_names dict[str, bool]

A dictionary whose keys list the names of the answers in the question.

ai_grading instance-attribute 

ai_grading: bool

Whether the question is being rendered for AI grading.

answers_names instance-attribute 

answers_names: dict[str, bool]

A dictionary whose keys list the names of the answers in the question.

correct_answer_shown instance-attribute 

correct_answer_shown: bool

Whether the correct answer (in the answer panel) is currently shown to the student.

correct_answers instance-attribute 

correct_answers: dict[str, Any]

The true answer (if any) for the variant.

editable instance-attribute 

editable: bool

Whether the question is currently in an editable state.

extensions instance-attribute 

extensions: dict[str, Any]

A list of extensions that are available to be loaded by this element.

feedback instance-attribute 

feedback: dict[str, Any]

Any feedback to the student on their submitted answer. Elements will never read or write to this dictionary, with the exception of the <pl-external-grader-results> element.

format_errors instance-attribute 

format_errors: dict[str, Any]

A dictionary of format errors encountered while parsing the student input.

gradable instance-attribute 

gradable: bool

Whether the submission can be graded. Automatically set to False if there are format errors.

manual_grading instance-attribute 

manual_grading: bool

Whether manual-grading content should be shown. This is true in the manual grading view, and also for question and answer panels when rendered for AI grading.

num_valid_submissions instance-attribute 

num_valid_submissions: int

The number of valid (not containing format errors) submissions by the student for the current variant.

options instance-attribute 

options: dict[str, Any]

Any options associated with the question.

panel instance-attribute 

panel: Literal['question', 'submission', 'answer']

The panel that is being rendered.

params instance-attribute 

params: dict[str, Any]

Parameters that describe the question variant.

partial_scores instance-attribute 

partial_scores: dict[str, PartialScore]

A dictionary of partial scores for each answer in the question.

preferences instance-attribute 

preferences: dict[str, Any]

Preferences for the question variant. These can be set to different values in different assessments.

raw_submitted_answers instance-attribute 

raw_submitted_answers: dict[str, Any]

The answer submitted by the student before parsing.

score instance-attribute 

score: float

The total final score for the question.

submitted_answers instance-attribute 

submitted_answers: dict[str, Any]

The answer submitted by the student (after parsing).

variant_seed instance-attribute 

variant_seed: str

The random seed for this question variant.

add_files_format_error 

add_files_format_error(
    data: QuestionData, error: str
) -> None

Add a format error to the data dictionary.

Examples:

>>> add_files_format_error(data, f"Missing baz in foo.txt")
>>> data["format_errors"]
{"_files": ["Missing baz in foo.txt"]}

add_submitted_file 

add_submitted_file(
    data: QuestionData,
    file_name: str,
    base64_contents: str | None = None,
    *,
    raw_contents: str | bytes | bytearray | None = None,
    mimetype: str | None = None,
) -> None

Add a submitted file to the data dictionary.

Raises:

Type Description
ValueError

If neither base64_contents nor raw_contents is provided.

Examples:

>>> add_submitted_file(data, "foo.txt", "base64-contents", mimetype="text/plain")
>>> data["submitted_answers"]
{"_files": [{"name": "foo.txt", "contents": "base64-contents", "mimetype": "text/plain"}]}
>>> add_submitted_file(data, "bar.txt", raw_contents="raw contents")
>>> data["submitted_answers"]
{"_files": [{"name": "foo.txt", "contents": "base64-contents", "mimetype": "text/plain"},
            {"name": "bar.txt", "contents": "cmF3IGNvbnRlbnRz"}]}

all_partial_scores_correct 

all_partial_scores_correct(data: QuestionData) -> bool

Check if all partial scores are close to 1.

Returns:

Type Description
bool

True if all scores are close to 1 and not an empty list, False otherwise.

Examples:

>>> data = {"partial_scores": {"foo":{"score": 1.0}}}
>>> all_partial_scores_correct(data)
True
>>> data = {"partial_scores": {"foo": {"score": 1.0}, "bar": {"score": 0.5}}}
>>> all_partial_scores_correct(data)
False

set_all_or_nothing_score_data 

set_all_or_nothing_score_data(data: QuestionData) -> None

Give points to main question score if all partial scores are correct.

Examples:

>>> data = {"partial_scores": {"foo": {"score": 1.0}, "bar": {"score": 1.0}}}
>>> set_all_or_nothing_score_data(data)
>>> data["score"]
1.0
>>> data = {"partial_scores": {"foo": {"score": 1.0}, "bar": {"score": 0.5}}}
>>> set_all_or_nothing_score_data(data)
>>> data["score"]
0.0

set_weighted_score_data 

set_weighted_score_data(
    data: QuestionData, weight_default: int = 1
) -> None

Set overall question score to be weighted average of all partial scores. Use weight_default to fill in a default weight for a score if one is missing.

Raises:

Type Description
ValueError

If any of the partial scores have a score of None.

Examples:

>>> data = {
...     "partial_scores": {
...         "foo": {"score": 0.5, "weight": 1},
...         "bar": {"score": 0.8, "weight": 2}
...     }
... }
>>> set_weighted_score_data(data)
>>> data["score"]
0.7