alto.ui.backup_flow
Exporting a backup and importing one: the file dialogs, the questions asked, and the safety copy made before anything is replaced.
Everything Alto keeps goes into a backup (the database and the saved preferences), and importing one replaces everything, so an import into a clean install leaves it as if nothing had changed. Before an import replaces what is there, a backup of that is saved next to the database, so a wrong choice can be undone.
Examples
>>> default_name(now=0.0).endswith(".altobackup")
True
default_name
def default_name(
*,
now: float | None = None,
) -> str
Suggest a file name for a backup made now.
Parameters
now(float or None, default None): The time as a timestamp; the clock is used if None. Keyword-only.
Returns
- str: For example
alto-backup-2026-11-13.altobackup.
Examples
>>> default_name(now=datetime(2026, 11, 13, 12).timestamp())
'alto-backup-2026-11-13.altobackup'
counted
def counted(
number: int,
*,
noun: str,
) -> str
Write a count with its noun, in the plural unless there is one.
Parameters
number(int): The count.noun(str): The singular noun. Keyword-only.
Returns
- str: For example “1 profile” or “12,345 answers”.
Examples
>>> counted(1, noun="profile"), counted(12345, noun="answer")
('1 profile', '12,345 answers')
describe
def describe(info: BackupInfo) -> str
Say what a backup holds and when it was made, for the question asked before importing it.
Parameters
info(BackupInfo): What the backup says about itself.
Returns
- str: A sentence or two.
Examples
>>> text = describe(BackupInfo(datetime(2026, 11, 13, 9, 30).timestamp(), app_version="0.1.0", schema_version=1,
... profiles=2, attempts=1500))
>>> text
'Made on 13 November 2026, 09:30 by Alto 0.1.0. It holds 2 profiles and 1,500 answers.'
export_backup
def export_backup(
parent: QWidget,
*,
db: Database,
) -> Path | None
Ask where to save a backup, and write it.
Parameters
parent(QWidget): The window the dialogs belong to.db(Database): The database to back up. Keyword-only.
Returns
- Path or None: The file that was written, or None if the user cancelled or the backup could not be written (which is explained).
Examples
>>> export_backup(QWidget(), db=Database()) # doctest: +SKIP
PosixPath('/home/ada/alto-backup-2026-11-13.altobackup')
safety_copy
def safety_copy(db: Database) -> Path | None
Save a backup of what the database holds now, beside it, before it is replaced.
Parameters
db(Database): The database about to be replaced.
Returns
- Path or None: The file written, or None for a throwaway in-memory database, which has no folder to keep a copy in.
Raises
- BackupError: If the copy cannot be written.
Examples
>>> safety_copy(Database()) is None
True
import_backup
def import_backup(
parent: QWidget,
*,
db: Database,
) -> bool
Ask for a backup file and, once the user has agreed, replace everything with what it holds.
The file is read and checked completely first, so a damaged or foreign file changes nothing. After the user agrees, a backup of the current data is saved beside the database, then the database and the saved preferences are replaced. The caller has to reload what is on screen afterwards.
Parameters
parent(QWidget): The window the dialogs belong to.db(Database): The database to replace the contents of. Keyword-only.
Returns
- bool: True if the backup was applied; False if the user cancelled or the file was refused (which is explained).
Examples
>>> import_backup(QWidget(), db=Database()) # doctest: +SKIP
True