Alto
dev

alto.lessons.base

What a lesson is made of: steps, and the small tasks inside them.

A task is a soft exercise. It cannot be failed: a wrong answer gets a hint, a second wrong answer gets the answer, and nothing is scored or recorded.

Examples

>>> task = Task(prompt="Click the key.", cells=frozenset({("outer", 1)}), hint="Count.", explanation="One step.")
>>> task.check(("outer", 1)), task.check(("outer", 2))
(True, False)

Task

Task(
    prompt: str,
    hint: str,
    explanation: str,
    cells: frozenset[tuple[str, int]] = frozenset(),
    choices: tuple[str, ...] = (),
    correct: str = '',
    clef: str = '',
    key: int = 0,
)

One small question inside a lesson step.

It is answered either by clicking a cell of the circle (cells) or by pressing one of choices.

Attributes

  • prompt (str): The question, as simple HTML.
  • hint (str): What to say after a wrong answer.
  • explanation (str): What to say after the right answer, or once the answer has been given away.
  • cells (frozenset of tuple of (str, int)): The cells that are right, each a ring (“outer” or “inner”) and a place clockwise from the top.
  • choices (tuple of str): The buttons to choose from, for a question that is not answered on the circle.
  • correct (str): The right button, if there are choices.
  • clef (str): For a step that shows a staff beside a task, the clef to draw on it; empty for a blank staff.
  • key (int): Sharps (positive) or flats (negative) on the task staff.

Examples

>>> Task(prompt="Which?", hint="Count.", explanation="Five.", choices=("A", "B"), correct="B").check("B")
True

Task.check

def check(answer: tuple[str, int] | str) -> bool

Say whether an answer is right.

Parameters

  • answer (tuple of (str, int) or str): A cell that was clicked, or the text of a button that was pressed.

Returns

  • bool: True for a right answer.

Examples

>>> Task(prompt="?", hint="", explanation="", cells=frozenset({("inner", 0)})).check(("inner", 0))
True
>>> Task(prompt="?", hint="", explanation="", choices=("A", "B"), correct="A").check(("outer", 0))
False

Staff

Staff(
    clef: str,
    note: str = '',
    caption: str = '',
    key: int = 0,
)

A staff to show beside the words of a step: a clef, and perhaps a note, with a line of words under it.

Attributes

  • clef (str): The clef to draw, any of alto.settings.CLEF_BASICS_CLEFS.
  • note (str): A note to write on the staff, such as “C4”; empty for none. Only the seven clefs that have a lowest line for notes can have one, not the French violin and subbass clefs.
  • caption (str): The words under the staff.
  • key (int): Sharps (positive) or flats (negative) after the clef.

Examples

>>> Staff(clef="alto", note="C4", caption="Alto clef").note
'C4'

Step

Step(
    title: str,
    text: str,
    circle: str = 'none',
    hear: tuple[tuple[str, ...], ...] = (),
    hear_label: str = 'Hear it',
    make_task: Callable[[random.Random], Task] | None = field(default=None, compare=False),
    closing: bool = False,
    staves: tuple[Staff, ...] = (),
    task_staff: bool = False,
    scale: str = '',
    scale_tonic: str = 'C4',
    scale_explore: bool = True,
    keyboard_note: str = '',
    hear_display: Literal['', 'staff', 'keyboard'] = '',
)

One page of a lesson.

Attributes

  • title (str): The heading.
  • text (str): What to read, as simple HTML.
  • circle (str): How the circle of fifths is shown: “none” for no circle, “rest” for a picture that does not respond, “explore” for one that can be clicked, or “walk” for one that can also be walked around with two buttons.
  • hear (tuple of tuple of str): Notes to play from a Hear it button, as columns of note names such as “C4”; empty for no button.
  • hear_label (str): What the Hear it button says.
  • make_task (callable or None): Makes a fresh task from a random generator each time one is wanted; None for a step with no task.
  • closing (bool): True for the last step, which offers to practice.
  • staves (tuple of Staff): Captioned staves in reading order. Adjacent examples share a panel and wrap when space is limited.
  • task_staff (bool): Show one staff beside the words that follows the task: it draws the task’s clef and key signature.
  • scale (str): Scale type for an interactive notation diagram; empty for none.
  • scale_tonic (str): Starting note of the diagram, including its octave.
  • scale_explore (bool): Allow changing the example. False hides the selectors for identification tasks.
  • hear_display (str): Show the playback pitches on a treble staff or keyboard (“staff” or “keyboard”). Empty hides this diagram.
  • keyboard_note (str): A named pitch to highlight on the lesson keyboard, which spans middle C to the C above it.

Examples

>>> Step(title="Hello", text="<p>Hi.</p>").circle
'none'

Lesson

Lesson(
    key: str,
    title: str,
    about: str,
    summary: str,
    category: str,
    steps: tuple[Step, ...],
    exercise: str,
    related_exercises: tuple[str, ...] = (),
)

A lesson: a title, a line about it, and its steps.

Attributes

  • key (str): A short name to save progress under.
  • title (str): The title.
  • about (str): A line or two saying what the lesson covers.
  • summary (str): A short line for its card.
  • category (str): The group it belongs to on the list, such as “Scales & Keys”.
  • steps (tuple of Step): The pages, in order.
  • exercise (str): The primary exercise offered on the last page and used for the lesson icon.
  • related_exercises (tuple of str): Additional exercises offered on the last page, in display order.

Examples

>>> steps = (Step(title="One", text=""),)
>>> lesson = Lesson(
...     key="demo",
...     title="Demo",
...     about="A demo.",
...     summary="Demo.",
...     category="Demos",
...     steps=steps,
...     exercise="NoteNames",
... )
>>> lesson.steps[0].title
'One'