Add xss-lock backend and rename to xidle-inhibit

The backend comes from ~/.config/xidle-inhibit/config, else the installed locker. With xss-lock, pausing X blanking alone blocks locking and Lock uses loginctl; the unit's ExecStopPost runs --cleanup. Inhibits from the old xautolock-inhibit state file are taken over once. Also fix mypy with pygobject-stubs 2.19.
Uniform installation instructions in README
2026-10-23 19:53:42 +02:00 · 2026-10-20 22:01:28 +02:00 · 2026-10-17 16:50:04 +02:00 · 2026-10-17 16:49:40 +02:00 · 2026-10-16 17:21:34 +02:00 · 2026-10-15 23:39:11 +02:00
8 changed files with 634 additions and 383 deletions
@@ -1 +1,4 @@
 CLAUDE.md
 __pycache__/
 .mypy_cache/
 .ruff_cache/
@@ -3,7 +3,7 @@
 # Maintainer: Daniele Fucini <dfucini [at] gmail [dot] com>
 pkgname=xautolock-inhibit
-pkgver=0.1.2
+pkgver=0.2
 pkgrel=1
 pkgdesc='Honor org.freedesktop.ScreenSaver inhibit requests by disabling xautolock'
 arch=('any')
@@ -17,7 +17,7 @@ depends=('libx11'
 makedepends=('git')
 source=("git+$url?signed#tag=$pkgver")
 validpgpkeys=('7E12BC1FF3B6EDB2CD8053EB981A2B2A3BBF5514')
-sha256sums=('6713c706e422cea0ae346fc7bd16611dd0e32487acf4d15ec3a4db325eaaa0c7')
+sha256sums=('c9d4bf5de7a1bd3f8ddf0cd2103e01891726877cfe12cb0f545c880b0df6f44f')
 package()
 {
@@ -1,73 +1,110 @@
-# xautolock-inhibit
+# xidle-inhibit
-Makes screen locking with `xautolock` respect the "don't lock the screen" requests that apps send, on X11 sessions without a desktop environment (for example a plain window manager like xmonad).
+Makes screen locking with `xautolock` or `xss-lock` respect the "don't lock the screen" requests that apps send, on X11 sessions without a desktop environment (for example a plain window manager like xmonad).
-Browsers, Steam, gamemode and other apps ask the desktop not to lock or blank the screen while a video or game is running, through the D-Bus service `org.freedesktop.ScreenSaver`. Without a desktop environment nothing provides that service, so the requests are dropped and the screen locks in the middle of a video. xautolock-inhibit provides it:
+Browsers, Steam, gamemode and other apps ask the desktop not to lock or blank the screen while a video or game is running, through the D-Bus service `org.freedesktop.ScreenSaver`. Without a desktop environment nothing provides that service, so the requests are dropped and the screen locks in the middle of a video. xidle-inhibit provides it:
- While at least one request is active, it runs `xautolock -disable` and pauses X screen blanking and DPMS.
+- While at least one request is active, it pauses X screen blanking and DPMS, and with xautolock also runs `xautolock -disable`. xss-lock locks when the X screensaver starts, so pausing it is enough.
- When the last request is released, it waits a few seconds, then runs `xautolock -enable` and resumes blanking.
+- When the last request is released, it waits a few seconds, then resumes blanking (and runs `xautolock -enable`).
-xautolock stays your locker; xautolock-inhibit only switches it off and on.
+Your locker setup stays as it is; xidle-inhibit only holds it off.
 Formerly `xautolock-inhibit`, which supported only xautolock.
 ## How it works
- Owns `org.freedesktop.ScreenSaver` on the session bus at both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` (apps differ on the path), and implements `Inhibit` and `UnInhibit`.
+- Owns `org.freedesktop.ScreenSaver` on the session bus at both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` (apps differ on the path), and implements `Inhibit`, `UnInhibit` and `Lock`.
 - Tracks requests per D-Bus client. If a client disconnects without releasing them (for example a browser crash), its requests are released.
- Runs `xautolock` only when the number of active requests goes from 0 to 1 or back to 0. Re-enabling waits a few seconds (`--release-delay`), because browsers send short bursts of requests when a video starts.
+- Blocks and unblocks only when the number of active requests goes from 0 to 1 or back to 0. Unblocking waits a few seconds (`--release-delay`), because browsers send short bursts of requests when a video starts.
 - Pauses X blanking with `XScreenSaverSuspend`, the same mechanism mpv uses, instead of changing `xset` settings. The X server ends the pause by itself if the daemon exits or crashes.
 - Requests whose reason is on an ignore list (default: `Playing audio`) are accepted and logged, but don't block locking. Firefox-based browsers send one for audio playback, which would otherwise keep the screen unlocked while music plays with nobody at the computer.
- On exit (including SIGTERM), it re-enables xautolock. The systemd unit also runs `xautolock -enable` when it stops, as a fallback.
+- Keeps the requests it holds in `$XDG_RUNTIME_DIR/xidle-inhibit.json`, so a restarted or crashed daemon takes them over. They are taken over only if the previous daemon stopped at most 30 seconds ago (`--restore-window`) on the same session bus, and only for clients still connected. A request released while no daemon was running can't be seen, so an old file isn't trusted.
 - With xautolock, it re-enables xautolock on exit (including SIGTERM). The systemd unit also runs `xidle-inhibit --cleanup` when it stops, which does the same, as a fallback.
 - `Lock` runs `xautolock -locknow`, or `loginctl lock-session` with xss-lock.
 - If another program (a desktop environment) already owns `org.freedesktop.ScreenSaver`, it exits with status 2 instead of taking over.
 ## Requirements
- `xautolock`, already running in the session
+- `xautolock` or `xss-lock`, already running in the session
 - `python`, `python-gobject`
 - `libx11`, `libxss`
 ## Installation
-Build and install the package with the included PKGBUILD:
+Build and install the package with the included PKGBUILD, which builds the signed release tag set in `pkgver`:
 ```
 makepkg -si
 ```
-Then start it from your window manager's startup, after `xautolock`. For xmonad:
+Or, with aurutils, build it into a local repository with `aur build` and install it with pacman.
 Then start it from your window manager's startup, after the locker. For xmonad with xautolock:
 ```haskell
 spawnOnce "xautolock -time 10 -locker slock -detectsleep"
-spawnOnce "systemctl --user start xautolock-inhibit"
+spawnOnce "systemctl --user start xidle-inhibit"
 ```
 With xss-lock, the lock timeout is the X screensaver timeout (`xset s`):
 ```haskell
 spawnOnce "xset s 600"
 spawnOnce "xss-lock -- slock"
 spawnOnce "systemctl --user start xidle-inhibit"
 ```
 The unit has no `[Install]` section on purpose. Enabling it at login would also start it in a desktop environment, or before X is up; starting it from the window manager limits it to that session. The user service manager needs `DISPLAY` (and `XAUTHORITY`) in its environment, which `/etc/X11/xinit/xinitrc.d/50-systemd-user.sh` sets up for `startx` sessions.
 ### Upgrading from xautolock-inhibit
 The package replaces `xautolock-inhibit`. After upgrading, change the `systemctl --user start` line in your window manager's startup, then switch the running daemon:
 ```
 systemctl --user stop xautolock-inhibit
 systemctl --user start xidle-inhibit
 ```
 Requests held by the old daemon are taken over if the new one starts within `--restore-window`.
 ## Configuration
 The backend is set in `~/.config/xidle-inhibit/config` (`$XDG_CONFIG_HOME`):
 ```
 backend = xss-lock
 ```
 Values are `xautolock` and `xss-lock`. Without the file, xidle-inhibit uses whichever of the two is installed, and xautolock if both are. Restart the service after changing it.
 ## Usage
 ```
-xautolock-inhibit [-i REASON] [--count-all] [-d SECONDS]
+xidle-inhibit [-i REASON] [--count-all] [-d SECONDS] [--restore-window SECONDS] [--cleanup]
 ```
 - `-i`, `--ignore-reason REASON`: request reason that doesn't block locking. Can be repeated; replaces the default (`Playing audio`).
 - `--count-all`: every request blocks locking; no reasons are ignored.
- `-d`, `--release-delay SECONDS`: wait this long after the last release before re-enabling xautolock (default 5).
+- `-d`, `--release-delay SECONDS`: wait this long after the last release before unblocking locking (default 5).
 - `--restore-window SECONDS`: take over requests from a previous daemon that stopped at most this long ago (default 30; 0 disables).
 - `--cleanup`: run `xautolock -enable` if xautolock is the backend, then exit. Used by the unit's `ExecStopPost`.
 To change the options used by the service:
 ```
-systemctl --user edit xautolock-inhibit.service
+systemctl --user edit xidle-inhibit.service
 ```
 ```ini
 [Service]
 ExecStart=
-ExecStart=/usr/bin/xautolock-inhibit --count-all
+ExecStart=/usr/bin/xidle-inhibit --count-all
 ```
-Every request, release and xautolock call is logged to the journal:
+Every request, release and locker command is logged to the journal:
 ```
-journalctl --user -u xautolock-inhibit
+journalctl --user -u xidle-inhibit
 ```
 ## App notes
@@ -84,7 +121,8 @@ journalctl --user -u xautolock-inhibit
 ## Limitations
- Restarting the daemon loses the requests it holds; apps don't send them again. Avoid restarting it while a video or game is running.
+- A release sent while the daemon is down is lost: if the daemon is back within `--restore-window`, that request stays active until its app exits. After a longer stop, all held requests are dropped and apps don't send them again.
 - With xss-lock, requests block only the idle timeout: suspending, or `loginctl lock-session` from elsewhere, still locks.
 - `SimulateUserActivity` is accepted but does nothing. Calls are logged once when a client starts sending them and once, with a count, after 5 minutes without any.
 - `GetActive` always returns `false`.
@@ -0,0 +1,10 @@
 [tool.ruff]
 line-length = 120
 extend-include = ["xidle-inhibit"]
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP"]
 [tool.mypy]
 files = ["xidle-inhibit"]
 strict = true
@@ -1,351 +0,0 @@
 #!/usr/bin/env python3
 """Own org.freedesktop.ScreenSaver and turn inhibit requests into xautolock -disable/-enable.
 While an inhibit is active, X screen blanking is also paused (like mpv does).
 """
 import argparse
 import ctypes
 import itertools
 import signal
 import subprocess
 import sys
 import time
 from dataclasses import dataclass
 from datetime import timedelta
 from gi.repository import Gio, GLib
 try:
    from gi.repository import GLibUnix  # GLib >= 2.80
    signal_add = GLibUnix.signal_add
 except ImportError:
    signal_add = GLib.unix_signal_add
 BUS_NAME = "org.freedesktop.ScreenSaver"
 OBJECT_PATHS = ("/org/freedesktop/ScreenSaver", "/ScreenSaver")  # Vivaldi uses the first, Zen the second
 EXIT_NAME_TAKEN = 2
 ACTIVITY_QUIET = 300  # seconds without SimulateUserActivity that end a logged burst
 INTROSPECTION = """
 <node>
  <interface name="org.freedesktop.ScreenSaver">
    <method name="Inhibit">
      <arg name="application_name" type="s" direction="in"/>
      <arg name="reason_for_inhibit" type="s" direction="in"/>
      <arg name="cookie" type="u" direction="out"/>
    </method>
    <method name="UnInhibit">
      <arg name="cookie" type="u" direction="in"/>
    </method>
    <method name="SimulateUserActivity"/>
    <method name="Lock"/>
    <method name="GetActive">
      <arg type="b" direction="out"/>
    </method>
    <method name="SetActive">
      <arg type="b" direction="in"/>
      <arg type="b" direction="out"/>
    </method>
    <method name="GetActiveTime">
      <arg type="u" direction="out"/>
    </method>
    <method name="GetSessionIdleTime">
      <arg type="u" direction="out"/>
    </method>
  </interface>
 </node>
 """
 def log(msg):
    print(msg, flush=True)
 def xautolock(arg):
    try:
        subprocess.run(["xautolock", arg], check=True, timeout=10)
        log(f"xautolock {arg}")
    except (OSError, subprocess.SubprocessError) as e:
        log(f"xautolock {arg} failed: {e}")
 class XBlanking:
    """Pause X screen blanking with XScreenSaverSuspend (MIT-SCREEN-SAVER extension).
    Unlike `xset s off -dpms` this changes no global setting: the X server ends the
    pause by itself when this client releases it or its connection closes (exit, crash).
    """
    def __init__(self):
        self.dpy = None
        try:
            self.x11 = ctypes.CDLL("libX11.so.6")
            self.xss = ctypes.CDLL("libXss.so.1")
        except OSError as e:
            log(f"Cannot load X11 libraries ({e}); X blanking will not be paused")
            return
        self.x11.XOpenDisplay.argtypes = [ctypes.c_char_p]
        self.x11.XOpenDisplay.restype = ctypes.c_void_p
        self.x11.XFlush.argtypes = [ctypes.c_void_p]
        self.xss.XScreenSaverQueryExtension.argtypes = [
            ctypes.c_void_p, ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_int)]
        self.xss.XScreenSaverSuspend.argtypes = [ctypes.c_void_p, ctypes.c_int]
        dpy = self.x11.XOpenDisplay(None)
        if not dpy:
            log("Cannot open the X display; X blanking will not be paused")
            return
        event_base, error_base = ctypes.c_int(), ctypes.c_int()
        if not self.xss.XScreenSaverQueryExtension(dpy, ctypes.byref(event_base), ctypes.byref(error_base)):
            log("X server lacks the MIT-SCREEN-SAVER extension; X blanking will not be paused")
            return
        self.dpy = dpy
    def suspend(self, on):
        if self.dpy:
            self.xss.XScreenSaverSuspend(self.dpy, int(on))
            self.x11.XFlush(self.dpy)
            log(f"X blanking {'paused' if on else 'resumed'}")
@dataclass
 class ActivityBurst:
    first: float
    last: float
    calls: int = 0
    timer: int = 0
 class Inhibitor:
    def __init__(self, ignored_reasons, release_delay, blanking):
        self.ignored_reasons = ignored_reasons
        self.blanking = blanking
        self.release_delay = release_delay
        self.cookies = {}  # cookie -> (sender, application_name, reason, counts)
        self.next_cookie = itertools.count(1)
        self.proc_names = {}  # sender -> "comm[pid]", for logging only
        self.activity: dict[str, ActivityBurst] = {}  # sender -> SimulateUserActivity burst
        self.disabled = False
        self.release_timer = 0
        self.conn = None
    # --- lock state -------------------------------------------------------
    def active_count(self):
        return sum(1 for *_, counts in self.cookies.values() if counts)
    def update(self):
        """Run xautolock only on 0->1 and 1->0 transitions; delay re-enabling."""
        active = self.active_count()
        if active and self.release_timer:
            GLib.source_remove(self.release_timer)
            self.release_timer = 0
        if active and not self.disabled:
            self.block()
        elif not active and self.disabled and not self.release_timer:
            # Browsers send quick Inhibit/UnInhibit bursts when a video starts.
            self.release_timer = GLib.timeout_add_seconds(self.release_delay, self.on_release_timeout)
    def on_release_timeout(self):
        self.release_timer = 0
        if not self.active_count() and self.disabled:
            self.unblock()
        return GLib.SOURCE_REMOVE
    def block(self):
        xautolock("-disable")
        self.blanking.suspend(True)
        self.disabled = True
    def unblock(self):
        xautolock("-enable")
        self.blanking.suspend(False)
        self.disabled = False
    def shutdown(self) -> None:
        for sender in list(self.activity):
            self.end_activity(sender)
        if self.release_timer:
            GLib.source_remove(self.release_timer)
            self.release_timer = 0
        if self.disabled:
            self.unblock()
    # --- D-Bus ------------------------------------------------------------
    def proc_name(self, sender):
        if sender not in self.proc_names:
            try:
                pid = self.conn.call_sync(
                    "org.freedesktop.DBus", "/org/freedesktop/DBus", "org.freedesktop.DBus",
                    "GetConnectionUnixProcessID", GLib.Variant("(s)", (sender,)),
                    GLib.VariantType("(u)"), Gio.DBusCallFlags.NONE, 1000, None,
                ).unpack()[0]
                with open(f"/proc/{pid}/comm") as f:
                    self.proc_names[sender] = f"{f.read().strip()}[{pid}]"
            except (GLib.Error, OSError):
                self.proc_names[sender] = "?"
        return f"{sender} {self.proc_names[sender]}"
    def inhibit(self, sender, app, reason):
        cookie = next(self.next_cookie)
        counts = reason not in self.ignored_reasons
        self.cookies[cookie] = (sender, app, reason, counts)
        note = "" if counts else " (reason ignored, does not block locking)"
        log(f"Inhibit {cookie}: '{app}' '{reason}' from {self.proc_name(sender)}{note}")
        self.update()
        return cookie
    def uninhibit(self, sender, cookie):
        entry = self.cookies.get(cookie)
        if entry is None or entry[0] != sender:
            log(f"UnInhibit {cookie} from {self.proc_name(sender)}: unknown cookie, ignored")
            return
        del self.cookies[cookie]
        _, app, reason, _ = entry
        log(f"UnInhibit {cookie}: '{app}' '{reason}'")
        self.update()
    def simulate_activity(self, sender: str) -> None:
        """Log a sender's calls once per burst: Steam sends thousands per hour."""
        now = time.monotonic()
        burst = self.activity.get(sender)
        if burst is None:
            log(f"SimulateUserActivity from {self.proc_name(sender)} (not implemented)")
            burst = self.activity[sender] = ActivityBurst(first=now, last=now)
        else:
            GLib.source_remove(burst.timer)
        burst.calls += 1
        burst.last = now
        burst.timer = GLib.timeout_add_seconds(ACTIVITY_QUIET, self.on_activity_quiet, sender)
    def on_activity_quiet(self, sender: str) -> bool:
        self.activity[sender].timer = 0
        self.end_activity(sender)
        return GLib.SOURCE_REMOVE
    def end_activity(self, sender: str) -> None:
        burst = self.activity.pop(sender, None)
        if burst is None:
            return
        if burst.timer:
            GLib.source_remove(burst.timer)
        if burst.calls == 1:
            return
        span = timedelta(seconds=round(burst.last - burst.first))
        log(f"SimulateUserActivity from {self.proc_name(sender)}: {burst.calls} calls over {span}")
    def release_sender(self, sender: str) -> None:
        gone = [c for c, (s, *_) in self.cookies.items() if s == sender]
        for c in gone:
            _, app, reason, _ = self.cookies.pop(c)
            log(f"Released {c}: '{app}' '{reason}' ({sender} left the bus)")
        self.end_activity(sender)
        self.proc_names.pop(sender, None)
        if gone:
            self.update()
    def on_method_call(self, conn, sender, path, iface, method, params, invocation):
        if method == "Inhibit":
            app, reason = params.unpack()
            invocation.return_value(GLib.Variant("(u)", (self.inhibit(sender, app, reason),)))
        elif method == "UnInhibit":
            self.uninhibit(sender, params.unpack()[0])
            invocation.return_value(None)
        elif method == "SimulateUserActivity":
            self.simulate_activity(sender)
            invocation.return_value(None)
        elif method == "Lock":
            log(f"Lock from {self.proc_name(sender)}")
            xautolock("-locknow")
            invocation.return_value(None)
        elif method in ("GetActive", "SetActive"):
            invocation.return_value(GLib.Variant("(b)", (False,)))
        elif method in ("GetActiveTime", "GetSessionIdleTime"):
            invocation.return_value(GLib.Variant("(u)", (0,)))
    def on_name_owner_changed(self, conn, sender, path, iface, signal_name, params):
        name, _old, new = params.unpack()
        if not new and name.startswith(":"):
            self.release_sender(name)
    def on_bus_acquired(self, conn, name):
        self.conn = conn
        iface = Gio.DBusNodeInfo.new_for_xml(INTROSPECTION).interfaces[0]
        for path in OBJECT_PATHS:
            conn.register_object(path, iface, self.on_method_call, None, None)
        conn.signal_subscribe(
            "org.freedesktop.DBus", "org.freedesktop.DBus", "NameOwnerChanged",
            "/org/freedesktop/DBus", None, Gio.DBusSignalFlags.NONE, self.on_name_owner_changed,
        )
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "-i", "--ignore-reason", action="append", metavar="REASON",
        help="inhibit reason that does not block locking (repeatable; default: 'Playing audio')",
    )
    parser.add_argument(
        "--count-all", action="store_true",
        help="let every inhibit block locking, ignoring no reasons",
    )
    parser.add_argument(
        "-d", "--release-delay", type=int, default=5, metavar="SECONDS",
        help="wait this long after the last release before re-enabling xautolock (default: 5)",
    )
    args = parser.parse_args()
    if args.count_all:
        ignored = set()
    else:
        ignored = set(args.ignore_reason or ["Playing audio"])
    inhibitor = Inhibitor(ignored, max(args.release_delay, 0), XBlanking())
    loop = GLib.MainLoop()
    exit_code = 0
    acquired = False
    def on_name_acquired(conn, name):
        nonlocal acquired
        acquired = True
        log(f"Owning {name}; ignored reasons: {sorted(ignored) or 'none'}")
        # Start from a known state, in case a previous instance died while disabled.
        # Only after owning the name, so a second instance can't undo an active inhibit.
        xautolock("-enable")
    def on_name_lost(conn, name):
        nonlocal exit_code
        if conn is None:
            log("Could not connect to the session bus")
            exit_code = 1
        elif acquired:
            log(f"Lost {name} (bus connection closed?)")
            exit_code = 1
        else:
            log(f"{name} is owned by another process (a desktop environment?); exiting")
            exit_code = EXIT_NAME_TAKEN
        loop.quit()
    def on_signal():
        log("Signal received, exiting")
        loop.quit()
        return GLib.SOURCE_REMOVE
    for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
        signal_add(GLib.PRIORITY_HIGH, sig, on_signal)
    owner_id = Gio.bus_own_name(
        Gio.BusType.SESSION, BUS_NAME, Gio.BusNameOwnerFlags.DO_NOT_QUEUE,
        inhibitor.on_bus_acquired, on_name_acquired, on_name_lost,
    )
    try:
        loop.run()
    finally:
        inhibitor.shutdown()
        Gio.bus_unown_name(owner_id)
    sys.exit(exit_code)
 if __name__ == "__main__":
    main()
@@ -1,10 +0,0 @@
 [Unit]
 Description=Turn org.freedesktop.ScreenSaver inhibit requests into xautolock control
 [Service]
 Type=dbus
 BusName=org.freedesktop.ScreenSaver
 ExecStart=/usr/bin/xautolock-inhibit
 ExecStopPost=-/usr/bin/xautolock -enable
 Restart=on-failure
 RestartPreventExitStatus=2
@@ -0,0 +1,551 @@
 #!/usr/bin/env python3
 """Own org.freedesktop.ScreenSaver and block screen locking by xautolock or xss-lock while inhibits are held.
 While an inhibit is active, X screen blanking is paused (like mpv does), which also keeps xss-lock from
 locking; with xautolock, it is also switched off with xautolock -disable.
 """
 import argparse
 import ctypes
 import json
 import os
 import shutil
 import signal
 import subprocess
 import sys
 import time
 from dataclasses import dataclass
 from datetime import timedelta
 from typing import Any
 from gi.repository import Gio, GLib
 try:
    from gi.repository import GLibUnix  # GLib >= 2.80
    signal_add = GLibUnix.signal_add
 except ImportError:
    signal_add = GLib.unix_signal_add
 BUS_NAME = "org.freedesktop.ScreenSaver"
 OBJECT_PATHS = ("/org/freedesktop/ScreenSaver", "/ScreenSaver")  # Vivaldi uses the first, Zen the second
 EXIT_NAME_TAKEN = 2
 ACTIVITY_QUIET = 300  # seconds without SimulateUserActivity that end a logged burst
 STATE_FILE = "xidle-inhibit.json"  # in $XDG_RUNTIME_DIR
 OLD_STATE_FILE = "xautolock-inhibit.json"  # before the rename (0.2); read once when upgrading
 STATE_HEARTBEAT = 10  # seconds between state file touches while inhibits are held
 CONFIG_FILE = "xidle-inhibit/config"  # in $XDG_CONFIG_HOME
 BACKENDS = ("xautolock", "xss-lock")
 Cookie = tuple[str, str, str, bool]  # sender, application_name, reason, counts
 INTROSPECTION = """
 <node>
  <interface name="org.freedesktop.ScreenSaver">
    <method name="Inhibit">
      <arg name="application_name" type="s" direction="in"/>
      <arg name="reason_for_inhibit" type="s" direction="in"/>
      <arg name="cookie" type="u" direction="out"/>
    </method>
    <method name="UnInhibit">
      <arg name="cookie" type="u" direction="in"/>
    </method>
    <method name="SimulateUserActivity"/>
    <method name="Lock"/>
    <method name="GetActive">
      <arg type="b" direction="out"/>
    </method>
    <method name="SetActive">
      <arg type="b" direction="in"/>
      <arg type="b" direction="out"/>
    </method>
    <method name="GetActiveTime">
      <arg type="u" direction="out"/>
    </method>
    <method name="GetSessionIdleTime">
      <arg type="u" direction="out"/>
    </method>
  </interface>
 </node>
 """
 def log(msg: str) -> None:
    print(msg, flush=True)
 def run(*cmd: str) -> None:
    try:
        subprocess.run(cmd, check=True, timeout=10)
        log(" ".join(cmd))
    except (OSError, subprocess.SubprocessError) as e:
        log(f"{' '.join(cmd)} failed: {e}")
 def xautolock(arg: str) -> None:
    run("xautolock", arg)
 def read_backend() -> str:
    """Return the backend set in the config file, else the installed locker (xautolock if both are)."""
    config_home = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
    path = os.path.join(config_home, CONFIG_FILE)
    try:
        with open(path) as f:
            for line in f:
                key, sep, value = line.partition("=")
                if not sep or key.strip() != "backend":
                    continue
                value = value.strip().strip("\"'")
                if value in BACKENDS:
                    return value
                log(f"{path}: unknown backend '{value}' (expected {' or '.join(BACKENDS)}); detecting")
    except FileNotFoundError:
        pass
    except OSError as e:
        log(f"Cannot read {path}: {e}; detecting the backend")
    if not shutil.which("xautolock") and shutil.which("xss-lock"):
        return "xss-lock"
    return "xautolock"
 class XBlanking:
    """Pause X screen blanking with XScreenSaverSuspend (MIT-SCREEN-SAVER extension).
    Unlike `xset s off -dpms` this changes no global setting: the X server ends the
    pause by itself when this client releases it or its connection closes (exit, crash).
    """
    def __init__(self) -> None:
        self.dpy: int | None = None
        try:
            self.x11 = ctypes.CDLL("libX11.so.6")
            self.xss = ctypes.CDLL("libXss.so.1")
        except OSError as e:
            log(f"Cannot load X11 libraries ({e}); X blanking will not be paused")
            return
        self.x11.XOpenDisplay.argtypes = [ctypes.c_char_p]
        self.x11.XOpenDisplay.restype = ctypes.c_void_p
        self.x11.XFlush.argtypes = [ctypes.c_void_p]
        self.xss.XScreenSaverQueryExtension.argtypes = [
            ctypes.c_void_p, ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_int)]
        self.xss.XScreenSaverSuspend.argtypes = [ctypes.c_void_p, ctypes.c_int]
        dpy = self.x11.XOpenDisplay(None)
        if not dpy:
            log("Cannot open the X display; X blanking will not be paused")
            return
        event_base, error_base = ctypes.c_int(), ctypes.c_int()
        if not self.xss.XScreenSaverQueryExtension(dpy, ctypes.byref(event_base), ctypes.byref(error_base)):
            log("X server lacks the MIT-SCREEN-SAVER extension; X blanking will not be paused")
            return
        self.dpy = dpy
    def suspend(self, on: bool) -> None:
        if self.dpy:
            self.xss.XScreenSaverSuspend(self.dpy, int(on))
            self.x11.XFlush(self.dpy)
            log(f"X blanking {'paused' if on else 'resumed'}")
@dataclass
 class ActivityBurst:
    first: float
    last: float
    calls: int = 0
    timer: int = 0
 class Inhibitor:
    def __init__(
        self, backend: str, ignored_reasons: set[str], release_delay: int, blanking: XBlanking,
        state_path: str | None, restore_window: int,
    ) -> None:
        self.xautolock = backend == "xautolock"  # else xss-lock: pausing X blanking is enough
        self.ignored_reasons = ignored_reasons
        self.blanking = blanking
        self.release_delay = release_delay
        self.state_path = state_path
        self.restore_window = restore_window
        self.state_ready = False  # set once this instance owns the name and may write the state file
        self.heartbeat_timer = 0
        self.cookies: dict[int, Cookie] = {}
        self.last_cookie = 0
        self.proc_names: dict[str, str] = {}  # sender -> "comm[pid]", for logging only
        self.activity: dict[str, ActivityBurst] = {}  # sender -> SimulateUserActivity burst
        self.disabled = False
        self.release_timer = 0
        self.conn: Gio.DBusConnection | None = None
    # --- lock state -------------------------------------------------------
    def active_count(self) -> int:
        return sum(1 for *_, counts in self.cookies.values() if counts)
    def update(self) -> None:
        """Block or unblock only on 0->1 and 1->0 transitions; delay unblocking."""
        active = self.active_count()
        if active and self.release_timer:
            GLib.source_remove(self.release_timer)
            self.release_timer = 0
        if active and not self.disabled:
            self.block()
        elif not active and self.disabled and not self.release_timer:
            # Browsers send quick Inhibit/UnInhibit bursts when a video starts.
            self.release_timer = GLib.timeout_add_seconds(self.release_delay, self.on_release_timeout)
    def on_release_timeout(self) -> bool:
        self.release_timer = 0
        if not self.active_count() and self.disabled:
            self.unblock()
        return GLib.SOURCE_REMOVE
    def block(self) -> None:
        if self.xautolock:
            xautolock("-disable")
        self.blanking.suspend(True)
        self.disabled = True
    def unblock(self) -> None:
        if self.xautolock:
            xautolock("-enable")
        self.blanking.suspend(False)
        self.disabled = False
    def shutdown(self) -> None:
        for sender in list(self.activity):
            self.end_activity(sender)
        if self.release_timer:
            GLib.source_remove(self.release_timer)
            self.release_timer = 0
        self.save(stopped=True)
        if self.disabled:
            self.unblock()
    # --- state file -------------------------------------------------------
    def start(self) -> None:
        """Take over inhibits saved by a previous instance, then set the locker to match."""
        self.restore()
        self.state_ready = True
        self.save()
        if self.state_path:
            old = os.path.join(os.path.dirname(self.state_path), OLD_STATE_FILE)
            try:
                os.remove(old)
            except FileNotFoundError:
                pass
            except OSError as e:
                log(f"Cannot remove old state file {old}: {e}")
        if self.active_count():
            self.block()
        elif self.xautolock:
            # Start from a known state, in case a previous instance died while disabled.
            xautolock("-enable")
    def restore(self) -> None:
        if not self.state_path:
            log("XDG_RUNTIME_DIR is not set; inhibits will not survive a restart")
            return
        assert self.conn is not None
        path = self.state_path
        old = os.path.join(os.path.dirname(path), OLD_STATE_FILE)
        if not os.path.exists(path) and os.path.exists(old):
            path = old
        try:
            with open(path) as f:
                state = json.load(f)
            age = time.time() - (state["stopped_at"] or os.stat(path).st_mtime)
            bus_id = state["bus_id"]
            last_cookie = int(state["last_cookie"])
            saved = [(int(c), s, a, r) for c, s, a, r in state["cookies"]]
        except FileNotFoundError:
            return
        except (OSError, ValueError, KeyError, TypeError) as e:
            log(f"Ignoring unreadable state file {path}: {e}")
            return
        if path == old:
            log(f"Reading inhibits from {old} (xautolock-inhibit)")
        if bus_id != self.conn.get_guid():
            # Unique names like :1.42 are reused by a new bus, so they would mean other clients.
            if saved:
                log(f"Not restoring {len(saved)} inhibit(s): saved on another session bus")
            return
        # Keep numbering after old cookies, so a late UnInhibit can't hit a new one.
        self.last_cookie = last_cookie
        if not saved:
            return
        if age > self.restore_window:
            # An UnInhibit sent while no instance ran is lost; don't trust an old file.
            log(f"Not restoring {len(saved)} inhibit(s): saved {age:.0f}s ago, "
                f"over the {self.restore_window}s window")
            return
        for cookie, sender, app, reason in saved:
            if not self.has_owner(sender):
                log(f"Not restoring {cookie}: '{app}' '{reason}' ({sender} left the bus)")
                continue
            counts = reason not in self.ignored_reasons
            self.cookies[cookie] = (sender, app, reason, counts)
            note = "" if counts else " (reason ignored, does not block locking)"
            log(f"Restored {cookie}: '{app}' '{reason}' from {self.proc_name(sender)}{note}")
    def save(self, stopped: bool = False) -> None:
        """Write the held inhibits atomically; while any are held, touch the file regularly.
        The touches keep the mtime recent, so after a crash the next instance can tell how
        long ago it happened. A clean stop records the time in `stopped_at` instead.
        """
        if not self.state_ready or not self.state_path:
            return
        assert self.conn is not None
        state = {
            "bus_id": self.conn.get_guid(),
            "last_cookie": self.last_cookie,
            "stopped_at": time.time() if stopped else None,
            "cookies": [[c, s, a, r] for c, (s, a, r, _) in self.cookies.items()],
        }
        tmp = f"{self.state_path}.tmp"
        try:
            with open(tmp, "w") as f:
                json.dump(state, f)
            os.replace(tmp, self.state_path)
        except OSError as e:
            log(f"Cannot write state file {self.state_path}: {e}")
        if self.cookies and not stopped:
            if not self.heartbeat_timer:
                self.heartbeat_timer = GLib.timeout_add_seconds(STATE_HEARTBEAT, self.on_heartbeat)
        elif self.heartbeat_timer:
            GLib.source_remove(self.heartbeat_timer)
            self.heartbeat_timer = 0
    def on_heartbeat(self) -> bool:
        assert self.state_path is not None
        try:
            os.utime(self.state_path)
        except OSError as e:
            log(f"Cannot touch state file {self.state_path}: {e}")
        return GLib.SOURCE_CONTINUE
    # --- D-Bus ------------------------------------------------------------
    def bus_call(self, method: str, name: str, reply_type: str) -> Any:
        """Call an org.freedesktop.DBus method that takes a bus name; return its single result."""
        assert self.conn is not None  # set in on_bus_acquired, before any method call
        return self.conn.call_sync(
            "org.freedesktop.DBus", "/org/freedesktop/DBus", "org.freedesktop.DBus",
            method, GLib.Variant("(s)", (name,)),
            GLib.VariantType(reply_type), Gio.DBusCallFlags.NONE, 1000, None,
        ).unpack()[0]
    def has_owner(self, name: str) -> bool:
        try:
            return bool(self.bus_call("NameHasOwner", name, "(b)"))
        except GLib.Error:
            return False
    def proc_name(self, sender: str) -> str:
        if sender not in self.proc_names:
            try:
                pid = self.bus_call("GetConnectionUnixProcessID", sender, "(u)")
                with open(f"/proc/{pid}/comm") as f:
                    self.proc_names[sender] = f"{f.read().strip()}[{pid}]"
            except (GLib.Error, OSError):
                self.proc_names[sender] = "?"
        return f"{sender} {self.proc_names[sender]}"
    def inhibit(self, sender: str, app: str, reason: str) -> int:
        self.last_cookie += 1
        cookie = self.last_cookie
        counts = reason not in self.ignored_reasons
        self.cookies[cookie] = (sender, app, reason, counts)
        note = "" if counts else " (reason ignored, does not block locking)"
        log(f"Inhibit {cookie}: '{app}' '{reason}' from {self.proc_name(sender)}{note}")
        self.save()
        self.update()
        return cookie
    def uninhibit(self, sender: str, cookie: int) -> None:
        entry = self.cookies.get(cookie)
        if entry is None or entry[0] != sender:
            log(f"UnInhibit {cookie} from {self.proc_name(sender)}: unknown cookie, ignored")
            return
        del self.cookies[cookie]
        _, app, reason, _ = entry
        log(f"UnInhibit {cookie}: '{app}' '{reason}'")
        self.save()
        self.update()
    def simulate_activity(self, sender: str) -> None:
        """Log a sender's calls once per burst: Steam sends thousands per hour."""
        now = time.monotonic()
        burst = self.activity.get(sender)
        if burst is None:
            log(f"SimulateUserActivity from {self.proc_name(sender)} (not implemented)")
            burst = self.activity[sender] = ActivityBurst(first=now, last=now)
        else:
            GLib.source_remove(burst.timer)
        burst.calls += 1
        burst.last = now
        burst.timer = GLib.timeout_add_seconds(ACTIVITY_QUIET, self.on_activity_quiet, sender)
    def on_activity_quiet(self, sender: str) -> bool:
        self.activity[sender].timer = 0
        self.end_activity(sender)
        return GLib.SOURCE_REMOVE
    def end_activity(self, sender: str) -> None:
        burst = self.activity.pop(sender, None)
        if burst is None:
            return
        if burst.timer:
            GLib.source_remove(burst.timer)
        if burst.calls == 1:
            return
        span = timedelta(seconds=round(burst.last - burst.first))
        log(f"SimulateUserActivity from {self.proc_name(sender)}: {burst.calls} calls over {span}")
    def release_sender(self, sender: str) -> None:
        gone = [c for c, (s, *_) in self.cookies.items() if s == sender]
        for c in gone:
            _, app, reason, _ = self.cookies.pop(c)
            log(f"Released {c}: '{app}' '{reason}' ({sender} left the bus)")
        self.end_activity(sender)
        self.proc_names.pop(sender, None)
        if gone:
            self.save()
            self.update()
    def on_method_call(
        self, conn: Gio.DBusConnection, sender: str, path: str, iface: str, method: str,
        params: GLib.Variant, invocation: Gio.DBusMethodInvocation,
    ) -> None:
        if method == "Inhibit":
            app, reason = params.unpack()
            invocation.return_value(GLib.Variant("(u)", (self.inhibit(sender, app, reason),)))
        elif method == "UnInhibit":
            self.uninhibit(sender, params.unpack()[0])
            invocation.return_value(None)
        elif method == "SimulateUserActivity":
            self.simulate_activity(sender)
            invocation.return_value(None)
        elif method == "Lock":
            log(f"Lock from {self.proc_name(sender)}")
            if self.xautolock:
                xautolock("-locknow")
            else:
                run("loginctl", "lock-session")
            invocation.return_value(None)
        elif method in ("GetActive", "SetActive"):
            invocation.return_value(GLib.Variant("(b)", (False,)))
        elif method in ("GetActiveTime", "GetSessionIdleTime"):
            invocation.return_value(GLib.Variant("(u)", (0,)))
    def on_name_owner_changed(
        self, conn: Gio.DBusConnection, sender: str | None, path: str, iface: str, signal_name: str,
        params: GLib.Variant,
    ) -> None:
        name, _old, new = params.unpack()
        if not new and name.startswith(":"):
            self.release_sender(name)
    def on_bus_acquired(self, conn: Gio.DBusConnection, name: str) -> None:
        self.conn = conn
        iface = Gio.DBusNodeInfo.new_for_xml(INTROSPECTION).interfaces[0]
        for path in OBJECT_PATHS:
            conn.register_object(path, iface, self.on_method_call, None, None)
        conn.signal_subscribe(
            "org.freedesktop.DBus", "org.freedesktop.DBus", "NameOwnerChanged",
            "/org/freedesktop/DBus", None, Gio.DBusSignalFlags.NONE, self.on_name_owner_changed,
        )
 def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "-i", "--ignore-reason", action="append", metavar="REASON",
        help="inhibit reason that does not block locking (repeatable; default: 'Playing audio')",
    )
    parser.add_argument(
        "--count-all", action="store_true",
        help="let every inhibit block locking, ignoring no reasons",
    )
    parser.add_argument(
        "-d", "--release-delay", type=int, default=5, metavar="SECONDS",
        help="wait this long after the last release before unblocking locking (default: 5)",
    )
    parser.add_argument(
        "--restore-window", type=int, default=30, metavar="SECONDS",
        help="take over inhibits from a previous instance that stopped at most this long ago "
             "(default: 30; 0 disables)",
    )
    parser.add_argument(
        "--cleanup", action="store_true",
        help="re-enable xautolock if it is the backend, then exit (for the unit's ExecStopPost)",
    )
    args = parser.parse_args()
    backend = read_backend()
    if args.cleanup:
        if backend == "xautolock":
            xautolock("-enable")
        return
    ignored: set[str]
    if args.count_all:
        ignored = set()
    else:
        ignored = set(args.ignore_reason or ["Playing audio"])
    runtime_dir = os.environ.get("XDG_RUNTIME_DIR")
    state_path = os.path.join(runtime_dir, STATE_FILE) if runtime_dir else None
    blanking = XBlanking()
    if backend == "xss-lock" and not blanking.dpy:
        log("Warning: with xss-lock, inhibits block locking only through X blanking, which is unavailable")
    inhibitor = Inhibitor(
        backend, ignored, max(args.release_delay, 0), blanking, state_path, max(args.restore_window, 0),
    )
    loop = GLib.MainLoop()
    exit_code = 0
    acquired = False
    def on_name_acquired(conn: Gio.DBusConnection, name: str) -> None:
        nonlocal acquired
        acquired = True
        log(f"Owning {name}; backend: {backend}; ignored reasons: {sorted(ignored) or 'none'}")
        # Only after owning the name, so a second instance can't undo an active inhibit
        # or overwrite the state file.
        inhibitor.start()
    def on_name_lost(conn: Gio.DBusConnection | None, name: str) -> None:
        nonlocal exit_code
        if conn is None:
            log("Could not connect to the session bus")
            exit_code = 1
        elif acquired:
            log(f"Lost {name} (bus connection closed?)")
            exit_code = 1
        else:
            log(f"{name} is owned by another process (a desktop environment?); exiting")
            exit_code = EXIT_NAME_TAKEN
        loop.quit()
    def on_signal() -> bool:
        log("Signal received, exiting")
        loop.quit()
        return GLib.SOURCE_REMOVE
    for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
        signal_add(GLib.PRIORITY_HIGH, sig, on_signal)
    owner_id = Gio.bus_own_name(
        Gio.BusType.SESSION, BUS_NAME, Gio.BusNameOwnerFlags.DO_NOT_QUEUE,
        inhibitor.on_bus_acquired, on_name_acquired, on_name_lost,
    )
    try:
        loop.run()
    finally:
        inhibitor.shutdown()
        Gio.bus_unown_name(owner_id)
    sys.exit(exit_code)
 if __name__ == "__main__":
    main()
@@ -0,0 +1,10 @@
 [Unit]
 Description=Block screen locking (xautolock or xss-lock) on org.freedesktop.ScreenSaver inhibit requests
 [Service]
 Type=dbus
 BusName=org.freedesktop.ScreenSaver
 ExecStart=/usr/bin/xidle-inhibit
 ExecStopPost=-/usr/bin/xidle-inhibit --cleanup
 Restart=on-failure
 RestartPreventExitStatus=2
Author	SHA1	Message	Date
Daniele Fucini	0fc1ab2f47	Add xss-lock backend and rename to xidle-inhibit The backend comes from ~/.config/xidle-inhibit/config, else the installed locker. With xss-lock, pausing X blanking alone blocks locking and Lock uses loginctl; the unit's ExecStopPost runs --cleanup. Inhibits from the old xautolock-inhibit state file are taken over once. Also fix mypy with pygobject-stubs 2.19.	2026-10-23 19:53:42 +02:00
Daniele Fucini	ef9c8b858b	Uniform installation instructions in README	2026-10-20 22:01:28 +02:00
Daniele Fucini	ddd1f6f40a	Update PKGBUILD	2026-10-17 16:50:04 +02:00
Daniele Fucini	265966ffe9	Keep inhibits across daemon restarts Save held inhibits to $XDG_RUNTIME_DIR/xautolock-inhibit.json and restore them on start if the previous instance stopped within --restore-window (default 30s) on the same bus and the senders are still connected. The file is touched every 10s while inhibits are held, so crashes are timed too.	2026-10-17 16:49:40 +02:00
Daniele Fucini	a36e700df6	Add type hints and ruff/mypy config Annotate all functions and check them with mypy --strict (needs python-pygobject-stubs). pyproject.toml holds only tool config since the PKGBUILD installs the script directly.	2026-10-16 17:21:34 +02:00
Daniele Fucini	13c1afd7b6	Update PKGBUILD	2026-10-15 23:39:11 +02:00