Alto
latest

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, as Database.snapshot returns 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 as sqlite3.Row so 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 restore can 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, as snapshot returns 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")
[]