alto.learning.calendar
Daily exercise queues for SM-2 and FSRS.
The scheduler controls when an introduced card is due. Each exercise supplies new questions under its current settings. Counting a prepared question does not introduce it.
ReviewInterval
ReviewInterval(
seconds: int,
identity: tuple[int, str, str, str],
previous_state: str | None,
rating: Rating = Rating.Good,
graded_state: str | None = None,
previous_due: float | None = None,
)
A preview of one rating for a card in its current scheduling state.
Examples
>>> ReviewInterval(600, (1, "NoteNames", "abc", "FSRS"), None).seconds
600
ReviewInterval.duration
@property
def duration() -> str
Format a review interval for display above a grade button or beside the music.
Returns
- str: A whole-day interval or a short learning step in minutes and seconds.
Examples
>>> ReviewInterval(330, (1, "NoteNames", "abc", "FSRS"), None).duration
'5 min 30 s'
CalendarPractice
CalendarPractice(db: Database)
Prepare daily exercise queues and store each scheduler’s review dates.
Examples
>>> practice = CalendarPractice(Database())
>>> practice.db.profiles()
[]
Constructor
Attach the queues to an Alto database.
Parameters
db(Database): Database containing the profile and its cards.
Constructor examples
>>> CalendarPractice(Database())._batches
{}
CalendarPractice.inherit_schedules
def inherit_schedules(
profile: int,
*,
mode: str,
) -> None
Initialize missing schedules for this profile from the other calendar scheduler.
Parameters
profile(int): Profile entering calendar practice.mode(str): Selected scheduler. Adaptive practice uses no calendar schedules.
Examples
Switching to FSRS carries over an SM-2 due date without consuming a review.
CalendarPractice.limits
def limits(
profile: int,
*,
exercise: str = '',
) -> tuple[int, int]
Return the effective daily new-card and review limits.
Parameters
profile(int): Profile whose settings to read.exercise(str): Exercise class name, or an empty string for profile defaults.
Returns
- tuple of int and int: New cards and completed reviews allowed per exercise per local day. UNLIMITED removes the cap.
Examples
>>> CalendarPractice(Database()).limits(1)
(10, 200)
CalendarPractice.overrides
def overrides(
profile: int,
*,
exercise: str,
) -> tuple[int | None, int | None]
Read the two explicitly saved limits for an exercise.
Parameters
profile(int): Active profile.exercise(str): Exercise class name.
Returns
- tuple: A number for each override, or None for each inherited value.
Examples
>>> CalendarPractice(Database()).overrides(1, exercise="NoteNames")
(None, None)
CalendarPractice.set_limits
def set_limits(
profile: int,
*,
exercise: str = '',
new_cards: int | None,
reviews: int | None,
) -> None
Save the profile defaults or an exercise’s individual overrides.
Parameters
profile(int): Active profile.exercise(str): Exercise class name, or an empty string for the profile defaults.new_cards(int or None): Daily introductions, UNLIMITED for no cap, or None to inherit.reviews(int or None): Daily reviews, UNLIMITED for no cap, or None to inherit.
Examples
>>> db = Database()
>>> practice = CalendarPractice(db)
>>> profile = db.add_profile("Ada").id
>>> practice.set_limits(profile, new_cards=5, reviews=30)
>>> practice.limits(profile, exercise="NoteNames")
(5, 30)
CalendarPractice.reset_limits
def reset_limits(profile: int) -> None
Restore the profile defaults and remove its exercise overrides.
Parameters
profile(int): Profile whose limits to reset.
Examples
Restoring defaults keeps the day's introductions and completed reviews.
CalendarPractice.queue
def queue(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
) -> tuple[list[Question], list[Question]]
Find due reviews and prepare the remaining new cards for this local day.
Parameters
exercise(Exercise): Exercise with its current settings.profile(int): Active profile ID.mode(str): Calendar scheduler whose due dates apply.now(float): Current timestamp.
Returns
- tuple of list of Question and list of Question: Due reviews, oldest first, and new questions available for introduction.
Examples
>>> from alto.exercises.library import NoteNames
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> due, new = CalendarPractice(db).queue(NoteNames(), profile=ada.id, mode="FSRS", now=1000)
>>> not due and len(new) == DAILY_NEW
True
CalendarPractice.counts
def counts(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
) -> tuple[int, int]
Count due reviews and unseen cards available with the selected settings.
Parameters
exercise(Exercise): Exercise shown on the tile.profile(int): Active profile.mode(str): Calendar scheduler.now(float): Current timestamp.
Returns
- tuple of int and int: Due and new counts. Exact catalogs can be counted without rendering their cards.
Examples
>>> from alto.exercises.library import NoteNames
>>> db = Database()
>>> CalendarPractice(db).counts(NoteNames(), profile=db.add_profile("Ada").id, mode="SM-2", now=100)[1] > 0
True
CalendarPractice.tile_counts
def tile_counts(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
) -> tuple[int, int, int]
Count available reviews, new cards, and missed cards awaiting a correct review.
Parameters
exercise(Exercise): Exercise with the current settings.profile(int): Active profile ID.mode(str): Active calendar scheduler.now(float): Current timestamp.
Returns
- tuple of int, int, int: Due reviews, available new cards, and outstanding incorrect cards. A due retry counts in both review totals.
Examples
>>> from alto.exercises.library import NoteNames
>>> db = Database()
>>> CalendarPractice(db).tile_counts(NoteNames(), profile=db.add_profile("Ada").id, mode="SM-2", now=100)[2]
0
CalendarPractice.study_counts
def study_counts(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
current_key: str | None = None,
) -> tuple[tuple[int, int, int], str | None]
Count the exercise queues and identify the queue of the question on screen.
Parameters
exercise(Exercise): Exercise with the current settings.profile(int): Active profile ID.mode(str): Active calendar scheduler.now(float): Current timestamp.current_key(str or None): Item key of the question awaiting an answer.
Returns
- tuple: The same review, new, and incorrect counts as the tiles, plus the current queue if a question is active.
Examples
A missed card that comes due again is underlined as incorrect during its retry.
CalendarPractice.take
def take(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
) -> Question | None
Take the first eligible card, recording a new introduction only when served.
Parameters
exercise(Exercise): Exercise being opened or advanced.profile(int): Active profile ID.mode(str): Active calendar scheduler.now(float): Presentation timestamp.
Returns
- Question or None: Next question, or None once the available work is finished.
Examples
>>> from alto.exercises.library import ChordQualities
>>> db = Database()
>>> practice = CalendarPractice(db)
>>> question = practice.take(ChordQualities(), profile=db.add_profile("Ada").id, mode="SM-2", now=1000)
>>> isinstance(question, Question)
True
CalendarPractice.take_or_wait
def take_or_wait(
exercise: Exercise,
*,
profile: int,
mode: str,
now: float,
avoid: str | None = None,
wait_learning: bool = False,
) -> tuple[Question | None, float | None]
Draw an eligible card or return the time when a missed card can be reviewed.
Parameters
exercise(Exercise): Exercise with the current settings.profile(int): Active profile ID.mode(str): Active calendar scheduler.now(float): Presentation timestamp.avoid(str or None): Prefer another available card to the one just shown.wait_learning(bool): Also wake the exercise when a correctly answered learning card comes due.
Returns
- tuple: The next question and, when the queue is waiting for a retry, its due timestamp.
Examples
A single missed card can wake the exercise when its learning step expires.
CalendarPractice.introduce
def introduce(
exercise: Exercise,
*,
profile: int,
question: Question,
now: float,
) -> None
Register a calendar introduction once, in the caller’s draw or answer transaction.
Parameters
exercise(Exercise): Exercise that supplied this question.profile(int): Practicing profile.question(Question): New or previously introduced question.now(float): Time of introduction.
Examples
Answering a pending card keeps its original introduction day.
CalendarPractice.correct_interval
def correct_interval(
exercise: str,
*,
profile: int,
key: str,
mode: str,
now: float,
) -> ReviewInterval
Preview the next correct answer without grading the card.
Parameters
exercise(str): Exercise class name.profile(int): Active profile ID.key(str): Card identity.mode(str): Calendar scheduler.now(float): Presentation timestamp.
Returns
- ReviewInterval: Delay to display and reuse when the answer is submitted.
Examples
>>> CalendarPractice(Database()).correct_interval("NoteNames", profile=1, key="abc", mode="FSRS", now=1000).seconds
600
CalendarPractice.passing_intervals
def passing_intervals(
exercise: str,
*,
profile: int,
key: str,
mode: str,
now: float,
) -> dict[Rating, ReviewInterval]
Preview the three passing outcomes from one snapshot of this card.
Parameters
exercise(str): Exercise class name.profile(int): Active profile.key(str): Card identity.mode(str): Calendar scheduler.now(float): Time of the correct answer.
Returns
- dict: Passing grades and their previews, including the state to save.
Examples
>>> practice = CalendarPractice(Database())
>>> practice.passing_intervals("NoteNames", profile=1, key="abc", mode="SM-2", now=0)[Rating.Good].seconds
600
CalendarPractice.grade
def grade(
exercise: str,
*,
profile: int,
key: str,
mode: str,
correct: bool,
now: float,
manual_rating: Rating | None = None,
preview: ReviewInterval | None = None,
) -> None
Reschedule a card from the first submission to this presentation.
Parameters
exercise(str): Exercise class name.profile(int): Active profile ID.key(str): Stable card identity.mode(str): Scheduler selected for this review.correct(bool): Whether the first submission was correct.manual_rating(Rating or None): Button grade or automatic Again in self-grading mode. None uses the automatic schedule.now(float): Answer timestamp.preview(ReviewInterval or None): Correct-answer interval shown for this presentation.
Examples
>>> from alto.exercises.library import NoteNames
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> practice = CalendarPractice(db)
>>> question = practice.take(NoteNames(), profile=ada.id, mode="SM-2", now=1000)
>>> practice.grade("NoteNames", profile=ada.id, key=question.item_key(), mode="SM-2", correct=True, now=1002)
>>> db.conn.execute("SELECT due FROM review_schedules").fetchone()[0]
87402.0