Alto
latest

alto.ui.update_flow

Checking for a newer Alto and installing it: the questions asked, the progress shown, and the restart afterwards.

The menu’s “Check for updates…” follows one of two channels, chosen in Settings: the newest release (the default), or the newest commit on the main branch. A copy installed with scripts/alto-install.sh can replace itself, from either, with uv tool install, showing its output, and restarts when OK is pressed. A packaged copy cannot replace itself, so it is told that a newer release exists and offered the page where it can be downloaded; it always follows releases. A copy run from a source folder is told to update with git.

Examples

>>> brief("fatal: unable to access 'https://example.org/': Could not resolve host\n")
"fatal: unable to access 'https://example.org/': Could not resolve host"

brief

def brief(
    text: str,
    *,
    limit: int = 400,
) -> str

Cut what a program printed down to what is worth showing in a message: the end of it, without the blank space around it.

Parameters

  • text (str): What the program printed.
  • limit (int, default 400): The most characters to keep. Keyword-only.

Returns

  • str: The end of the text, at most limit characters long.

Examples

>>> brief("  one\ntwo  \n")
'one\ntwo'
>>> brief("x" * 10, limit=4)
'xxxx'

CommandRunner

CommandRunner(parent: QObject | None = None)

Bases: QObject

Run one program without freezing the window, handing on what it prints as it prints it, and how it ended.

Attributes

  • output (Signal): Emitted with each piece of text the program prints, as it arrives. Its errors are mixed in with it.
  • done (Signal): Emitted once, with the exit code and everything the program printed. The exit code is -1 if the program could not be started, was stopped for taking too long, or crashed.

Examples

>>> runner = CommandRunner()
>>> runner.running
False

Constructor

Make a runner that has not started anything.

Parameters

  • parent (QObject or None, default None): The object that owns it.

CommandRunner.running

@property
def running() -> bool

Say whether a program has been started and has not yet ended.

Returns

  • bool: True while it runs.

CommandRunner.start

def start(
    program: str,
    *,
    arguments: list[str],
    seconds: int = 0,
) -> None

Start a program.

Parameters

  • program (str): The program’s path.
  • arguments (list of str): What to give it. Keyword-only.
  • seconds (int, default 0): Stop it if it has not ended by then; 0 lets it take as long as it takes. Keyword-only.

Examples

>>> import sys
>>> runner = CommandRunner()
>>> runner.start(sys.executable, arguments=["-c", "import time; time.sleep(30)"])
>>> runner.stop()
>>> runner.running
False

CommandRunner.stop

def stop() -> None

Stop the program, if it is running, without announcing that it has ended.

Examples

>>> CommandRunner().stop()

saved_channel

def saved_channel() -> str

Return what the update check follows, as chosen in Settings.

Returns

  • str: “releases” for the newest release, or “main” for the newest commit on the main branch; “releases” if nothing valid is saved.

Examples

>>> saved_channel()
'releases'
>>> save_channel("main")
>>> saved_channel()
'main'
>>> save_channel("releases")

save_channel

def save_channel(channel: str) -> None

Remember what the update check follows.

Parameters

  • channel (str): “releases” or “main”. Anything else is saved as “releases”.

Examples

>>> save_channel("nonsense")
>>> saved_channel()
'releases'

WaitDialog

WaitDialog(
    parent: QWidget | None,
    *,
    text: str,
)

Bases: QDialog

A small window with a bar that keeps moving and a Cancel button, shown while something is asked for.

Attributes

  • ended (bool): Whether the asking has ended, by an answer, a failure or a cancel.
  • cancelled (bool): Whether the person cancelled it.

Constructor

Build the window.

Parameters

  • parent (QWidget or None): The window it belongs to.
  • text (str): What is being asked for. Keyword-only.

WaitDialog.reject

def reject() -> None

Cancel the asking.

CheckDialog

CheckDialog(
    parent: QWidget | None,
    *,
    source: Source,
    git: str,
)

Bases: WaitDialog

A waiting window while the address Alto came from is asked for the newest commit of its main branch.

Attributes

  • commit (str): The newest commit, once it is known; empty if it could not be found out.
  • error (str): What went wrong, if there is no commit.
  • runner (CommandRunner): The program that does the asking.

Constructor

Build the window; it asks nothing until run is called.

Parameters

  • parent (QWidget or None): The window it belongs to.
  • source (Source): Where the running copy of Alto came from. Keyword-only.
  • git (str): The path of the git program. Keyword-only.

CheckDialog.run

def run() -> None

Ask, showing the window until there is an answer.

Examples

>>> # noinspection PyTypeChecker
>>> CheckDialog(None, source=Source("https://example.org/a.git", commit="abc1234"), git="git").cancelled
False

ReleaseFetcher

ReleaseFetcher(parent: QObject | None = None)

Bases: QObject

Ask GitHub for the latest release on another thread, so that the window never freezes while it waits.

Attributes

  • done (Signal): Emitted once, with the HTTP status (0 if GitHub was not reached) and the answer or the reason there was none.

Examples

>>> ReleaseFetcher().cancel()

Constructor

Make a fetcher that has not asked anything.

Parameters

  • parent (QObject or None, default None): The object that owns it.

ReleaseFetcher.start

def start(
    *,
    seconds: int,
) -> None

Start asking.

Parameters

  • seconds (int): How long to wait for GitHub. Keyword-only.

ReleaseFetcher.cancel

def cancel() -> None

Stop caring about the answer; the thread ends by itself when GitHub answers or the time is up.

ReleaseDialog

ReleaseDialog(parent: QWidget | None)

Bases: WaitDialog

A waiting window while GitHub is asked for the latest release.

Attributes

  • release (Release or None): The latest release, once it is known; None if it could not be found out.
  • error (str): What went wrong, if there is no release.
  • fetcher (ReleaseFetcher): What does the asking.

Constructor

Build the window; it asks nothing until run is called.

Parameters

  • parent (QWidget or None): The window it belongs to.

ReleaseDialog.run

def run() -> None

Ask, showing the window until there is an answer.

Examples

>>> # noinspection PyTypeChecker
>>> ReleaseDialog(None).cancelled
False

UpdateDialog

UpdateDialog(
    parent: QWidget | None,
    *,
    command: tuple[str, list[str]],
)

Bases: QDialog

The window that shows an update being installed: a bar that keeps moving, what uv prints, and then what comes next.

It cannot be closed while the update runs, because stopping it half way could leave the installed copy broken. When it has finished it says so, and its one button closes it. After a successful update the caller restarts Alto.

Attributes

  • status (QLabel): What is happening.
  • bar (QProgressBar): A bar that keeps moving while the update runs, and fills when it has succeeded.
  • log (QPlainTextEdit): What uv prints, as it prints it.
  • button (QPushButton): Enabled when the update has ended.
  • ended (bool): Whether the update has ended.
  • succeeded (bool): Whether it ended well.
  • runner (CommandRunner): The program that does the update.

Constructor

Build the window; the update does not start until run is called.

Parameters

  • parent (QWidget or None): The window it belongs to.
  • command (tuple of str and list of str): The program that installs the update and its arguments. Keyword-only.

UpdateDialog.run

def run() -> bool

Install the update, showing the window until the person has read how it went.

Returns

  • bool: True if it succeeded and OK was pressed, so Alto should restart.

Examples

>>> # noinspection PyTypeChecker
>>> UpdateDialog(None, command=("uv", ["tool", "install", "alto"])).succeeded
False

UpdateDialog.reject

def reject() -> None

Close the window, but not while the update is running.

UpdateDialog.closeEvent

def closeEvent(event: QCloseEvent) -> None

Refuse to close while the update is running.

Parameters

  • event (QCloseEvent): The request to close.

check_for_updates

def check_for_updates(
    parent: QWidget,
    *,
    restart: Callable[[], None],
    quit_app: Callable[[], None] = QApplication.quit,
) -> None

Ask whether a newer Alto is available and, if the person agrees, install it and restart.

What is asked depends on the copy: one run from a source folder is told how it is updated; a packaged copy asks for the latest release and is offered its download page; one installed with the script follows what Settings says, the latest release or the main branch, and can install it.

Parameters

  • parent (QWidget): The window the questions are asked over.
  • restart (Callable): What to do after a successful update to start the new version in place of this one. Keyword-only.
  • quit_app (Callable, default QApplication.quit): What to do to close Alto once an update has been handed to the program that installs it, which is how a packaged copy is replaced. Keyword-only.

Examples

>>> check_for_updates  # doctest: +SKIP

check_release

def check_release(
    parent: QWidget,
    *,
    kind: InstallKind,
    source: Source | None,
    restart: Callable[[], None],
    quit_app: Callable[[], None],
) -> None

Ask GitHub for the latest release and compare it with the version that is running.

Parameters

  • parent (QWidget): The window the questions are asked over.
  • kind (InstallKind): What kind of copy is running: a packaged one is offered a download page, and one installed with the script is offered the update. Keyword-only.
  • source (Source or None): Where the running copy came from; None for a packaged copy. Keyword-only.
  • restart (Callable): What to do after a successful update. Keyword-only.
  • quit_app (Callable): What to do to close Alto once an update has been handed to the program that installs it. Keyword-only.

Examples

>>> check_release  # doctest: +SKIP

check_main

def check_main(
    parent: QWidget,
    *,
    source: Source,
    restart: Callable[[], None],
) -> None

Ask the address Alto came from for the newest commit on its main branch and compare it with the one that is running.

Parameters

  • parent (QWidget): The window the questions are asked over.
  • source (Source): Where the running copy came from. Keyword-only.
  • restart (Callable): What to do after a successful update. Keyword-only.

Examples

>>> check_main  # doctest: +SKIP

install

def install(
    parent: QWidget,
    *,
    source: Source,
    tag: str | None,
    restart: Callable[[], None],
) -> None

Install a release, or the newest commit of the main branch, showing the progress, and restart if it worked.

Parameters

  • parent (QWidget): The window the progress is shown over.
  • source (Source): Where the running copy came from. Keyword-only.
  • tag (str or None): The release to install, such as “v0.1.0”; None for the newest commit of the main branch. Keyword-only.
  • restart (Callable): What to do after a successful update. Keyword-only.

Examples

>>> install  # doctest: +SKIP

update_package

def update_package(
    parent: QWidget,
    *,
    release: updates.Release,
    target: selfupdate.Target,
    installed: str,
    quit_app: Callable[[], None],
) -> None

Offer to replace a packaged copy with a release: download and check it, say that Alto will restart, and hand over.

Parameters

  • parent (QWidget): The window the questions are asked over.
  • release (updates.Release): The newer release. Keyword-only.
  • target (selfupdate.Target): The copy that will be replaced. Keyword-only.
  • installed (str): The version that is running. Keyword-only.
  • quit_app (Callable): What to do to close Alto once the update has been handed to the program that installs it. Keyword-only.

Examples

>>> update_package  # doctest: +SKIP