Skip to content

frontmost

frontmost

Frontmost application helpers (macOS).

Functions:

frontmost_app_name 

frontmost_app_name() -> Optional[str]

Return the frontmost app name, or None if unavailable.

Source code in src/diapason/desktop/frontmost.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def frontmost_app_name() -> Optional[str]:
    """Return the frontmost app name, or None if unavailable."""
    if sys.platform != "darwin":
        return None
    # Native Launch Services lookup is typically sub-millisecond and avoids
    # spawning osascript for every verification poll.
    try:
        from AppKit import NSWorkspace  # type: ignore

        app = NSWorkspace.sharedWorkspace().frontmostApplication()
        name = app.localizedName() if app is not None else None
        if name:
            return str(name)
    except (ImportError, AttributeError):
        pass
    script = (
        'tell application "System Events" to get name of first application '
        "process whose frontmost is true"
    )
    try:
        r = subprocess.run(
            ["osascript", "-e", script],
            capture_output=True,
            text=True,
            timeout=5,
            check=False,
        )
        if r.returncode != 0:
            return None
        name = (r.stdout or "").strip()
        return name or None
    except (OSError, subprocess.TimeoutExpired):
        logger.debug("frontmost app probe failed", exc_info=True)
        return None

wait_until_frontmost 

wait_until_frontmost(
    app_name: str, *, timeout_s: float = 2.0
) -> bool

Wait briefly for an app activation and report the observed result.

Source code in src/diapason/desktop/frontmost.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
def wait_until_frontmost(app_name: str, *, timeout_s: float = 2.0) -> bool:
    """Wait briefly for an app activation and report the observed result."""
    wanted = (app_name or "").casefold().replace(" ", "")
    if not wanted:
        return False
    deadline = time.monotonic() + max(0.0, timeout_s)
    while True:
        active = (frontmost_app_name() or "").casefold().replace(" ", "")
        if active and (active == wanted or active in wanted or wanted in active):
            return True
        if time.monotonic() >= deadline:
            return False
        time.sleep(0.04)

is_email_composer_context 

is_email_composer_context() -> bool

True when the user is likely composing email (Mail/Outlook frontmost).

Source code in src/diapason/desktop/frontmost.py 
70
71
72
def is_email_composer_context() -> bool:
    """True when the user is likely composing email (Mail/Outlook frontmost)."""
    return is_mail_frontmost()