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_scaleis 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_kindsays 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
constructis 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"