alto.learning.database
The SQLite store: profiles, every answer given, and what is known about each question. Pure Python (no Qt).
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.add_attempt(ada.id, exercise="NoteNames", item_key="k", attempt_no=1, answer="C", correct=True,
... duration_ms=2000, answered_at=100.0)
>>> db.count_attempts(ada.id)
1
check_snapshot
def check_snapshot(data: bytes) -> tuple[int, int, int]
Check that bytes are an intact Alto database that this version can read, and say what is in it.
Parameters
data(bytes): A snapshot, asDatabase.snapshotreturns it.
Returns
- tuple of (int, int, int): The schema version, the number of profiles and the number of answers.
Raises
- ValueError: If the data is not a SQLite database, is damaged, is not an Alto database, or has a newer schema than this version knows.
Examples
>>> check_snapshot(Database().snapshot())
(1, 0, 0)
>>> check_snapshot(b"not a database")
Traceback (most recent call last):
...
ValueError: This is not an Alto database.
Profile
Profile(
id: int,
*,
name: str,
)
A person who practises: their answers are kept apart from everyone else’s.
Attributes
id(int): The profile’s row number in the database.name(str): The name shown in the interface. Keyword-only.
Examples
>>> Profile(1, name="Ada")
Profile(id=1, name='Ada')
ItemRecord
ItemRecord(
strain: float,
*,
seen: int,
first_try_right: int,
wrong_attempts: int,
total_first_ms: int,
last_seen: float,
signature: str,
payload: str,
item_key: str = '',
)
What a profile’s history says about one question.
Attributes
strain(float): How much practice the question needs; higher means it comes back sooner.seen(int): How many times the question was shown and answered. Keyword-only.first_try_right(int): How many of those showings were answered right first time. Keyword-only.wrong_attempts(int): How many wrong answers there have been in all. Keyword-only.total_first_ms(int): Time to the first answer, summed over the showings, in milliseconds. Keyword-only.last_seen(float): When the question was last answered, as a timestamp. Keyword-only.signature(str): The exercise settings it was asked under; it is only asked again while these are unchanged. Keyword-only.payload(str): The question itself as JSON, so it can be asked again. Keyword-only.item_key(str, default ““): The question’s identity. Empty when the record is built to be saved, filled in when it is read back. Keyword-only.
Examples
>>> record = ItemRecord(2.0, seen=3, first_try_right=1, wrong_attempts=2, total_first_ms=9000,
... last_seen=100.0, signature="s", payload="{}")
>>> record.seen
3
Database
Database(path: str | Path = ':memory:')
The SQLite database behind profiles, answers and per-question history.
Attributes
conn(sqlite3.Connection): The open connection, with rows returned assqlite3.Rowso columns can be read by name.
Examples
>>> db = Database() # in memory; give a path to keep it on disk
>>> db.profiles()
[]
>>> db.add_profile("Ada")
Profile(id=1, name='Ada')
Constructor
Open the database, creating it and its tables if they do not exist.
Parameters
path(str or Path, default “:memory:”): The file to use, whose folder is created if needed, or “:memory:” for a throwaway database.
Constructor examples
>>> db = Database()
>>> db.conn.execute("PRAGMA user_version").fetchone()[0] == SCHEMA_VERSION
True
Database.close
def close() -> None
Close the connection.
Examples
>>> db = Database()
>>> db.close()
Database.snapshot
def snapshot() -> bytes
Return the whole database as bytes: every profile, answer and question record, exactly as they are now.
Returns
- bytes: A complete SQLite database, which
restorecan load into another database.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> check_snapshot(db.snapshot())
(1, 1, 0)
Database.restore
def restore(data: bytes) -> None
Replace everything in the database with a snapshot, so it is exactly as it was when the snapshot was taken.
Profiles, answers and question records that are here now are gone afterwards, and the ones in the snapshot take their place with the same ids. A snapshot made by an older version of Alto is brought up to date.
Parameters
data(bytes): A snapshot, assnapshotreturns it.
Raises
- ValueError: If the data is not an intact Alto database, or was made by a newer version of Alto. The database is not changed.
Examples
>>> source = Database()
>>> ada = source.add_profile("Ada")
>>> target = Database()
>>> _ = target.add_profile("Someone else")
>>> target.restore(source.snapshot())
>>> [p.name for p in target.profiles()]
['Ada']
Database.profiles
def profiles() -> list[Profile]
Return every profile, sorted by name without regard to case.
Returns
- list of Profile: The profiles.
Examples
>>> db = Database()
>>> _ = db.add_profile("ben")
>>> _ = db.add_profile("Ada")
>>> [p.name for p in db.profiles()]
['Ada', 'ben']
Database.profile
def profile(profile_id: int) -> Profile | None
Return one profile by its id.
Parameters
profile_id(int): The profile’s id.
Returns
- Profile or None: The profile, or None if there is none with that id.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> # noinspection PyUnresolvedReferences
>>> db.profile(ada.id).name
'Ada'
>>> db.profile(999) is None
True
Database.add_profile
def add_profile(name: str) -> Profile
Create a profile.
Parameters
name(str): The name. Runs of spaces are collapsed to one, and case does not matter when checking for a duplicate.
Returns
- Profile: The new profile.
Raises
- ValueError: If the name is empty, or is already taken.
Examples
>>> db = Database()
>>> db.add_profile(" Ada Lovelace ")
Profile(id=1, name='Ada Lovelace')
>>> db.add_profile("ada lovelace")
Traceback (most recent call last):
...
ValueError: There is already a profile called ada lovelace.
Database.delete_profile
def delete_profile(profile_id: int) -> None
Delete a profile together with all of its answers and question history.
Parameters
profile_id(int): The profile’s id.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.delete_profile(ada.id)
>>> db.profiles()
[]
Database.get_item
def get_item(
profile_id: int,
*,
exercise: str,
item_key: str,
) -> ItemRecord | None
Return what is known about one question for a profile.
Parameters
profile_id(int): The profile’s id.exercise(str): The exercise’s class name. Keyword-only.item_key(str): The question’s identity. Keyword-only.
Returns
- ItemRecord or None: The record, or None if the question has never been answered.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.get_item(ada.id, exercise="NoteNames", item_key="k") is None
True
Database.save_item
def save_item(
profile_id: int,
*,
exercise: str,
item_key: str,
item: ItemRecord,
) -> None
Store what is known about a question, replacing any earlier record of it.
Parameters
profile_id(int): The profile’s id.exercise(str): The exercise’s class name. Keyword-only.item_key(str): The question’s identity. Keyword-only.item(ItemRecord): What to store. Keyword-only.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> record = ItemRecord(2.0, seen=1, first_try_right=0, wrong_attempts=1, total_first_ms=3000,
... last_seen=100.0, signature="s", payload="{}")
>>> db.save_item(ada.id, exercise="NoteNames", item_key="k", item=record)
>>> # noinspection PyUnresolvedReferences
>>> db.get_item(ada.id, exercise="NoteNames", item_key="k").strain
2.0
Database.add_attempt
def add_attempt(
profile_id: int,
*,
exercise: str,
item_key: str,
attempt_no: int,
answer: str,
correct: bool,
duration_ms: int,
answered_at: float,
) -> None
Log one answer, right or wrong.
Parameters
profile_id(int): The profile’s id.exercise(str): The exercise’s class name. Keyword-only.item_key(str): The question’s identity. Keyword-only.attempt_no(int): 1 for the first answer to this showing of the question, 2 for the second and so on. Keyword-only.answer(str): What was answered. Keyword-only.correct(bool): Whether it was right. Keyword-only.duration_ms(int): How long it took, in milliseconds. Keyword-only.answered_at(float): When it was answered, as a timestamp. Keyword-only.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.add_attempt(ada.id, exercise="NoteNames", item_key="k", attempt_no=1, answer="C", correct=False,
... duration_ms=1500, answered_at=50.0)
>>> [(r["answer"], r["correct"]) for r in db.attempts(ada.id)]
[('C', 0)]
Database.attempts
def attempts(
profile_id: int,
*,
exercise: str | None = None,
) -> list[sqlite3.Row]
Return all of a profile’s answers in the order they were given.
Parameters
profile_id(int): The profile’s id.exercise(str or None, default None): Only answers to this exercise (its class name); every exercise if None. Keyword-only.
Returns
- list of sqlite3.Row: Every column of each answer.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> for i, name in enumerate(["NoteNames", "IntervalNames"]):
... db.add_attempt(ada.id, exercise=name, item_key="k", attempt_no=1, answer="x", correct=True,
... duration_ms=1000, answered_at=float(i))
>>> [r["exercise"] for r in db.attempts(ada.id)]
['NoteNames', 'IntervalNames']
>>> [r["exercise"] for r in db.attempts(ada.id, exercise="IntervalNames")]
['IntervalNames']
Database.attempts_in
def attempts_in(
profile_ids: list[int] | None = None,
*,
exercise: str | None = None,
since: float | None = None,
) -> list[sqlite3.Row]
Return answers given, oldest first, for some profiles, an exercise and a period.
Parameters
profile_ids(list of int or None, default None): The profiles to include; every profile if None.exercise(str or None, default None): Only this exercise (its class name); every exercise if None. Keyword-only.since(float or None, default None): Only answers from this timestamp on; the whole history if None. Keyword-only.
Returns
- list of sqlite3.Row: Each answer’s exercise, attempt number, correctness, duration in milliseconds and time.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> for t in (10.0, 20.0, 30.0):
... db.add_attempt(ada.id, exercise="NoteNames", item_key="k", attempt_no=1, answer="C", correct=True,
... duration_ms=1000, answered_at=t)
>>> [r["answered_at"] for r in db.attempts_in([ada.id], since=15.0)]
[20.0, 30.0]
Database.strained_items
def strained_items(
profile_ids: list[int] | None = None,
*,
exercise: str | None = None,
since: float | None = None,
min_strain: float = 0.0,
limit: int = 10,
) -> list[sqlite3.Row]
Return the questions that need most practice, the same question from different profiles counted together.
Parameters
profile_ids(list of int or None, default None): The profiles to include; every profile if None.exercise(str or None, default None): Only this exercise (its class name); every exercise if None. Keyword-only.since(float or None, default None): Only questions last seen from this timestamp on; the whole history if None. Keyword-only.min_strain(float, default 0.0): Leave out questions with less strain than this. Keyword-only.limit(int, default 10): The most questions to return. Keyword-only.
Returns
- list of sqlite3.Row: Each question’s exercise, key, average strain, times seen, wrong attempts and stored payload, most strained first.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> for key, strain in (("easy", 0.5), ("hard", 4.0)):
... item = ItemRecord(strain, seen=1, first_try_right=0, wrong_attempts=1, total_first_ms=1000,
... last_seen=1.0, signature="s", payload="{}")
... db.save_item(ada.id, exercise="NoteNames", item_key=key, item=item)
>>> [r["item_key"] for r in db.strained_items([ada.id], min_strain=1.0)]
['hard']
Database.count_attempts
def count_attempts(
profile_id: int,
*,
exercise: str | None = None,
since: float | None = None,
until: float | None = None,
) -> int
Return how many answers a profile has given, optionally of one exercise and within a period.
Parameters
profile_id(int): The profile’s id.exercise(str or None, default None): Count only answers to this exercise (a class name); all exercises if None. Keyword-only.since(float or None, default None): Count only answers given at or after this time (a timestamp). Keyword-only.until(float or None, default None): Count only answers given before this time (a timestamp). Keyword-only.
Returns
- int: The number of answers, wrong ones included.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.count_attempts(ada.id)
0
>>> for t in (1.0, 5.0, 9.0):
... db.add_attempt(ada.id, exercise="NoteNames", item_key="k", attempt_no=1, answer="C", correct=True,
... duration_ms=1000, answered_at=t)
>>> db.count_attempts(ada.id, since=2.0, until=9.0) # from the start of the period up to, not including, its end
1
Database.attempt_rows
def attempt_rows(
profile_id: int,
*,
limit: int = 10000,
exercise: str | None = None,
since: float | None = None,
until: float | None = None,
) -> list[sqlite3.Row]
Return the newest answers first, each with the stored question it was an answer to (if that is still known).
Parameters
profile_id(int): The profile’s id.limit(int, default 10000): The most rows to return. Keyword-only.exercise(str or None, default None): Return only answers to this exercise (a class name); all exercises if None. Keyword-only.since(float or None, default None): Return only answers given at or after this time (a timestamp). Keyword-only.until(float or None, default None): Return only answers given before this time (a timestamp). Keyword-only.
Returns
- list of sqlite3.Row: Each answer’s time, exercise, question key, answer, correctness, attempt number, duration and question payload.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> for t in (1.0, 2.0):
... db.add_attempt(ada.id, exercise="NoteNames", item_key="k", attempt_no=1, answer="C", correct=True,
... duration_ms=1000, answered_at=t)
>>> [r["answered_at"] for r in db.attempt_rows(ada.id)]
[2.0, 1.0]
>>> [r["answered_at"] for r in db.attempt_rows(ada.id, since=1.5)]
[2.0]
Database.item_rows
def item_rows(
profile_id: int,
*,
limit: int = 10000,
) -> list[sqlite3.Row]
Return what is known about each of a profile’s questions, the most strained first.
Parameters
profile_id(int): The profile’s id.limit(int, default 10000): The most rows to return. Keyword-only.
Returns
- list of sqlite3.Row: Every column of each question’s record.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> db.item_rows(ada.id)
[]
Database.profile_rows
def profile_rows() -> list[sqlite3.Row]
Return every profile with how many answers and questions it has.
Returns
- list of sqlite3.Row: Each profile’s id, name, creation time, number of answers and number of questions, sorted by name.
Examples
>>> db = Database()
>>> _ = db.add_profile("Ada")
>>> [(r["name"], r["attempts"], r["questions"]) for r in db.profile_rows()]
[('Ada', 0, 0)]
Database.replay_candidates
def replay_candidates(
profile_id: int,
*,
exercise: str,
signature: str,
hardest: int = 25,
random_extra: int = 10,
) -> list[ItemRecord]
Return questions asked before under these same settings: the ones that need most practice, plus a few at random.
Parameters
profile_id(int): The profile’s id.exercise(str): The exercise’s class name. Keyword-only.signature(str): The exercise’s current settings signature; only questions asked under it qualify. Keyword-only.hardest(int, default 25): How many of the most strained questions to include. Keyword-only.random_extra(int, default 10): How many more to pick at random. Keyword-only.
Returns
- list of ItemRecord: The questions, each at most once.
Examples
>>> db = Database()
>>> ada = db.add_profile("Ada")
>>> item = ItemRecord(3.0, seen=1, first_try_right=0, wrong_attempts=1, total_first_ms=1000,
... last_seen=1.0, signature="s1", payload="{}")
>>> db.save_item(ada.id, exercise="NoteNames", item_key="k", item=item)
>>> [row_.item_key for row_ in db.replay_candidates(ada.id, exercise="NoteNames", signature="s1")]
['k']
>>> db.replay_candidates(ada.id, exercise="NoteNames", signature="other settings")
[]