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 = '',
)
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.
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 = '',
)
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 ofalto.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.
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,
)
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 round 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 practise.staves(tuple of Staff): Staves to show beside the words, one above another, instead of the circle; empty for none.task_staff(bool): Show one staff beside the words that follows the task: it draws the task’s clef.
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,
)
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 class name of the exercise that practises it, which the last page offers.
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'