cli-watch-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
cli_watch_kit/paths.py ADDED
@@ -0,0 +1,114 @@
1
+ """Filesystem locations of one app: the base dir its watchers write their files under, and the daemon state dir.
2
+
3
+ Each location can be overridden by an environment variable named after the app's prefix (`<PREFIX>BASE_DIR`,
4
+ `<PREFIX>STATE_DIR`), which also keeps tests inside temp dirs.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import re
11
+ import stat
12
+ import sys
13
+ import tempfile
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+
17
+
18
+ def sanitize_part(value: str) -> str:
19
+ """Make one path component safe: no separators, no traversal, no characters Windows rejects."""
20
+ cleaned = re.sub(r"[^A-Za-z0-9._-]", "-", value).strip(".")
21
+ cleaned = cleaned.replace("..", "-")
22
+ return cleaned or "unknown"
23
+
24
+
25
+ def ensure_private_dir(path: Path) -> Path:
26
+ """Create `path` and make it readable by the user only.
27
+
28
+ A dir in a shared place such as `/tmp` may have been created by someone else first, or be a symlink to their dir;
29
+ such a dir is refused, because the daemon's socket and log, and the watchers' files, would then be theirs to read
30
+ or replace.
31
+ """
32
+ path.mkdir(parents=True, exist_ok=True)
33
+ if os.name != "nt":
34
+ # Ours, then made private: the mode a fresh dir gets from the umask is no reason to refuse it.
35
+ check_owned(path, directory=True, modes=False)
36
+ os.chmod(path, 0o700)
37
+ return path
38
+
39
+
40
+ def check_owned(path: Path, *, directory: bool = False, private: bool = False, modes: bool = True) -> None:
41
+ """Raise `PermissionError` unless `path` belongs to this user, is no symlink, and (with `modes`) nobody else may
42
+ write it, or with `private` read it either. Does nothing on Windows, where the profile dir protects the files."""
43
+ if os.name == "nt":
44
+ return
45
+ info = os.lstat(path)
46
+ if stat.S_ISLNK(info.st_mode) or (directory and not stat.S_ISDIR(info.st_mode)):
47
+ raise PermissionError(f"{path} is a symlink or not a {'dir' if directory else 'file'}; refusing to use it")
48
+ if info.st_uid != os.getuid():
49
+ raise PermissionError(f"{path} belongs to another user; refusing to use it")
50
+ if modes and info.st_mode & (0o077 if private else 0o022):
51
+ raise PermissionError(
52
+ f"{path} is open to other users (mode {stat.S_IMODE(info.st_mode):o}); refusing to use it"
53
+ )
54
+
55
+
56
+ def uid_suffix() -> str:
57
+ getuid = getattr(os, "getuid", None)
58
+ return str(getuid()) if getuid is not None else (os.environ.get("USERNAME") or "user")
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class AppPaths:
63
+ """Where an app named `name` keeps its files. `env_prefix` is the prefix of its override variables.
64
+ `files_dir_name` names the dir of the watchers' files (default: `name`); the daemon's state dir keeps `name`."""
65
+
66
+ name: str
67
+ env_prefix: str
68
+ files_dir_name: str = ""
69
+
70
+ @property
71
+ def files_name(self) -> str:
72
+ return self.files_dir_name or self.name
73
+
74
+ @property
75
+ def base_dir_env(self) -> str:
76
+ return f"{self.env_prefix}BASE_DIR"
77
+
78
+ @property
79
+ def state_dir_env(self) -> str:
80
+ return f"{self.env_prefix}STATE_DIR"
81
+
82
+ def base_dir(self, override: Path | None = None, scratchpad: Path | None = None) -> Path:
83
+ """The dir the watchers write their resource dirs under.
84
+
85
+ `override` wins, then `<PREFIX>BASE_DIR`. Under a Claude Code session with a scratchpad it is
86
+ `<scratchpad>/<files_dir_name>`, which Claude Code removes after a while. Otherwise
87
+ `<temp dir>/<files_dir_name>-<uid>`, private to the user, which the OS cleans.
88
+ """
89
+ if override is not None:
90
+ return override
91
+ env = os.environ.get(self.base_dir_env)
92
+ if env:
93
+ return Path(env)
94
+ if scratchpad is not None:
95
+ return scratchpad / self.files_name
96
+ return ensure_private_dir(Path(tempfile.gettempdir()) / f"{self.files_name}-{uid_suffix()}")
97
+
98
+ def state_dir(self) -> Path:
99
+ """The per-user dir holding the daemon's lock, socket (or port file) and log."""
100
+ override = os.environ.get(self.state_dir_env)
101
+ if override:
102
+ return Path(override)
103
+ if sys.platform == "win32":
104
+ base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
105
+ return base / self.name / "run"
106
+ if sys.platform == "darwin":
107
+ tmpdir = os.environ.get("TMPDIR")
108
+ if tmpdir:
109
+ return Path(tmpdir) / self.name
110
+ else:
111
+ runtime = os.environ.get("XDG_RUNTIME_DIR")
112
+ if runtime and Path(runtime).is_dir():
113
+ return Path(runtime) / self.name
114
+ return Path(tempfile.gettempdir()) / f"{self.name}-{uid_suffix()}"
cli_watch_kit/py.typed ADDED
File without changes
cli_watch_kit/sinks.py ADDED
@@ -0,0 +1,106 @@
1
+ """Where a watcher delivers its events, and where its own status lines go.
2
+
3
+ Status lines (the startup header, the end line, errors) go to stderr, so stdout carries only events. Claude Code puts
4
+ a background Bash task's stderr into the task output next to its stdout, so an agent reads both. Status lines start
5
+ with the app's prefix and never with `{`, so a reader of the merged output can still tell them from events.
6
+
7
+ :class:`EventSink` has the shape of cc-blackbox's event sinks, so its `MessageEventSink` fits without an adapter;
8
+ see :mod:`cli_watch_kit.claude`.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import sys
15
+ from collections.abc import Mapping, Sequence
16
+ from typing import Any, Protocol, TextIO, TypeVar
17
+
18
+ from cli_watch_kit.events import Event
19
+
20
+
21
+ class StreamEvent(Protocol):
22
+ @property
23
+ def kind(self) -> str: ...
24
+
25
+ @property
26
+ def seq(self) -> int: ...
27
+
28
+ def to_json(self) -> Mapping[str, Any]: ...
29
+
30
+
31
+ E_contra = TypeVar("E_contra", bound=StreamEvent, contravariant=True)
32
+
33
+
34
+ class EventSink(Protocol[E_contra]):
35
+ """Where a watcher delivers its events. The watcher calls :meth:`tick` when :meth:`seconds_until_flush` says so."""
36
+
37
+ name: str
38
+
39
+ def describe(self) -> str:
40
+ """One line for the startup header: the stream mode and its target."""
41
+ ...
42
+
43
+ def emit(self, events: Sequence[E_contra]) -> None: ...
44
+
45
+ def seconds_until_flush(self) -> float | None:
46
+ """When a buffered batch is due, so the watcher wakes up for it; `None` when nothing is buffered."""
47
+ ...
48
+
49
+ def tick(self) -> None:
50
+ """Deliver a buffered batch whose time has come."""
51
+ ...
52
+
53
+ def alive(self) -> bool:
54
+ """`False` once the target is gone, which ends the watch."""
55
+ ...
56
+
57
+ def close(self) -> None: ...
58
+
59
+
60
+ type Sink = EventSink[Event]
61
+
62
+
63
+ class StdoutSink:
64
+ """One compact JSON object per line, flushed after every batch."""
65
+
66
+ name = "stdout"
67
+
68
+ def __init__(self, stream: TextIO | None = None) -> None:
69
+ self._stream = stream
70
+
71
+ def describe(self) -> str:
72
+ return "stdout (one JSON event per line)"
73
+
74
+ def emit(self, events: Sequence[StreamEvent]) -> None:
75
+ stream = self._stream or sys.stdout
76
+ for event in events:
77
+ stream.write(json.dumps(event.to_json(), ensure_ascii=False, separators=(",", ":")) + "\n")
78
+ stream.flush()
79
+
80
+ def seconds_until_flush(self) -> float | None:
81
+ return None
82
+
83
+ def tick(self) -> None:
84
+ pass
85
+
86
+ def alive(self) -> bool:
87
+ return True
88
+
89
+ def close(self) -> None:
90
+ pass
91
+
92
+
93
+ class StatusOutput:
94
+ """Status lines with the app's prefix, on stderr unless a stream is given."""
95
+
96
+ def __init__(self, prefix: str, stream: TextIO | None = None) -> None:
97
+ self.prefix = prefix
98
+ self._stream = stream
99
+
100
+ @property
101
+ def stream(self) -> TextIO:
102
+ return self._stream if self._stream is not None else sys.stderr
103
+
104
+ def line(self, text: str) -> None:
105
+ self.stream.write(f"{self.prefix}{text}\n")
106
+ self.stream.flush()
@@ -0,0 +1,291 @@
1
+ """What a CLI implements to be watched: a :class:`Source` that polls targets and diffs them into events.
2
+
3
+ The engine owns the scheduling, the rate budget, the sharing between watchers and the event log. The source owns the
4
+ API: it fetches the current state of a batch of targets, diffs each against the previous snapshot with a pure
5
+ function, and returns one :class:`PollOutcome` per target. It never sleeps and never retries; the engine does both.
6
+
7
+ - A **target** is what a watcher asks for (`issue ABC-123`). Its `key` names it in events and logs.
8
+ - An **account** is whose rate limit a poll spends. Targets of different accounts never share a poll or a budget,
9
+ so two watchers with different API keys of the same user share one budget, and two users never share one.
10
+ - Targets with the same **batch key** that are due at about the same time go into one :meth:`Source.poll` call, split
11
+ so that no call costs more than :attr:`Source.batch_cost_cap`.
12
+ - **Params** are what a watcher sends along with its subscription, such as an API key. They reach the daemon over its
13
+ private socket and are given to the source per account, never logged or shown in the status.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import time
19
+ from abc import ABC, abstractmethod
20
+ from collections.abc import Awaitable, Callable, Hashable, Mapping, Sequence
21
+ from contextvars import ContextVar
22
+ from dataclasses import dataclass, field
23
+ from typing import TYPE_CHECKING, Any
24
+
25
+ from cli_watch_kit.budget import DEFAULT_DIMENSIONS, REQUESTS, Budget, DimensionSpec
26
+ from cli_watch_kit.daemon.cache import ByteBoundedCache
27
+ from cli_watch_kit.events import KindCatalog, RawEvent
28
+
29
+ if TYPE_CHECKING:
30
+ from cli_watch_kit.daemon.engine import Engine
31
+
32
+ Params = Mapping[str, Any]
33
+
34
+
35
+ class SourceError(Exception):
36
+ """A poll of a target failed. Raise a subclass from :meth:`Source.poll` for the whole batch, or put one in a
37
+ :class:`PollOutcome` for one target. The engine reports each kind once as `watch_degraded` and backs off."""
38
+
39
+ reason = "error"
40
+
41
+
42
+ class NotFound(SourceError):
43
+ """The target does not exist (any more). Before the first successful poll this ends the watch."""
44
+
45
+ reason = "not_found"
46
+
47
+
48
+ class Unauthorized(SourceError):
49
+ reason = "auth"
50
+
51
+
52
+ class RateLimited(SourceError):
53
+ """The API refused the request for its rate limit. Blocks the whole account for `retry_after` seconds or more."""
54
+
55
+ reason = "rate_limited"
56
+
57
+ def __init__(self, message: str, retry_after: float | None = None) -> None:
58
+ super().__init__(message)
59
+ self.retry_after = retry_after
60
+
61
+
62
+ class Transient(SourceError):
63
+ """A network error, a 5xx, an unexpected response: worth trying again later."""
64
+
65
+ reason = "error"
66
+
67
+
68
+ @dataclass(frozen=True)
69
+ class Target:
70
+ """A watched resource: its `kind` (a key of the catalog's `kinds_by_resource`), an `id` unique within the kind,
71
+ and whatever else the source needs to poll it, as JSON in `data`. Two targets are equal when their keys are."""
72
+
73
+ kind: str
74
+ id: str
75
+ data: Mapping[str, Any] = field(default_factory=dict, compare=False, hash=False)
76
+
77
+ @property
78
+ def key(self) -> str:
79
+ return f"{self.kind} {self.id}"
80
+
81
+ def to_wire(self) -> dict[str, Any]:
82
+ return {"kind": self.kind, "id": self.id, "data": dict(self.data)}
83
+
84
+ @classmethod
85
+ def from_wire(cls, value: Any) -> Target:
86
+ if not isinstance(value, Mapping):
87
+ raise ValueError("target must be an object")
88
+ kind, ident, data = value.get("kind"), value.get("id"), value.get("data") or {}
89
+ if not isinstance(kind, str) or not kind or not isinstance(ident, str) or not ident:
90
+ raise ValueError("target.kind and target.id must be non-empty strings")
91
+ if not isinstance(data, Mapping):
92
+ raise ValueError("target.data must be an object")
93
+ return cls(kind, ident, dict(data))
94
+
95
+
96
+ @dataclass(frozen=True)
97
+ class PollItem[S]:
98
+ """One target in a poll: the snapshot to diff against (`None` on the first poll without a baseline) and the event
99
+ kinds any subscriber wants, which a source may use to skip work nobody needs.
100
+
101
+ `state` is the resource's private scratch space for what is not part of the snapshot (an ETag, work held back
102
+ for a later poll, a stateful poller object). It is the same dict on every poll of the resource, starts empty
103
+ (also after a daemon restart), and goes away with the resource.
104
+ """
105
+
106
+ target: Target
107
+ snapshot: S | None
108
+ events: frozenset[str]
109
+ state: dict[str, Any] = field(default_factory=dict, compare=False)
110
+ options: tuple[Mapping[str, Any], ...] = ()
111
+ """The source options of every subscriber and parent that sent any, each once, for the source to merge (glab's
112
+ `--logs` modes, for example). Empty when nobody sent options."""
113
+
114
+ @property
115
+ def key(self) -> str:
116
+ return self.target.key
117
+
118
+
119
+ @dataclass(frozen=True)
120
+ class Wants:
121
+ """What a parent wants from a child target: event kinds, and source options like a subscriber's.
122
+
123
+ `baseline` is the child's snapshot as the parent's snapshot knows it, in the child's :meth:`Source.encode` form.
124
+ A new child starts from it, so after a daemon restart the child's first poll reports what changed in the gap
125
+ instead of being a silent baseline poll. It works only when the parent's snapshot embeds the child state that
126
+ the relayed events depend on; without it the changes of a child during a restart are not reported.
127
+ """
128
+
129
+ events: frozenset[str]
130
+ options: Mapping[str, Any] = field(default_factory=dict)
131
+ baseline: Any = None
132
+
133
+
134
+ @dataclass(frozen=True)
135
+ class PollOutcome[S]:
136
+ """What a poll found for one target.
137
+
138
+ - On success, `snapshot` is the new state and `events` what changed since the previous one. A poll without a
139
+ previous snapshot is the baseline and should report nothing.
140
+ - `ended` ends the watch with that reason (`completed`, `merged`, ...), `end_data` goes into `watch_ended`.
141
+ - `next_delay` overrides :meth:`Source.interval` for this target once.
142
+ - With `error`, the rest is ignored.
143
+ """
144
+
145
+ snapshot: S | None = None
146
+ events: Sequence[RawEvent] = ()
147
+ ended: str | None = None
148
+ end_data: Mapping[str, Any] = field(default_factory=dict)
149
+ next_delay: float | None = None
150
+ error: SourceError | None = None
151
+
152
+
153
+ @dataclass
154
+ class PollContext:
155
+ """What a poll gets from the engine besides its targets.
156
+
157
+ `budget` is the account's: call :meth:`Budget.observe` with the rate-limit readings of each response.
158
+
159
+ The engine charges the account :meth:`Source.cost` before the call. A source that knows what each response really
160
+ cost (an ETag 304 at a tenth of a request, a complexity header) calls :meth:`spend` with it, as often as it sends
161
+ requests; after the call the engine gives back the estimate of each dimension the source spent on, so the account
162
+ pays what was spent there and the estimate elsewhere. `cache` is
163
+ shared by the whole daemon; put the version of the value into its key, so a hit is never stale.
164
+ """
165
+
166
+ account: str
167
+ params: Params
168
+ budget: Budget
169
+ cache: ByteBoundedCache[Any]
170
+ clock: Callable[[], float] = time.time
171
+ estimate: Mapping[str, float] = field(default_factory=dict)
172
+ """What the engine charged before the call."""
173
+ spent: dict[str, float] = field(default_factory=dict)
174
+ """What :meth:`spend` charged so far."""
175
+
176
+ def spend(self, cost: Mapping[str, float]) -> None:
177
+ """Charge what a request really cost. The estimate of each dimension spent on is refunded after the poll."""
178
+ self.budget.charge(cost, self.clock())
179
+ for dim, amount in cost.items():
180
+ self.spent[dim] = self.spent.get(dim, 0.0) + amount
181
+
182
+ @staticmethod
183
+ def current() -> PollContext | None:
184
+ """The context of the poll the calling task runs in, or `None` outside a poll (in an extra op, say).
185
+
186
+ For an API client the source shares between the polls of an account, which can then charge each request to
187
+ the poll that sent it without the context being passed down to it. Concurrent polls each see their own."""
188
+ return _CURRENT_POLL.get()
189
+
190
+
191
+ _CURRENT_POLL: ContextVar[PollContext | None] = ContextVar("cli_watch_kit_current_poll", default=None)
192
+
193
+
194
+ @dataclass
195
+ class OpContext:
196
+ """What an extra op of the daemon gets: the engine and the params the request carried."""
197
+
198
+ engine: Engine
199
+ params: Params
200
+
201
+ async def account(self, target: Target) -> str:
202
+ return await self.engine.source.account(target, self.params)
203
+
204
+
205
+ OpHandler = Callable[[OpContext, dict[str, Any]], Awaitable[dict[str, Any]]]
206
+ """An extra daemon op: gets the request (without `op` and `params`) and returns the fields of the `ok` response."""
207
+
208
+
209
+ class Source[S](ABC):
210
+ """The base class of a CLI's source. `S` is the source's snapshot type, which never leaves the daemon as is:
211
+ :meth:`encode` turns it into JSON for the watchers and their baselines, :meth:`decode` reads it back."""
212
+
213
+ catalog: KindCatalog
214
+ dimensions: Mapping[str, DimensionSpec] = DEFAULT_DIMENSIONS
215
+ """The budget dimensions, with their rates before the API reports any."""
216
+ batch_cost_cap: Mapping[str, float] | None = None
217
+ """The most one poll call may cost per dimension. Batches above it are split; one target above it polls alone."""
218
+ coalesce_window: float = 5.0
219
+ """A target due within this many seconds joins a batch that polls now, so close schedules merge."""
220
+ baseline_wait: float | None = None
221
+ """How long the first poll of a new target with a batch key waits, so the targets that watchers subscribe to
222
+ within a few seconds of each other share one call. `None` waits the `coalesce_window`; 0 polls at once."""
223
+ max_inflight: int = 4
224
+ """Concurrent poll calls per account."""
225
+ ops: Mapping[str, OpHandler] = {}
226
+ """Extra daemon ops, by name. They must not shadow the built-in ones."""
227
+
228
+ async def account(self, target: Target, params: Params) -> str:
229
+ """Whose budget polls of `target` spend. Called on subscribe; raise :class:`Unauthorized` for bad params.
230
+
231
+ The params of the latest subscription of an account replace those of the earlier ones for every poll of the
232
+ account, so check them here, for example by resolving the user an API key belongs to: a subscription with a
233
+ wrong key that got through would break the account's other watchers. The default is one account for
234
+ everything."""
235
+ return ""
236
+
237
+ def batch_key(self, target: Target) -> Hashable | None:
238
+ """Targets with an equal key (within one account) may be polled in one call. `None` polls alone."""
239
+ return None
240
+
241
+ @abstractmethod
242
+ def interval(self, target: Target, snapshot: S | None) -> float:
243
+ """Base seconds until the next poll, before the engine stretches it under budget pressure."""
244
+
245
+ def cost(self, batch: Sequence[PollItem[S]]) -> Mapping[str, float]:
246
+ """The estimated cost of one poll call for `batch`, per dimension. Default: one request."""
247
+ return {REQUESTS: 1.0}
248
+
249
+ @abstractmethod
250
+ async def poll(self, batch: Sequence[PollItem[S]], ctx: PollContext) -> Mapping[str, PollOutcome[S]]:
251
+ """Poll every target of `batch` and return an outcome per target key. A target left out counts as a
252
+ transient error. Raise a :class:`SourceError` when the whole call failed."""
253
+
254
+ def diff(self, target: Target, previous: S, current: S, events: frozenset[str]) -> Sequence[RawEvent]:
255
+ """The events between two snapshots, limited to `events`: the same pure diff :meth:`poll` uses.
256
+
257
+ The engine calls it when a watcher resubscribes with a baseline (after a daemon restart, a drain or an
258
+ expired lease) to a resource that other watchers keep polling, so this watcher still learns what changed
259
+ in the gap. Default: no events, and the watcher only gets the new snapshot in `watch_started`."""
260
+ return ()
261
+
262
+ def summary(self, target: Target, snapshot: S | None) -> dict[str, Any]:
263
+ """A compact description of the snapshot, sent in `watch_started`."""
264
+ return {}
265
+
266
+ def encode(self, snapshot: S) -> Any:
267
+ """The snapshot as JSON. Default: the snapshot is already JSON.
268
+
269
+ Its hash decides when watchers get the snapshot again, so it must not change while the target does not:
270
+ keep fetch times, ETags and other volatile values in `PollItem.state` instead."""
271
+ return snapshot
272
+
273
+ def decode(self, target: Target, data: Any) -> S:
274
+ """A snapshot from :meth:`encode` (a baseline a watcher kept). Raise `ValueError` when it does not fit."""
275
+ return data # type: ignore[no-any-return]
276
+
277
+ def status(self) -> dict[str, Any]:
278
+ """What `daemon status` shows about the source, such as request counts per host. Never put params here."""
279
+ return {}
280
+
281
+ def check_options(self, target: Target, options: Mapping[str, Any]) -> Mapping[str, Any]:
282
+ """Validate the source options a watcher subscribes with, and return them normalized. Raise `ValueError`
283
+ with a message for the watcher when they cannot work. Default: any options are taken as they are."""
284
+ return dict(options)
285
+
286
+ def children(self, target: Target, snapshot: S, item: PollItem[S]) -> Mapping[Target, frozenset[str] | Wants]:
287
+ """Other targets whose events this one relays, each with the kinds (and options) it wants from them, such as
288
+ an MR that relays its head pipeline. `item` says what the subscribers of `target` want. A child is polled
289
+ as a target of its own, in the parent's account, and its events other than the lifecycle ones go into the
290
+ parent's log too."""
291
+ return {}
@@ -0,0 +1,67 @@
1
+ """What a watcher derives from time: the threshold events of the app, and the idle end of a watch.
2
+
3
+ Both come from the snapshots and events the watcher already receives, so they cost no request. The daemon never sees
4
+ them: they depend on what this watcher reported, which differs per watcher of the same resource.
5
+
6
+ An app adds its own threshold kinds (glab's `quiet` and `pipeline_stuck`, for example) as :class:`ClientTimer` objects
7
+ and names their options in the catalog's `thresholds`. :class:`IdleTimer` ends a watch when nothing was reported for
8
+ `--idle-after`; threshold events do not count as activity, so a quiet resource stays idle after `quiet`.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from collections.abc import Iterable
14
+ from typing import Any, Protocol
15
+
16
+ from cli_watch_kit.durations import format_duration
17
+ from cli_watch_kit.events import Event
18
+
19
+
20
+ class ClientTimer(Protocol):
21
+ """An app's threshold event source inside the watcher. The watcher passes a monotonic `now` everywhere."""
22
+
23
+ def snapshot(self, data: Any, now: float) -> None:
24
+ """Take in a snapshot the daemon sent, as the source encoded it."""
25
+ ...
26
+
27
+ def reported(self, events: Iterable[Event], now: float) -> None:
28
+ """The events the watcher just reported, threshold events included."""
29
+ ...
30
+
31
+ def due(self, now: float) -> list[tuple[str, dict[str, Any]]]:
32
+ """The threshold events due now, as (kind, data). Each should be returned once."""
33
+ ...
34
+
35
+ def seconds_until_next(self, now: float) -> float | None:
36
+ """How long until the next threshold can fire, so the watcher does not sleep past it."""
37
+ ...
38
+
39
+ def describe(self) -> str | None:
40
+ """A part of the header's `thresholds:` line, such as `quiet after 2m`, or `None`."""
41
+ ...
42
+
43
+
44
+ class IdleTimer:
45
+ """Ends a watch when nothing but threshold events was reported for `idle_after` seconds."""
46
+
47
+ def __init__(self, idle_after: float | None, threshold_kinds: Iterable[str], now: float) -> None:
48
+ self.idle_after = idle_after
49
+ self.threshold_kinds = frozenset(threshold_kinds)
50
+ self._last_activity = now
51
+
52
+ def reported(self, events: Iterable[Event], now: float) -> None:
53
+ if any(e.kind not in self.threshold_kinds for e in events):
54
+ self._last_activity = now
55
+
56
+ def idle(self, now: float) -> bool:
57
+ return self.idle_after is not None and now - self._last_activity >= self.idle_after
58
+
59
+ def seconds_until_next(self, now: float) -> float | None:
60
+ if self.idle_after is None:
61
+ return None
62
+ return max(0.0, self._last_activity + self.idle_after - now)
63
+
64
+ def describe(self) -> str | None:
65
+ if self.idle_after is None:
66
+ return None
67
+ return f"after {format_duration(self.idle_after)} without an event"