Alto
latest

alto.exercises.library

The exercises: note names, intervals, key signatures, scales, chords, arpeggios, keyboard keys and note construction.

Each class makes one kind of Question and registers itself with @register, so importing this module is what adds the exercises to the home screen.

Examples

>>> from alto.exercises import REGISTRY
>>> [cls.name for cls in REGISTRY][:3]
['Note Identification', 'Keyboard Identification', 'Note Construction']

NoteNames

NoteNames(accidentals: bool = False)

Bases: Exercise

Name the note shown on a staff.

Examples

>>> q = NoteNames().generate(random.Random(1))
>>> len(q.staff), q.answer in q.choices
(1, True)

Constructor

Create the exercise.

Parameters

  • accidentals (bool, default False): Ask notes with explicit sharps, flats and naturals, whatever the settings say.

Constructor examples

>>> NoteNames(accidentals=True).accidentals
True

NoteNames.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, ranges, key signatures, note values and naming in force, and whether accidentals are asked.

Examples

>>> NoteNames().settings_signature() != NoteNames(accidentals=True).settings_signature()
True

NoteNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Press the button with its name" in NoteNames().instructions()
True

NoteNames.generate

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

Make a note to name, on one of the chosen clefs, in a chosen key.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The note drawn on a staff, with one button for each name that could be the answer.

Examples

>>> q = NoteNames().generate(random.Random(2))
>>> q.clef in ("treble", "bass", "alto", "tenor", "soprano", "mezzo", "baritone", "grand")
True

IntervalNames

class IntervalNames(Exercise)

Name the interval between two notes, up to an octave.

Attributes

  • QUALITIES (dict of int to str): For each interval number, the qualities that can occur, separated by spaces.

Examples

>>> q = IntervalNames().generate(random.Random(3))
>>> len(q.staff), q.answer in q.choices
(2, True)

IntervalNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "quality followed by a number" in IntervalNames().instructions()
True

IntervalNames.generate

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

Make two notes whose interval is to be named.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The lower and higher note on a staff, and the interval (such as ‘M3’ or ‘P5’) as the answer.

Examples

>>> q = IntervalNames().generate(random.Random(4))
>>> q.answer[0] in "PMmAd" and q.answer[1:].isdigit()
True

KeySignatures

class KeySignatures(Exercise)

Read a key signature drawn on a staff and name the key it belongs to.

Examples

>>> q = KeySignatures().generate(random.Random(5))
>>> q.answer in q.choices
True

KeySignatures.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The kinds of question, clefs, scales and key signatures in force.

Examples

>>> KeySignatures().settings_signature().startswith("[")
True

KeySignatures.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Key Signature Identification" in KeySignatures().instructions()
True

KeySignatures.refresh

def refresh(question: Question) -> Question

Give a stored signature question the caption on its staff that older versions did not write.

Parameters

  • question (Question): The question as it was stored.

Returns

  • Question: The same question, captioned ‘_ Major’ (or ‘_ minor’, ‘_ Dorian’ and so on) if it shows a staff and had no caption.

Examples

>>> old = Question("Which minor key has this key signature?", choices=["C"], answer="C", key=-3, show_staff=True)
>>> KeySignatures().refresh(old).caption
'_ minor'

KeySignatures.generate

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

Make a key signature to read.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A signature on a staff; the answer is the tonic of the scale that has it.

Examples

>>> q = KeySignatures().generate(random.Random(6))
>>> q.show_staff and q.answer in q.choices
True

KeySignatureConstruction

class KeySignatureConstruction(Exercise)

Build the key signature of a named key on a blank staff, with the fork.

Examples

>>> q = KeySignatureConstruction().generate(random.Random(5))
>>> q.build_key, q.staff, q.choices
(True, [], [])

KeySignatureConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, scales and key signatures in force.

Examples

>>> KeySignatureConstruction().settings_signature().startswith("[")
True

KeySignatureConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Key Signature Construction" in KeySignatureConstruction().instructions()
True

KeySignatureConstruction.generate

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

Name a key whose signature is to be built.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A blank staff captioned with the key, such as ‘D Major’; the answer is its sharps or flats.

Examples

>>> q = KeySignatureConstruction().generate(random.Random(1))
>>> q.caption.split()[0] in {"C", "D", "E", "F", "G", "A", "B"} or "♯" in q.caption or "♭" in q.caption
True
>>> q.answer == format_key_signature(q.key)
True

ScaleDegrees

class ScaleDegrees(Exercise)

Spell a note of a scale or mode from its tonic.

Examples

>>> q = ScaleDegrees().generate(random.Random(7))
>>> q.prompt.startswith("In ") and q.answer in q.choices
True

ScaleDegrees.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "degree" in ScaleDegrees().instructions()
True

ScaleDegrees.generate

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

Make a question asking for one degree of a scale.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: For example ‘In E♭ Dorian, what is scale degree 6?’, answered ‘C’.

Examples

>>> q = ScaleDegrees().generate(random.Random(8))
>>> "scale degree" in q.prompt
True

ScaleConstruction

class ScaleConstruction(Exercise)

Place the notes of a named scale on a blank staff, one after another.

Examples

>>> q = ScaleConstruction().generate(random.Random(5))
>>> len(q.construct_scale or []), q.choices, q.key
(8, [], 0)

ScaleConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, scales and key signatures in force.

Examples

>>> ScaleConstruction().settings_signature().startswith("[")
True

ScaleConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "Scale Construction" in ScaleConstruction().instructions()
True

ScaleConstruction.generate

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

Name a scale to be placed on the staff.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A blank staff captioned with the scale, such as ‘D Major’; construct_scale is its eight notes, going up an octave.

Examples

>>> q = ScaleConstruction().generate(random.Random(1))
>>> scale = q.construct_scale or []
>>> scale[0].name == scale[-1].name and q.accidentals
True
>>> q.check_scale(scale)
True

CircleOfFifths

class CircleOfFifths(Exercise)

Questions on the circle of fifths: a relative major, a relative minor, or the Roman numeral of a chord.

Examples

>>> q = CircleOfFifths().generate(random.Random(3))
>>> q.circle is not None and q.answer in q.choices
True

CircleOfFifths.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The kinds of question in force.

Examples

>>> CircleOfFifths().settings_signature().startswith("[")
True

CircleOfFifths.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with a paragraph for each kind of question that is switched on.

Examples

>>> "circle of fifths" in CircleOfFifths().instructions()
True

CircleOfFifths.generate

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

Pick a kind of question that is switched on, and ask it.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A question on the circle: circle_kind says which kind.

Examples

>>> settings.circle.questions = {"minor"}
>>> q = CircleOfFifths().generate(random.Random(5))
>>> q.circle_kind, q.prompt
('minor', 'Which minor key is the relative minor of F major?')
>>> settings.circle.questions = set(settings.CIRCLE_QUESTIONS)

ChordQualities

class ChordQualities(Exercise)

Identify the quality of a triad or seventh chord in root position.

Examples

>>> q = ChordQualities().generate(random.Random(9))
>>> len(q.staff[0]) in (3, 4) and q.answer in q.choices
True

ChordQualities.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "root position" in ChordQualities().instructions()
True

ChordQualities.generate

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

Make a chord in root position whose quality is to be named.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The chord drawn as one stack of notes, with its type (such as ‘minor 7th’) as the answer.

Examples

>>> q = ChordQualities().generate(random.Random(10))
>>> q.answer in CHORDS
True

ArpeggioNames

class ArpeggioNames(Exercise)

Name the type and the inversion of a broken chord.

Examples

>>> q = ArpeggioNames().generate(random.Random(11))
>>> q.octaves is not None and len(q.staff) >= 4
True

ArpeggioNames.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, chord types, inversions and key signatures in force.

Examples

>>> ArpeggioNames().settings_signature().startswith("[")
True

ArpeggioNames.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML.

Examples

>>> "inversion" in ArpeggioNames().instructions()
True

ArpeggioNames.generate

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

Make an arpeggio on one of the chosen clefs, in a chosen position.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The arpeggio’s notes one after another on a staff; the answer is the chord type and inversion, such as ‘major · 1st inversion’.

Raises

  • RuntimeError: If no arpeggio fits the chosen clefs, chord types and inversions.

Examples

>>> q = ArpeggioNames().generate(random.Random(12))
>>> " · " in q.answer
True

KeyboardNotes

class KeyboardNotes(Exercise)

Name the highlighted key on a piano keyboard.

Examples

>>> q = KeyboardNotes().generate(random.Random(13))
>>> q.keyboard is not None and q.answer in q.choices
True

KeyboardNotes.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The keyboard range, black keys, octave and key signature settings, and the naming in force.

Examples

>>> KeyboardNotes().settings_signature().startswith("[")
True

KeyboardNotes.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with paragraphs added for the octave and key signature settings that are on.

Examples

>>> "highlighted" in KeyboardNotes().instructions()
True

KeyboardNotes.generate

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

Make a keyboard with one key highlighted.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: The keyboard, a grid of name buttons (and a row of octave buttons if octaves are asked), and the key’s name as the answer, with the other spelling of a black key accepted.

Examples

>>> q = KeyboardNotes().generate(random.Random(14))
>>> # noinspection PyUnresolvedReferences
>>> q.keyboard_range[0] <= q.keyboard.midi <= q.keyboard_range[1]
True

NoteConstruction

class NoteConstruction(Exercise)

Place a named note on the staff.

Examples

>>> q = NoteConstruction().generate(random.Random(15))
>>> q.construct is not None and q.prompt.startswith("Place ")
True

NoteConstruction.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs, accidentals and key signature settings, and the naming in force.

Examples

>>> NoteConstruction().settings_signature().startswith("[")
True

NoteConstruction.instructions

def instructions() -> str

Return the help text for the exercise.

Returns

  • str: Simple HTML, with paragraphs added for the key signature and accidental settings that are on.

Examples

>>> "Click the staff" in NoteConstruction().instructions()
True

NoteConstruction.generate

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

Make a note name to be placed on the staff.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: A prompt such as ‘Place F♯4 on the staff.’; the answer is the note’s name, and construct is the note to place.

Examples

>>> q = NoteConstruction().generate(random.Random(16))
>>> q.answer in q.prompt
True

ClefBasics

class ClefBasics(Exercise)

Put a named clef on a blank staff: choose the G, C or F symbol and put it on the line that makes the clef asked for.

Examples

>>> q = ClefBasics().generate(random.Random(1))
>>> q.answer == q.place_clef and q.place_clef in settings.CLEF_BASICS_CLEFS
True

ClefBasics.settings_signature

def settings_signature() -> str

Return what identifies the settings that shape these questions.

Returns

  • str: The clefs asked for.

Examples

>>> ClefBasics().settings_signature().startswith("[")
True

ClefBasics.instructions

def instructions() -> str

Return the help text for the exercise, for the kind of question that is being asked.

Returns

  • str: Simple HTML.

Examples

>>> "Clef Basics" in ClefBasics().instructions()
True

ClefBasics.generate

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

Name a clef to place, or draw a clef to name.

Parameters

  • rng (random.Random): The random number generator.

Returns

  • Question: For construction, a blank staff and the name of the clef, which is the question written under the staff. For identification, a staff with the clef drawn on it, and a button for each clef that can be asked for.

Examples

>>> q = ClefBasics().generate(random.Random(3))
>>> q.prompt.startswith("Place the ") and q.caption == q.prompt
True
>>> settings.clef_basics.question_type = "identification"
>>> q = ClefBasics().generate(random.Random(3))
>>> q.answer in q.choices, q.place_clef, q.caption
(True, '', 'Which clef is this?')
>>> settings.clef_basics.question_type = "construction"