How to install hooks¶

A hook changes how the application itself starts and looks, rather than what it contains. With a hook you can create the Qt application object yourself, apply a style to every window, or show a splash screen while the session builds. The class you write for this is called a hook provider. It's an ordinary class, and it never changes which components the session builds.

A hook acts at one of a fixed set of moments, called hook points. Each point is named after the method the session calls on your provider. Some points take one provider and others take several, as the table below says.

You can install a provider from the session class or from the session file. Every example below shows both, as tabs, and picking a tab switches every tab on the site to the same choice.

Pick a hook point¶

A provider serves a point by having the method of its protocol. It may inherit from the protocol too, which lets a type checker hold it to the signature.

All five belong to the Qt frontend, so they only work on a QtSession. A plain Session calls no hook points and refuses a hook.

Write a provider¶

A provider is a class with the point's method:

from qtpy.QtWidgets import QApplication


class DarkTheme:
    def __init__(self, accent: str = "#4c8eda") -> None:
        self.accent = accent

    def configure_application(self, app: QApplication) -> None:
        app.setStyleSheet(f"QWidget {{ background: #202020; color: {self.accent}; }}")

It doesn't inherit from anything, because having the method is enough.

Install it¶

from redsun import AsHook
from redsun.qt import QtSession


class MyApp(QtSession):
    configure_application: AsHook[DarkTheme]

session: my-lab
frontend: qt

hooks:
  configure_application:
    provider: "mylab.theme:DarkTheme"

Use a provider redsun ships¶

redsun ships providers you can install without writing your own. A session file names one by a short name instead of a class path, and the session file reference lists the names. Choose a style shows one of them in use.

from redsun.qt.styles.napari import NapariStyle


class MyApp(QtSession):
    configure_application: AsHook[NapariStyle]

hooks:
  configure_application: napari

Pass constructor arguments¶

from typing import Annotated

from redsun import AsHook, Declare


class MyApp(QtSession):
    configure_application: Annotated[AsHook[DarkTheme], Declare(accent="#d47f4c")]

hooks:
  configure_application:
    provider: "mylab.theme:DarkTheme"
    kwargs:
      accent: "#d47f4c"

Install several at one point¶

A point that takes several providers calls them one after another, so a style and a provider of your own can both act on the application.

from typing import Annotated

from redsun import AsHook, Serves
from redsun.qt import QtHook, QtSession


class MyApp(QtSession):
    configure_application: AsHook[DarkTheme]
    icon: Annotated[AsHook[AppIcon], Serves(QtHook.CONFIGURE_APPLICATION)]

hooks:
  configure_application:
    - provider: "mylab.theme:DarkTheme"
    - provider: "mylab.theme:AppIcon"

AppIcon here is a second provider with a configure_application method. The providers of the class run first, in the order they are declared, and then those of the file, in the order of the list. A point that takes one provider refuses a second, wherever it was named.

Serve more than one hook point¶

A provider that keeps something between two points is installed at both as one object, so the state it keeps is shared.

from redsun import Serves
from redsun.qt import QtHook


class MyApp(QtSession):
    theme: Annotated[
        AsHook[DarkTheme],
        Serves(QtHook.CONFIGURE_APPLICATION, QtHook.CONFIGURE_MAIN_VIEW),
    ]

hooks:
  configure_application: &theme
    provider: "mylab.theme:DarkTheme"
  configure_main_view: *theme

Show a splash screen during the build¶

during_build covers a span of time, not a moment, so it returns a context manager that the session enters before the first build step and closes after the last. The session calls what the manager yields with each step's name as the step starts:

from collections.abc import Callable, Generator
from contextlib import contextmanager

from qtpy.QtGui import QPixmap
from qtpy.QtWidgets import QApplication, QSplashScreen


class Splash:
    def __init__(self, image: str) -> None:
        self.pixmap = QPixmap(image)
        if self.pixmap.isNull():
            raise ValueError(f"no image at {image!r}")

    @contextmanager
    def during_build(self, app: QApplication) -> Generator[Callable[[str], None]]:
        screen = QSplashScreen(self.pixmap)
        screen.show()
        app.processEvents()

        def report(step: str) -> None:
            screen.showMessage(step)
            app.processEvents()

        try:
            yield report
        finally:
            screen.close()

Check the image in the constructor, because a missing file gives an empty QPixmap instead of an error, and a splash that shows nothing.

The steps reported are the members of BuildStep, in order:

from redsun.session import BuildStep

Size a progress bar from len(BuildStep) rather than counting by hand, so it stays right when the steps change. Each step is reported when it starts, so fill the bar to the end after the yield. The finally closes the splash even when the build fails.

Undo what a hook did¶

A provider puts back what it changed, so that nothing of it outlives the session. Give it a shutdown method. The session calls it when it shuts down, once per provider however many points it serves, the last built first:

class DarkTheme:
    def configure_application(self, app: QApplication) -> None:
        self._app = app
        self._previous = app.styleSheet()
        app.setStyleSheet("...")

    def shutdown(self) -> None:
        self._app.setStyleSheet(self._previous)

A during_build provider needs none: its context manager closes what it opened.

Read a failure¶

A provider that fails doesn't stop the session, but a mistake in how you declared it does.

When a provider can't be built, or its hook method raises, the session logs the error, skips the provider at every point it serves, and carries on. The build summary lists it as Hooks skipped: DarkTheme (configure_application), and in a Qt session the failures button of the status bar lists it too. A skipped provider gets no shutdown call. A provider whose constructor raised is logged as cannot construct hook provider 'X' ....

Two cases stop the build instead. A create_application provider that fails stops it, because the session can't run on another application. And with strict: true in the session file, every skipped provider stops it.

A wrong declaration raises HookError and names the point. In a session file, an entry of the wrong shape is found when the file is read and raised as ConfigurationError, located as hooks.<point>.<key>. An entry in a list is located by its index, as hooks.configure_application[1].kwargs.

See also¶

• Hook points lists the points, the order providers run in, and what a provider owes the session.
• Frontends shows the points in the life of a Qt session.
• ADR 10 records why the points are what they are, and ADR 31 why a point takes several providers and a failing one is skipped.
• Wire components together connects components, which hooks do not do.