Building an exercise
This chapter follows one new exercise from idea to published documentation, then covers the harder cases: exercises with settings, with a staff, a keyboard, a second row of buttons, or a note to place. The short version of the steps is in For developers; here are the reasons.
What an exercise is
An Exercise is a small class with four attributes and one method that matter. Everything else comes from the framework.
name, category, description |
What the home screen and the sidebar show. The category groups exercises. |
par_seconds |
How long a good first answer takes. The scheduler judges speed against it. |
generate(rng) |
Returns one Question. This is the whole of the exercise. |
settings_signature() |
Only for exercises with settings (see below). |
A Question says everything about one question. Its fields are the whole vocabulary of what the screen can show:
| Field | Meaning |
|---|---|
prompt |
The text above the question (may be empty). |
choices |
The answer buttons, in order. |
answer |
The right answer; it must be one of choices. |
staff |
Notes to draw: a list of chords, each a list of Notes. Empty for no staff. |
clef, key, value |
The clef, the key signature (sharps positive, flats negative) and the note value to draw. |
keyboard, key_staff, keyboard_range |
Highlight a piano key instead of drawing a staff; optionally with a small key signature above; and the range of keys to draw. |
octaves, second_label, joiner |
A two-part answer: a choice, then one of a second row of buttons (“C” then “4” gives “C4”). |
construct, accidentals |
A “place this note” question: the answer is a position on a clickable staff, not a button. |
grid |
Where to put each button, as (row, column), instead of one row. |
explanation |
Text shown after the answer says why it is right. |
Because an exercise only fills in a Question, it never touches Qt.
A complete example
We will add “Sharps and flats”: it names a major key and asks how many sharps or flats it has. This code runs as written.
import random
from alto.exercises.base import (
Exercise,
Question,
register,
)
from alto.theory.scales import (
MAJOR_KEYS,
format_key_signature,
)
@register
class SharpsAndFlats(Exercise):
name = "Sharps and flats"
category = "Notation"
description = "How many sharps or flats does a major key have?"
par_seconds = 4.0
def generate(self, rng: random.Random) -> Question:
count = rng.randint(-7, 7) # -7 flats ... +7 sharps
return Question(
f"How many sharps or flats are in {MAJOR_KEYS[count]} major?",
choices=[format_key_signature(n) for n in range(-7, 8)],
answer=format_key_signature(count),
explanation=f"{MAJOR_KEYS[count]} major has {format_key_signature(count)}.",
)
To try it without the program, in a Python session:
>>> q = SharpsAndFlats().generate(random.Random(1))
>>> q.prompt, q.answer
('How many sharps or flats are in D♭ major?', '5 flats')
and to see it in a window:
from PySide6.QtWidgets import QApplication
from alto.ui.exercise_view import ExerciseView
app = QApplication([])
view = ExerciseView(SharpsAndFlats(), rng=random.Random(1))
view.show()
app.exec()
Things to notice:
rngis an argument, not a global. The exercise never callsrandom.randint. That is what makes the example above repeatable and the exercise testable with a seed.@registerputs the class inREGISTRYnext to the other exercises of itscategory, so the home screen and the sidebar list it with them, whatever order the file is written in. Pick an existing category or invent a new one.- Choices must be unique and the answer must be one of them. A test,
test_every_exercise_generates_valid_questions, draws 300 questions from every registered exercise and checks both. A new exercise is covered the moment it is registered. - Distractors. The wrong answers matter as much as the right one.
pick_distractors(correct, pool=..., n=..., rng=...)inbase.pyreturns the right answer shuffled in withnothers drawn from a pool; use it, or write your own, with plausible wrong answers (for intervals: the neighbouring qualities, not random words). A question where only one answer is conceivable teaches nothing. - Where the logic lives. Anything about music itself (spelling, intervals, scales) belongs in
alto/theory/, with tests, and is used by the exercise. If yourgeneratecontains theory, move it.
Calibrating par_seconds
par_seconds is the time a fluent person takes to answer correctly the first time. The scheduler rewards answers at half par
or faster and penalises answers over four times par. Too small and everything looks slow, so strain rises for everyone; too large
and nothing is ever rewarded. A good method: answer fifty questions yourself in a row, at the speed you would call “fluent”, and
take the median of your answer times (the statistics page shows the median per exercise). The existing exercises run from 3 seconds
(naming a note) to 9 (naming an arpeggio’s type and inversion); scale spelling is 8. See Spaced repetition.
Adding settings to an exercise
If users should be able to change what is asked, there are four more places to touch. The NoteNames exercise is the model.
- A settings object in
alto/settings.py: a dataclass with the fields and the rules about them, and a module-level instance (note_names = NoteNameSettings()). Keep it free of Qt and of saving. - The exercise reads it when it generates a question:
settings.note_names.active_clefs(). Because the instance is shared, a change takes effect on the next question. - A signature. Override
settings_signature()to returnsignature(settings.note_names, ...). This is what stops a stored question from coming back under settings it was not made for. It is the step people forget, and nothing fails visibly: old questions simply reappear when they should not. - A panel and persistence in
alto/ui/settings_panel.py: a panel class (a subclass ofExerciseSettingsPanelthat emitschangedwhen something is edited),load_*andsave_*functions that read and writeQSettingsthroughstore()withtext_valueandint_value, a branch insettings_panel_for, and a call to yourload_*inMainWindow.__init__so settings are restored at start. The screen connectschangedtonext_question, so edits apply at once.
The panel is the largest piece of code in the program, and that is mostly widgets: copy a panel with a similar shape (for
a menu of pages, ArpeggioSettingsPanel) and change it.
Showing a staff, a keyboard or a clickable staff
Fill in the fields and the screen does the rest.
- A note on a staff:
staff=[[note]],clef="treble". Several notes at once (a chord) go in one inner list; several columns in sequence (an arpeggio) are several inner lists. - A key signature:
key=3for three sharps. The staff draws it after the clef. - A piano key:
keyboard=note, andkeyboard_range=(low_midi, high_midi)to show only a span.key_staff=Trueadds a small key-signature staff above the keyboard. - Place a note:
construct=noteandchoices=[]. The user clicks the staff,StaffInput.note_atturns the click into aNote, andQuestion.check_placedcompares it, spelling and octave included (G♯4 is not A♭4). Setaccidentals=Trueto show the sharp, flat and natural buttons. - A two-part answer:
choices=["C", "D", ...],octaves=["3", "4", "5"],joiner="", so the right answer is the choice joined to the octave. The screen shows two rows and submits when both are chosen.
If your question needs something the fields cannot say, the right move is to add a field to Question (with a default, so old
stored questions still load), teach ExerciseView to draw it, and add it to to_dict/from_dict. Decide whether it belongs in
item_key(): if two questions that differ in the new field are different questions, it does.
The icon
The home screen shows an icon per exercise. alto/ui/home.py has EXERCISE_ICONS, a dictionary from the exercise’s class name to
an SVG snippet in alto/ui/icons.py (a 24-by-24 drawing whose fill is the word COLOR). An exercise with no entry gets a default,
which tests/test_main_window.py checks. Make a simple monochrome icon in an SVG editor such as Inkscape, copy the path data into
a new constant, and add the dictionary entry.
Documenting it
- A section in
docs/exercises.mdthat says what is shown, what to press, and what the settings do. Write it for a user. - A screenshot if you want one: add a name to
SHOTSinscripts/screenshots.py, write the few lines that open your exercise and callsave(window, name="your-name"), include it in the page the way the other pages do (copy a line that uses theshot.htmlinclude), and runpython scripts/screenshots.py --only your-name.tests/test_docs.pychecks that every picture a page shows exists in both themes. - The instructions shown behind the “?” button: override
instructions()to return a little HTML. - The API reference: run
python scripts/api_docs.py. - A line in
ARCHITECTURE.mdonly if the exercise changes the picture of how the program fits together.
Testing it
Write the tests that the existing exercises have:
- A generation test: seed an
rng, draw some questions, and assert on what you can predict (the answer is in the choices; a question for G major shows one sharp). - A settings test: change a setting in the test (tests start from the defaults and restore them afterwards) and check the questions follow it.
- A screen test: build an
ExerciseView(YourExercise(), rng=random.Random(1)), click an answer, and check the score. Thetests/test_exercise_view.pyhelpersview_ofandaskeddo the work; setsounds.enabled = Falsein any test that submits an answer, or it will try to play. - A docstring with an example for every function, which
tests/test_docstrings.pydemands andpytestthen runs.
Further reading
- Fluent Python (see Python beyond the basics) on abstract base classes and decorators for the framework side.
- Music theory references for exercise content: Stefan Kostka and Dorothy Payne, Tonal Harmony, 7th ed. (McGraw-Hill, 2013), and Edward Aldwell, Carl Schachter and Allen Cadwallader, Harmony and Voice Leading, 4th ed. (Schirmer, 2011). They agree on terms, and when they disagree, that is a sign the exercise needs a setting.
- Thomas M. Haladyna, Developing and Validating Multiple-Choice Test Items, 3rd ed. (Lawrence Erlbaum, 2004): the standard book on writing good questions and, above all, good distractors.