Allow users to do a quiz by filling in gaps in an incomplete file

[inglesp]

This is an alternative to #2168.

We can provide a quiz-like experience by giving users an incomplete file with gaps for them to fill in. The file would look something like this:

from ehrql import quiz
from ehrql.tables.core import patients, clinical_events, medications

# Question 0: find the age of each patient on 1st January 2024
quiz.questions[0].check(patients.age_on("2024-01-01"))

# Question 1: find the number of medications given to each patient
quiz.questions[1].check(...)

# ...

quiz.summarise()

When they run the file, they would see output like:

Question 0: ☑
Question 1: ☒ The patient series you have provided has the wrong values for the following patients: 1, 3, 6
Question 2: ☐
Question 3: ☐

You have answered 1 question correctly, 1 incorrectly, and left 2 unanswered.

There is one line of output for every call to .check(), and one line from the call to .summarise().

The incomplete file can be included in the tutorial repo, so that users can do the quiz after they've done the tutorial.

To run the file, we should provide a VS Code command for users to run from the command palette and/or a button they can click on.

We should add a script to the scripts directory that produces the incomplete file, based on a list of questions that looks something like this, and which uses the answer-checking functionality in #2214.

questions = [
    Question(
        "find the age of each patient on 1st January 2024",
        patients.age_on("2024-01-01"),
    ),
    ...
]

Writing real questions is out of scope for this ticket.

[alarthast]

Slack conversation

Crude steps / thoughts towards implementing this (branch): Command

• [x] Get the opensafely exec ehrql:v1 quiz command (ehrql quiz in devenv) to print something (anything) to the terminal.
• [x] Like dump-example-data, have a dump-quiz-file command. First duplicate then refactor.
• [x] Allow an optional command line argument for quiz assuming that most users won't bother to change the default file name we give them.
• [x] With the above change, modify run_quiz to take a file path as an argument and run/import that file.
• [x] Clone the ehrQL tutorial locally and run ehrql quiz using the executable from the local ehrql repo on a file that prints hello world

Functionality

• [x] Write question.check(answer) that creates a sandbox engine (if one is not already provided) and calls check_answer.
• [x] Code a quiz.get_questions function with a boolean argument create_engine
• [x] In order to code the summarise function in Peter’s comment, create boolean properties called attempted and correct and have check update them.
• [x] Due to the above, with each run of the file, questions should be generated as fresh objects. Ensure this.
• [x] Allow answer=... to skip checking unattempted questions

Things to think about:

• Currently the things we import for users is manually written as strings.
  • Is there some way to detect the imports needed for each question from the model answers.
• Running a user-modified file might cause unexpected results.
  • At the very least if an error occurs, run_quiz should provide some helpful message.
  • Might be worth doing some regex/string manipulation to clean up the file. Not sure how this might be done yet.
  • Maybe run ruff on it? Is this too much?

[alarthast]

Closed by #2241