alto.selfupdate
Replacing a packaged copy of Alto with a newer release: whether it can, getting the update, checking it, and handing over.
A packaged copy is Alto frozen with PyInstaller, in a folder the user owns: ~/.local/opt/alto on Linux, made by install.sh,
and a folder under %LOCALAPPDATA%\Programs on Windows, made by the installer. Neither needs administrator rights, so Alto can
fetch the new package, check it, and start the program that installs it. Nothing is installed unless the signature on the list of
checksums verifies against a key that came with Alto, the list names the file, and the file’s hash is the one listed (see
alto.updates). This module has no Qt, so the interface runs it on a worker thread and shows its progress.
Examples
>>> self_update_target(executable=Path("/nowhere/alto"), system="linux") is None
True
UpdateError
class UpdateError(Exception)
Something went wrong in getting or checking an update. The message says what, in words for the person.
UpdateCancelled
class UpdateCancelled(Exception)
The person cancelled the update before it was ready.
Target
Target(
system: str,
folder: Path,
prefix: Path | None,
)
A packaged copy that can replace itself, and where it is.
Attributes
system(str): “linux” or “windows”.folder(Path): The folder the program is in.prefix(Path or None): On Linux, the folder that holdsopt/altoandbin/alto(~/.localby default); None on Windows.
Examples
>>> Target("windows", folder=Path("C:/Alto"), prefix=None).system
'windows'
Prepared
Prepared(
work: Path,
installer: Path | None,
root: Path | None,
)
An update that has been downloaded and checked, and is ready to be handed over.
Attributes
work(Path): The temporary folder that holds it, which is removed after the update.installer(Path or None): On Windows, the installer to run.root(Path or None): On Linux, the unpacked download, with itsinstall.sh.
Examples
>>> Prepared(Path("/tmp/x"), installer=None, root=Path("/tmp/x/unpacked/alto-0.1.0")).installer is None
True
self_update_target
def self_update_target(
*,
executable: Path | None = None,
system: str | None = None,
) -> Target | None
Say whether the running copy can replace itself, and if so where it is.
On Linux a copy can if it was put in <prefix>/opt/alto by install.sh, which links <prefix>/bin/alto to it; a folder that
someone unpacked and ran from cannot. On Windows a copy can if the installer made it, which leaves unins000.exe beside it.
Parameters
executable(Path or None, default None): The running program; the one that is running if None. Keyword-only.system(str or None, default None): “linux” or “windows”; this computer’s if None. Keyword-only.
Returns
- Target or None: Where the copy is, or None if it cannot replace itself.
Examples
>>> self_update_target(executable=Path("/usr/bin/python3"), system="linux") is None
True
>>> self_update_target(executable=Path("/nowhere/alto.exe"), system="windows") is None
True
download
def download(
url: str,
*,
destination: Path,
allowed: str,
max_bytes: int,
progress: Callable[[int, int], None],
cancelled: Callable[[], bool],
seconds: int = 30,
) -> str
Fetch a file, checking the address, the size and the connection, and give its SHA-256 hash.
Parameters
url(str): The address. It must start withallowed.destination(Path): Where to write the file. Nothing is left there if the download fails or is cancelled. Keyword-only.allowed(str): What the address must start with, which is where a release keeps its files. Keyword-only.max_bytes(int): The most to accept, by the size the server states and by what actually arrives. Keyword-only.progress(Callable): Called with the bytes received so far and the size the server states (0 if it does not say). Keyword-only.cancelled(Callable): Asked now and then; True stops the download. Keyword-only.seconds(int, default 30): How long to wait for the server at a time. Keyword-only.
Returns
- str: The SHA-256 hash of what was written, in hexadecimal.
Raises
- UpdateError: If the address is not allowed, the file is too large, the connection is not secure, or the download fails.
- UpdateCancelled: If
cancelledsaid so.
extract_tarball
def extract_tarball(
archive: Path,
*,
destination: Path,
) -> Path
Unpack the Linux download, refusing anything that would land outside the folder.
Parameters
archive(Path): The.tar.gz.destination(Path): The folder to unpack it in. Keyword-only.
Returns
- Path: The one folder the download unpacks to, which holds
install.shand the program.
Raises
- UpdateError: If it cannot be unpacked safely, or is not what an update needs.
ignore_progress
def ignore_progress(
done: int,
total: int,
) -> None
Take a note of progress and do nothing with it, for a download whose progress nobody watches.
Parameters
done(int): The bytes received so far.total(int): The total the server states.
Examples
>>> ignore_progress(1, 2)
prepare_update
def prepare_update(
release: updates.Release,
*,
target: Target,
work: Path,
keys: tuple[str, ...],
machine: str,
base: str = updates.DOWNLOAD_BASE,
status: Callable[[str], None],
progress: Callable[[int, int], None],
cancelled: Callable[[], bool],
) -> Prepared
Download a release for this copy and check it: its signed list of checksums, then the file against its listed hash.
Parameters
release(updates.Release): The release to install.target(Target): The copy that will be replaced.work(Path): An empty folder to work in.keys(tuple of str): The public keys (base64) a signature may be made with. Keyword-only.machine(str): The processor, asplatform.machine()says it. Keyword-only.base(str, default updates.DOWNLOAD_BASE): Where the release keeps its files. Keyword-only.status(Callable): Called with what is being done, in words for the person. Keyword-only.progress(Callable): Called with the bytes received so far and the total, while the file downloads. Keyword-only.cancelled(Callable): Asked now and then; True stops. Keyword-only.
Returns
- Prepared: The checked update, ready to be handed over.
Raises
- UpdateError: If anything is missing or does not check out. Nothing is installed.
- UpdateCancelled: If
cancelledsaid so.
clean_environment
def clean_environment(env: Mapping[str, str]) -> dict[str, str]
Undo what PyInstaller did to the environment, for a program that this one starts.
A packaged program puts its own libraries first on the library path, which would make the system’s sh, tar and the next
Alto load them. PyInstaller keeps the original in LD_LIBRARY_PATH_ORIG, and asks a program that restarts itself to reset
what it passed on. The desktop’s start-up token is for this launch only, so it is dropped too.
Parameters
env(Mapping): The environment of this program.
Returns
- dict of str to str: The environment to give the other.
Examples
>>> clean_environment({"LD_LIBRARY_PATH": "/app/lib", "LD_LIBRARY_PATH_ORIG": "/usr/lib", "_PYI_ARCHIVE_FILE": "x"})
{'LD_LIBRARY_PATH': '/usr/lib', 'PYINSTALLER_RESET_ENVIRONMENT': '1'}
>>> clean_environment({"LD_LIBRARY_PATH": "/app/lib", "LD_LIBRARY_PATH_ORIG": ""})
{'PYINSTALLER_RESET_ENVIRONMENT': '1'}
>>> clean_environment({"HOME": "/home/me"})
{'HOME': '/home/me', 'PYINSTALLER_RESET_ENVIRONMENT': '1'}
log_path
def log_path() -> Path
Give the file the Linux helper writes to, so that a failed update can be looked into.
Returns
- Path:
update.login Alto’s folder of the user’s cache.
Examples
>>> log_path().name
'update.log'
windows_handoff_command
def windows_handoff_command(
installer: Path,
*,
pid: int,
alto: Path,
) -> list[str]
Give the command that waits for Alto to end, runs the installer, and starts the old Alto again if the installer fails.
The installer must not start while Alto is still closing: it would find Alto’s files in use and, with no one to answer, give up. So Alto starts this command and quits, and the command waits for Alto’s process to be gone before it begins.
Parameters
installer(Path): The downloaded installer.pid(int): Alto’s process, which is waited for (for at most a minute). Keyword-only.alto(Path): The installedalto.exe, which is started again if the installer fails, so that the person is not left with no Alto. When it succeeds, the installer starts Alto itself (/RELAUNCH=1). Keyword-only.
Returns
- list of str: The program and its arguments.
Examples
>>> command = windows_handoff_command(Path("C:/Temp/setup.exe"), pid=42, alto=Path("C:/Alto/alto.exe"))
>>> command[0], command[1:-1] == list(POWERSHELL_ARGUMENTS)
('powershell.exe', True)
>>> text = base64.b64decode(command[-1]).decode("utf-16-le")
>>> "Wait-Process -Id 42" in text and "/RELAUNCH=1" in text
True
start_handoff
def start_handoff(
prepared: Prepared,
*,
target: Target,
pid: int | None = None,
log: Path | None = None,
environ: Mapping[str, str] | None = None,
) -> None
Start the program that installs the update, and return at once so that Alto can quit.
Parameters
prepared(Prepared): The checked update.target(Target): The copy that is replaced.pid(int or None, default None): The process to wait for, which is Alto; this one if None. Keyword-only.log(Path or None, default None): Where the Linux helper writes;log_path()if None. Keyword-only.environ(Mapping or None, default None): The environment to start from; this program’s if None. Keyword-only.
Raises
- UpdateError: If the update is missing what the system needs.
new_work_folder
def new_work_folder() -> Path
Make a new temporary folder for an update, whose name says what it is for.
Returns
- Path: The empty folder.
Examples
>>> folder = new_work_folder()
>>> folder.is_dir() and folder.name.startswith(LEFTOVER_PREFIX)
True
>>> folder.rmdir()
remove_leftovers
def remove_leftovers(
*,
older_than: float = 86400.0,
now: float | None = None,
root: Path | None = None,
) -> int
Remove the temporary folders of earlier updates that were never cleaned up, such as a Windows installer that was run and left.
Parameters
older_than(float, default 86400.0): How old, in seconds, a folder must be. Keyword-only.now(float or None, default None): The time to measure from; the clock’s if None. Keyword-only.root(Path or None, default None): The folder to look in; the system’s temporary folder if None. Keyword-only.
Returns
- int: How many folders were removed.
Examples
>>> remove_leftovers(root=Path("/no/such/folder"))
0