Application suspension

[davep]

Introduction

This PR adds two related features to Textual applications:

• An App.suspend context manager that allows the dev to temporarily stop application mode to run some other code; a classic example would be shelling out to an external editor.
• An action (App.action_suspend_process) that, where appropriate (currently GNU/Linux and macOS, perhaps other Unix and Unix-like environments), suspends the application as the foreground task.

App.suspend

Here's a simple example of using the App.suspend context manager:

from os import system
from pathlib import Path
from tempfile import NamedTemporaryFile

from textual import on
from textual.app import App, ComposeResult
from textual.reactive import var
from textual.widgets import Button, Static

class EditInVimApp(App[None]):

    text: var[str] = var("Hello, World!", init=False)

    def compose(self) -> ComposeResult:
        yield Button("Edit in vim")
        yield Static(self.text)

    def edit_in_vim(self) -> str:
        with NamedTemporaryFile(delete=False) as file_to_edit:
            file_to_edit.write(self.text.encode())
        try:
            with self.suspend():
                system(f"vim {file_to_edit.name}")
                return Path(file_to_edit.name).read_text()
        finally:
            Path(file_to_edit.name).unlink()

    @on(Button.Pressed)
    def edit_text(self) -> None:
        self.text = self.edit_in_vim()

    def watch_text(self) -> None:
        self.query_one(Static).update(self.text)

if __name__ == "__main__":
    EditInVimApp().run()

Screen.Recording.2024-01-30.at.13.24.40.mov

Suspend as foreground task

This PR also adds support for suspending the application as the foreground task. This is done by providing App.action_suspend_process as an action that can be bound to a key combination, the conventional choice being Ctrl+Z. This feature is only available on Unix and Unix-like operating systems (currently tested on GNU/Linux and macOS). On Windows it is a no-op. No matter the host operating system it is also a no-op when running under Textual Web.

Screen.Recording.2024-01-30.at.13.30.05.mov

Suspend and resume signals

Because the developer may with to perform some actions as a suspend happens, or when a resume happens, this PR also makes use of the new Signal facility. The developer can subscribe to App.app_suspend_signal and App.app_resume_signal to be notified when a suspend or a resume happens.

Using this, an example app with code like this in it (to log when a suspend and a resume happens):

    def suspending(self) -> None:
        self.query_one(Log).write_line("Suspending!")

    def resuming(self) -> None:
        self.query_one(Log).write_line("Resuming!")

    def on_mount(self) -> None:
        self.app_suspend_signal.subscribe(self, self.suspending)
        self.app_resume_signal.subscribe(self, self.resuming)

will log the suspends and the resumes:

Screen.Recording.2024-01-30.at.14.18.38.mov

App.suspend and SuspendNotSupported

If App.suspend is called in an environment that isn't supported a SuspendNotSupported exception will be raised. Using code like this:

    @on(Button.Pressed, "#countdown")
    def countdown(self) -> None:
        try:
            with self.app.suspend():
                for n in reversed(range(10)):
                    print(n)
                    sleep(1)
        except SuspendNotSupported:
            self.notify("I'm sorry Dave, I'm afraid I can't do that", severity="error")

in the test application above, and then run under Textual Web, will show the above notification:

Screen.Recording.2024-01-30.at.14.24.32.mov

[willmcgugan]

Great. Just some suggestions, mostly doc related.

[davep]

@willmcgugan Changes made and doc-tweaks merged.

[willmcgugan]

Nice