Alto
dev

alto.exercises.base

Exercise framework. Register a ChoiceExercise for button answers or an Exercise for construction tasks.

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,
    staff_signature: int | None = None,
    minor: bool = False,
    value: str = 'whole',
    grid: dict[str, tuple[int, int]] | None = None,
    keyboard: Note | None = None,
    keyboard_notes: list[Note] = field(default_factory=list),
    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,
    place_signature: bool = False,
    starting_slots: list[int] = field(default_factory=list),
    construct_scale: list[Note] | None = None,
    construct_steps: list[str] | None = None,
    notes_only: bool = False,
    any_octave: bool = False,
    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 = '',
    notation_target: tuple[str, int] | None = None,
    notation_excerpt: str | None = None,
)

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 of choices (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 written duration for single notes and interval voices. Keyword-only.
  • staff_signature (int or None): Override the signature shown on the staff while retaining the key for scale degrees. Keyword-only.
  • minor (bool, default False): Use the signature’s relative minor for scale degree naming. 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.
  • keyboard_notes (list of Note): Multiple piano keys to highlight together instead of drawing a staff. Keyword-only.
  • key_staff (bool, default False): Draw key as 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 signature key on a blank staff with the fork widget, instead of pressing a button. Keyword-only.
  • place_signature (bool, default False): Place each accidental of the named key on the staff. Keyword-only.
  • starting_slots (list of int): Zero-based positions of the accidentals already printed in an Order of Keys question.
  • 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 of construct_scale, each “W” (whole) or “H” (half), to mark once the notes are placed; None if the steps are not asked. Keyword-only.
  • notes_only (bool, default False): Show note names without a scale degree context. Keyword-only.
  • any_octave (bool, default False): Accept a single constructed note with the right spelling in any octave. 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.
  • notation_target (tuple of (str, int) or None): Notation part and zero-based note column or staff line to highlight. Keyword-only.
  • notation_excerpt (str or None): Versioned score containing the target. Its position is an index into the excerpt manifest. 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 must match exactly. The octave must also match unless any_octave is set.

Parameters

  • note (Note): The note the learner placed.

Returns

  • bool: True if it matches the requested note spelling and any required octave.

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, with exact_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.places_sequence

@property
def places_sequence() -> bool

Report whether the learner enters successive positions on the staff.

Returns

  • bool: True for scales and handwritten key signatures.

Examples

>>> Question("D major", choices=[], answer="F♯5 C♯5", place_signature=True).places_sequence
True

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 recognized when it comes around 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 a play field, 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 dictionary to_dict stores, or None.

Returns

  • Note or None: The note, or None if v was 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.card_groups

def card_groups() -> dict[str, str] | None

Map playable examples to the skills that share a calendar review date.

Returns

  • dict of str to str or None: Example item keys mapped to skill names, or None when every example has its own schedule.

Examples

>>> from alto.exercises.library import KeyboardNotes
>>> KeyboardNotes().card_groups() is None
True

Exercise.card_count

def card_count() -> int | None

Count distinct cards possible with the current settings when the exercise has an exact catalog.

Returns

  • int or None: Catalog size, or None for an exercise that prepares a bounded daily sample.

Examples

>>> from alto.exercises.library import KeyboardNotes
>>> KeyboardNotes().card_count() is None
True

Exercise.daily_candidates

def daily_candidates(rng: random.Random) -> Iterator[Question]

Yield distinct questions until 100 consecutive draws find no new playable item.

Parameters

  • rng (random.Random): The generator for this day’s sample.

Yields

  • Question: A playable question. Finite exercises can override this to visit every eligible item.

Examples

>>> from alto.exercises.library import KeyboardNotes
>>> isinstance(next(KeyboardNotes().daily_candidates(random.Random(1))), Question)
True

Exercise.review_question

def review_question(
    question: Question,
    *,
    same_settings: bool,
) -> Question | None

Adapt a stored question for review under the active settings.

Parameters

  • question (Question): Previously introduced card.
  • same_settings (bool): Whether the saved presentation matches the active settings.

Returns

  • Question or None: A playable question when the exercise recognizes this presentation.

Examples

>>> from alto.exercises.library import KeyboardNotes
>>> ex = KeyboardNotes()
>>> q = ex.generate(random.Random(1))
>>> ex.review_question(q, same_settings=True) == q
True

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

ButtonSettings

ButtonSettings(
    button_mode: str = 'all',
    button_count: int = 6,
)

An exercise’s choice of answer layout and maximum number of buttons per group.

Examples

>>> ButtonSettings().button_mode
'all'

ChoiceExercise

class ChoiceExercise(Exercise)

A button-answer exercise with its own standard Buttons submenu.

Supply the eligible choices in make_question. Set default_limit to start in Limited mode.

Examples

>>> from alto.exercises.library import ChordQualities
>>> ChordQualities.button_settings().button_mode
'limited'

ChoiceExercise.button_settings

@classmethod
@cache
def button_settings() -> ButtonSettings

Return the preferences shared by instances of this particular exercise.

Returns

  • ButtonSettings: The exercise’s answer layout.

Examples

>>> from alto.exercises.library import NoteNames
>>> NoteNames.button_settings().button_mode
'all'

ChoiceExercise.settings_signature

def settings_signature() -> str

Include custom answer layouts when deciding which questions can be replayed.

Returns

  • str: The original practice signature at the historical default, or a layout-specific signature.

Examples

>>> from alto.exercises.library import ChordQualities
>>> ChordQualities().settings_signature()
''

ChoiceExercise.practice_signature

def practice_signature() -> str

Identify the exercise settings other than the answer layout.

Returns

  • str: The signature for questions using the default layout.

Examples

>>> from alto.exercises.library import ChordQualities
>>> ChordQualities().practice_signature()
''

ChoiceExercise.generate

def generate(rng: random.Random) -> Question

Generate the musical task and apply the selected button count.

Parameters

  • rng (random.Random): Source for the exercise and the distractor sample.

Returns

  • Question: A question with its answer buttons ready for practice.

Examples

>>> from alto.exercises.library import ChordQualities
>>> len(ChordQualities().generate(random.Random(0)).choices)
5

ChoiceExercise.limit_buttons

def limit_buttons(
    question: Question,
    *,
    rng: random.Random,
) -> Question

Limit each answer group while keeping all the buttons needed to complete the question.

Parameters

  • question (Question): The task and its eligible answer choices.
  • rng (random.Random): Source for sampling distractors.

Returns

  • Question: The question with its chosen layout.

Examples

A note and octave question keeps the correct name and octave in their respective groups.

ChoiceExercise.make_question

@abstractmethod
def make_question(rng: random.Random) -> Question

Generate the task and eligible answer choices before the button limit is applied.

Parameters

  • rng (random.Random): The exercise’s random source.

Returns

  • Question: The musical task.

Examples

Note Identification supplies the note names appropriate to the active clef and key settings.

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 n others, 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)