alto.exercises.base
Exercise framework. To add an exercise: subclass Exercise, decorate with @register.
An Exercise makes Question objects. The Question says what to show (a staff, a keyboard or only text), which
buttons to offer and which answer is right. The exercise screen and the scheduler work with those two classes only, so
a new exercise needs no new interface code.
Examples
>>> question = Question("Name this note.", choices=["C", "D", "E"], answer="D")
>>> question.check("D"), question.check("E")
(True, False)
Question
Question(
prompt: str,
*,
choices: list[str],
answer: str,
staff: list[list[Note]] = field(default_factory=list),
clef: str = 'treble',
explanation: str = '',
key: int = 0,
value: str = 'whole',
grid: dict[str, tuple[int, int]] | None = None,
keyboard: Note | None = None,
key_staff: bool = False,
keyboard_range: tuple[int, int] | None = None,
octaves: list[str] | None = None,
second_label: str = 'Octave',
joiner: str = '',
construct: Note | None = None,
accidentals: bool = False,
accept: tuple[str, ...] = (),
show_staff: bool = False,
caption: str = '',
build_key: bool = False,
construct_scale: list[Note] | None = None,
construct_steps: list[str] | None = None,
exact_octave: bool = False,
circle: int | None = None,
circle_kind: str = '',
circle_ring: str = 'outer',
circle_key: int | None = None,
required: tuple[str, ...] = (),
place_clef: str = '',
)
One question, with what to show for it and which answer is right.
Attributes
prompt(str): The text shown above the question; may be empty.choices(list of str): The answer buttons, in the order they should be offered. Keyword-only.answer(str): The right answer, one ofchoices(or the note name for a “place this note” question). Keyword-only.staff(list of list of Note): What to draw on the staff: each inner list is one chord or note. Keyword-only.clef(str, default “treble”): The clef to draw on. Keyword-only.explanation(str, default ““): Text shown after the answer to say why it is right. Keyword-only.key(int, default 0): The key signature to draw: that many sharps if positive, flats if negative. Keyword-only.value(str, default “whole”): The note value to draw (single notes only). Keyword-only.grid(dict of str to tuple of (int, int) or None): Where to put each answer button, as (row, column). Without it the choices form one row. Keyword-only.keyboard(Note or None): A piano key to highlight, instead of drawing a staff. Keyword-only.key_staff(bool, default False): Drawkeyas a small key-signature staff above the keyboard. Keyword-only.keyboard_range(tuple of (int, int) or None): The keys (MIDI numbers, inclusive) the keyboard picture should show. Keyword-only.octaves(list of str or None): When set, the answer is a choice button plus one of these second-row buttons. Keyword-only.second_label(str, default “Octave”): What the second row of buttons is called. Keyword-only.joiner(str, default ““): Put between the two parts to make the answer (“” for a note and its octave: C + 4 gives C4). Keyword-only.construct(Note or None): The note to place on the staff: the answer is a position, not a button. Keyword-only.accidentals(bool, default False): Show the sharp, natural and flat buttons for a construct question. Keyword-only.accept(tuple of str): Other answers that count as right, such as the enharmonic name of a black key. Keyword-only.show_staff(bool, default False): Draw the staff even with no notes on it, to show only its clef and key signature. Keyword-only.caption(str, default ““): Text written on the staff itself, under the music, in place of the prompt above it. Keyword-only.build_key(bool, default False): The learner builds the key signaturekeyon a blank staff with the fork widget, instead of pressing a button. Keyword-only.construct_scale(list of Note or None): The notes of a scale to place on the staff one after another, left to right: the answer is the whole row. Keyword-only.construct_steps(list of str or None): The steps between the notes ofconstruct_scale, each “W” (whole) or “H” (half), to mark once the notes are placed; None if the steps are not asked. Keyword-only.exact_octave(bool, default False): The scale has to be placed in the octave asked, not in any octave. Keyword-only.circle(int or None): A question on the circle of fifths: the place asked about, clockwise from C at 0. Keyword-only.circle_kind(str, default ““): What the circle asks: “major” (the relative major of a minor key), “minor” (the relative minor of a major key) or “numeral” (the Roman numeral of a chord of a key). Keyword-only.circle_ring(str, default “outer”): Which ring the cell asked about is in: “outer” for the major keys or “inner” for the minor ones. Keyword-only.circle_key(int or None): For a Roman numeral question, the place of the key whose chords they are. Keyword-only.required(tuple of str): Answers that must all be given, one after another in any order, such as both names of a key with two: B and C♭. Empty for an ordinary question with one answer. Keyword-only.place_clef(str, default ““): The clef to put on a blank staff: the answer is a clef symbol (G, C or F) and a place on the staff, not a button. Empty for any other question. Keyword-only.
Examples
>>> q = Question("Which note is this?", choices=["C", "D", "E"], answer="D", staff=[[Note.parse("D4")]])
>>> q.check("D")
True
>>> Question.from_dict(q.to_dict()) == q # a question can be stored and asked again
True
Question.check_placed
def check_placed(note: Note) -> bool
Report whether a note placed on the staff is the one asked for.
The spelling and octave must match exactly, so G♯4 is not A♭4.
Parameters
note(Note): The note the learner placed.
Returns
- bool: True if it equals the note in
construct.
Examples
>>> q = Question("Place C4", choices=[], answer="C4", construct=Note.parse("C4"))
>>> q.check_placed(Note.parse("C4"))
True
>>> q.check_placed(Note.parse("B#3")) # sounds the same, but is spelled differently
False
Question.check_scale
def check_scale(notes: list[Note]) -> bool
Report whether the notes placed on the staff are the scale asked for.
The spelling and the order of the notes must match, so a G♯ is not an A♭. Unless exact_octave is set the octave
does not matter, as long as the whole scale is in the same one: the same scale an octave higher or lower is right,
but a scale with one note in the wrong octave is not. With exact_octave the scale has to be in the octave asked.
Parameters
notes(list of Note): The notes the learner placed, left to right.
Returns
- bool: True if they are the notes of
construct_scale, all moved by the same whole number of octaves (or, withexact_octave, not moved at all).
Examples
>>> asked = [Note.parse("C4"), Note.parse("D4")]
>>> q = Question("Place C D.", choices=[], answer="C4 D4", construct_scale=asked)
>>> q.check_scale([Note.parse("C4"), Note.parse("D4")])
True
>>> q.check_scale([Note.parse("C5"), Note.parse("D5")]) # the same scale, an octave higher
True
>>> q.check_scale([Note.parse("C4"), Note.parse("D5")]) # one note in another octave
False
>>> q.check_scale([Note.parse("C4"), Note.parse("D4"), Note.parse("E4")])
False
>>> exact = Question("Place C D.", choices=[], answer="C4 D4", construct_scale=asked, exact_octave=True)
>>> exact.check_scale([Note.parse("C4"), Note.parse("D4")]), exact.check_scale([Note.parse("C5"), Note.parse("D5")])
(True, False)
Question.check_steps
def check_steps(steps: list[str]) -> bool
Report whether the steps marked between the notes of a scale are the right ones.
Parameters
steps(list of str): The steps the learner marked, left to right, each “W” or “H”.
Returns
- bool: True if the steps are not asked, or if they are those of
construct_steps.
Examples
>>> q = Question("Mark the steps.", choices=[], answer="W H", construct_steps=["W", "H"])
>>> q.check_steps(["W", "H"]), q.check_steps(["H", "W"]), q.check_steps(["W"])
(True, False, False)
>>> Question("No steps.", choices=[], answer="").check_steps([])
True
Question.check_built
def check_built(count: int) -> bool
Report whether a key signature built with the fork is the one asked for.
Parameters
count(int): The signature the learner built: that many sharps if positive, flats if negative.
Returns
- bool: True if it equals
key.
Examples
>>> q = Question("Build D major.", choices=[], answer="2 sharps", key=2, show_staff=True, build_key=True)
>>> q.check_built(2), q.check_built(-2)
(True, False)
Question.check
def check(choice: str) -> bool
Report whether a chosen answer is right.
Parameters
choice(str): The text of the button that was pressed.
Returns
- bool: True if it is the answer or one of the other accepted answers.
Examples
>>> q = Question("", choices=["F♯", "G♭"], answer="F♯", accept=("G♭",))
>>> q.check("F♯"), q.check("G♭"), q.check("A")
(True, True, False)
>>> both = Question("", choices=["B", "C♭", "D"], answer="B", required=("B", "C♭"))
>>> both.check("B"), both.check("C♭"), both.check("D") # each is right, but both are needed: see `complete`
(True, True, False)
Question.complete
def complete(given: set[str]) -> bool
Report whether the answers given so far are all of those needed.
Parameters
given(set of str): The right answers given so far.
Returns
- bool: For an ordinary question, whether the answer has been given; for one with several
required, whether all have.
Examples
>>> both = Question("", choices=["B", "C♭"], answer="B", required=("B", "C♭"))
>>> both.complete({"B"}), both.complete({"C♭", "B"})
(False, True)
>>> Question("", choices=["C"], answer="C").complete({"C"})
True
Question.item_key
def item_key() -> str
Return a stable identity for the question, so the same one can be recognised when it comes round again.
It covers what is asked and where it is drawn, but not the note value or the order of the buttons.
Returns
- str: A 20-character hexadecimal string.
Examples
>>> a = Question("Name it.", choices=["C", "D"], answer="C")
>>> b = Question("Name it.", choices=["D", "C"], answer="C") # the same question, buttons in another order
>>> a.item_key() == b.item_key()
True
>>> len(a.item_key())
20
Question.to_dict
def to_dict() -> dict
Return the question as plain data, so it can be stored and asked again.
Returns
- dict: The fields of the question, with notes as dictionaries and tuples as lists.
Examples
>>> data = Question("Name it.", choices=["C"], answer="C", staff=[[Note.parse("C4")]]).to_dict()
>>> data["answer"], data["staff"]
('C', [[{'octave': 4, 'letter': 0, 'accidental': 0}]])
Question.from_dict
@classmethod
def from_dict(d: dict) -> Question
Rebuild a question from the data that to_dict made.
Parameters
d(dict): The stored data. Questions saved by older versions, which may carry aplayfield, are accepted.
Returns
- Question: The question.
Examples
>>> q = Question("Name it.", choices=["C", "D"], answer="C", key=2, accept=("D",))
>>> Question.from_dict(q.to_dict()) == q
True
note_from
def note_from(v: dict | None) -> Note | None
Rebuild a note from stored data.
Parameters
v(dict or None): A note as the dictionaryto_dictstores, or None.
Returns
- Note or None: The note, or None if
vwas None.
Examples
>>> note_from({"octave": 4, "letter": 0, "accidental": 0})
Note(octave=4, letter=0, accidental=0)
>>> note_from(None) is None
True
signature
def signature(*parts: object) -> str
Describe the exercise settings in force, so a stored question is only asked again under the settings it was made for.
Parameters
*parts(object): The settings to describe: dataclasses, dictionaries, lists, sets and plain values, nested as needed.
Returns
- str: A JSON string that is the same for equal settings, however their sets and dictionaries happen to be ordered.
Examples
>>> signature({"clefs": {"bass", "treble"}}, 3)
'[{"clefs": ["bass", "treble"]}, 3]'
>>> signature({"clefs": {"treble", "bass"}}, 3) == signature({"clefs": {"bass", "treble"}}, 3)
True
Exercise
class Exercise(ABC)
What every exercise provides: its name, how it makes questions and how long a good answer takes.
Attributes
name(str): The title shown on the home screen and in the exercise list.category(str): The heading it is listed under.description(str): One line saying what the exercise is for.par_seconds(float, default 5.0): How long a good first answer takes; much quicker earns credit and much slower counts against the question.has_sound(bool, default True): False for an exercise that makes no sound at all, whatever the sound button says.
Examples
>>> class Demo(Exercise):
... name = "Demo"
... def generate(self, rng):
... return Question("Pick A.", choices=["A", "B"], answer="A")
>>> Demo().generate(random.Random(0)).answer
'A'
Exercise.settings_signature
def settings_signature() -> str
Return what identifies the settings that shape the questions.
A stored question is only asked again while this is unchanged. Exercises with settings override it.
Returns
- str: An identifier; empty for an exercise with no settings.
Examples
>>> class Demo(Exercise):
... def generate(self, rng):
... return Question("?", choices=["A"], answer="A")
>>> Demo().settings_signature()
''
Exercise.refresh
def refresh(question: Question) -> Question
Bring a stored question up to date with how the exercise draws its questions now.
A question that is asked again comes from the copy stored when it was first asked, which an older version may have drawn differently. The default leaves it as it is.
Parameters
question(Question): The question as it was stored.
Returns
- Question: The question as the exercise would draw it today.
Examples
>>> class Demo(Exercise):
... def generate(self, rng):
... return Question("?", choices=["A"], answer="A")
>>> q = Question("?", choices=["A"], answer="A")
>>> Demo().refresh(q) is q
True
Exercise.instructions
def instructions() -> str
Return the help text shown from the exercise’s help button.
Exercises override it to describe themselves.
Returns
- str: Simple HTML; by default the one-line description.
Examples
>>> class Demo(Exercise):
... description = "Spot the note."
... def generate(self, rng):
... return Question("?", choices=["A"], answer="A")
>>> Demo().instructions()
'Spot the note.'
Exercise.generate
@abstractmethod
def generate(rng: random.Random) -> Question
Make one new question.
Parameters
rng(random.Random): The random number generator to use, so tests can ask for a repeatable question.
Returns
- Question: The question.
Examples
>>> from alto.exercises.library import NoteNames
>>> q = NoteNames().generate(random.Random(1))
>>> q.answer in q.choices
True
register
def register() -> type[Exercise]
Add an exercise to REGISTRY, next to the others of its category.
The categories come in the order they first appear, so the home screen and the exercise list can show each category once, with all its exercises under it. Used as a class decorator.
Parameters
cls(type of Exercise): The exercise class.
Returns
- type of Exercise: The same class, so the decorator can be applied to a class definition.
Examples
>>> @register
... class Demo(Exercise):
... name = "Demo"
... category = "A category no other exercise has"
... def generate(self, rng):
... return Question("?", choices=["A"], answer="A")
>>> REGISTRY[-1] is Demo
True
>>> REGISTRY.remove(Demo)
pick_distractors
def pick_distractors(
correct: str,
*,
pool: list[str],
n: int,
rng: random.Random,
) -> list[str]
Choose wrong answers to offer alongside the right one, and shuffle them all.
Parameters
correct(str): The right answer. It is always in the result.pool(list of str): Where the wrong answers come from; repeats and the right answer are ignored. Keyword-only.n(int): How many wrong answers to include (fewer if the pool has fewer). Keyword-only.rng(random.Random): The random number generator used to choose and shuffle. Keyword-only.
Returns
- list of str: The right answer and up to
nothers, in a random order.
Examples
>>> choices_ = pick_distractors("C", pool=["C", "D", "E", "F"], n=2, rng=random.Random(0))
>>> len(choices_), "C" in choices_
(3, True)