From 938782e2da9f73d333f0285054130e50ec654a68 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 1 Nov 2026 06:19:27 -0600 Subject: [PATCH 1/5] pane(feat[observation]) Retain immutable sampled capture values why: Consumers need capture evidence that remains readable after redraw or pane removal. what: - Copy decoded text and command provenance into a frozen standalone value - Preserve backend routing and reject failed or oversized captures - Document sampled identity limits and verify retained text with an owned producer --- docs/api/index.md | 1 + docs/api/libtmux.observation.md | 48 +++++++++++ src/libtmux/__init__.py | 2 + src/libtmux/observation.py | 132 +++++++++++++++++++++++++++++ tests/test_observation.py | 142 ++++++++++++++++++++++++++++++++ 5 files changed, 325 insertions(+) create mode 100644 docs/api/libtmux.observation.md create mode 100644 src/libtmux/observation.py create mode 100644 tests/test_observation.py diff --git a/docs/api/index.md b/docs/api/index.md index 23cd9043b..560970688 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -173,6 +173,7 @@ Window Pane Client Common +Retained observations Neo Options Hooks diff --git a/docs/api/libtmux.observation.md b/docs/api/libtmux.observation.md new file mode 100644 index 000000000..09fa206de --- /dev/null +++ b/docs/api/libtmux.observation.md @@ -0,0 +1,48 @@ +# Retained pane observations + +`PaneObservation.capture(pane)` keeps decoded pane text and its capture command +in a frozen value. Read it after redraw or pane removal without querying tmux +again. The pane and server remain borrowed. + +```python +>>> from libtmux import PaneObservation +>>> observed = PaneObservation.capture(pane) +>>> observed.pane_id == pane.pane_id +True +>>> isinstance(observed.lines, tuple) +True +>>> observed.text == "\n".join(observed.lines) +True +>>> observed.target_lifetime_verified is None +True +``` + +Use `start`, `end`, and `join_wrapped` to select text with tmux's ordinary +capture semantics. The result retains the selection, actual command argv, and +the controller's monotonic capture interval in nanoseconds. Text uses the +existing command decoder and trailing-empty-line policy. It contains no raw +byte or terminal-column positions. + +`max_text_codepoints` bounds admitted decoded text, including LF between lines. +It counts Python Unicode code points. Oversized text raises `ValueError`; +tmux failures raise instead of becoming successful empty observations. The +limit applies after the existing transport returns, so it does not bound +transport memory. The call keeps the selected backend's blocking behavior. + +The legacy pane ID cannot prove which daemon or pane lifetime supplied a +capture after replacement; `target_lifetime_verified` remains unknown. The +interval describes one sampled command, without an atomic metadata/content +checkpoint. Retained text remains readable after observer or server loss while +you retain the value. Process exit loses the in-memory value. No serializer or +persistent record is supplied. + +A later capture can recover then-visible text, not omitted output, erased +history, or hidden terminal state. Visible text and echoed commands do not +prove application completion; use an explicit producer signal when your +application cooperates. + +```{eval-rst} +.. autoclass:: libtmux.PaneObservation + :members: + :member-order: bysource +``` diff --git a/src/libtmux/__init__.py b/src/libtmux/__init__.py index c99fde4bd..c3bb66a5c 100644 --- a/src/libtmux/__init__.py +++ b/src/libtmux/__init__.py @@ -15,6 +15,7 @@ __version__, ) from .client import Client +from .observation import PaneObservation from .pane import Pane from .server import Server from .session import Session @@ -25,6 +26,7 @@ __all__ = ( "Client", "Pane", + "PaneObservation", "Server", "Session", "Window", diff --git a/src/libtmux/observation.py b/src/libtmux/observation.py new file mode 100644 index 000000000..383f47c9e --- /dev/null +++ b/src/libtmux/observation.py @@ -0,0 +1,132 @@ +"""Immutable sampled pane text and capture provenance.""" + +from __future__ import annotations + +import time +import typing as t +from dataclasses import dataclass, field + +from libtmux import exc +from libtmux.common import raise_if_stderr + +if t.TYPE_CHECKING: + from libtmux.pane import Pane + + +@dataclass(frozen=True, slots=True) +class PaneObservation: + """Retain decoded capture text without a live pane or server reference. + + ``lines`` and ``command`` are owned tuples. The interval counts controller + monotonic nanoseconds around one command; it is not a server timestamp. + ``pane_id`` records the requested target. Its daemon/object lifetime remains + unknown with the legacy pane handle, so ``target_lifetime_verified`` is None. + """ + + pane_id: str + lines: tuple[str, ...] = field(repr=False) + command: tuple[str, ...] = field(repr=False) + start: t.Literal["-"] | int | None + end: t.Literal["-"] | int | None + join_wrapped: bool + started_ns: int + finished_ns: int + target_lifetime_verified: bool | None = field(default=None, init=False) + + @property + def text(self) -> str: + """Return retained lines joined with LF, without terminal-column semantics.""" + return "\n".join(self.lines) + + @classmethod + def capture( + cls, + pane: Pane, + *, + start: t.Literal["-"] | int | None = None, + end: t.Literal["-"] | int | None = None, + join_wrapped: bool = False, + max_text_codepoints: int = 1_048_576, + ) -> PaneObservation: + """Capture once through the supplied pane's command route. + + The call retains plain decoded text using the existing command's + trailing-empty-line policy. The text limit includes LF between lines + and counts Python Unicode code points. It applies after transport + decoding; it is not a transport memory cap or command deadline. + + Parameters + ---------- + pane : Pane + Borrowed pane providing the backend and target. No cleanup is acquired. + start, end : int | "-" | None + Requested tmux line range, using ordinary capture-pane semantics. + join_wrapped : bool + Join wrapped physical lines using tmux's capture policy. + max_text_codepoints : int + Positive admission limit for retained decoded text, including LF. + + Raises + ------ + ValueError + Invalid selection, absent pane ID, or text exceeding the limit. + TypeError + ``join_wrapped`` is not a bool. + libtmux.exc.LibTmuxException + The capture command reports stderr or a nonzero/unknown exit status. + + Notes + ----- + Backend exceptions propagate unchanged. Blocking defaults remain those + of ``pane.cmd``; this method adds no cancellation operation. A retained + value survives pane removal while referenced, but supplies no continuity, + durable storage, hidden terminal state, or application-completion proof. + """ + if ( + isinstance(max_text_codepoints, bool) + or not isinstance(max_text_codepoints, int) + or max_text_codepoints <= 0 + ): + msg = "max_text_codepoints must be a positive integer" + raise ValueError(msg) + for name, value in (("start", start), ("end", end)): + if value is not None and ( + isinstance(value, bool) or not (isinstance(value, int) or value == "-") + ): + msg = f"{name} must be an integer, '-' or None" + raise ValueError(msg) + if not isinstance(join_wrapped, bool): + msg = "join_wrapped must be a bool" + raise TypeError(msg) + pane_id = pane.pane_id + if not pane_id: + msg = "Pane must have a pane_id to capture" + raise ValueError(msg) + args = ["-p"] + if start is not None: + args.extend(("-S", str(start))) + if end is not None: + args.extend(("-E", str(end))) + if join_wrapped: + args.append("-J") + started_ns = time.monotonic_ns() + result = pane.cmd("capture-pane", *args, target=pane_id) + finished_ns = time.monotonic_ns() + raise_if_stderr(result, "capture-pane") + if result.returncode != 0: + msg = f"command exited with status {result.returncode}" + raise exc.LibTmuxException(msg, subcommand="capture-pane") + text_size = sum(map(len, result.stdout)) + max(0, len(result.stdout) - 1) + if text_size > max_text_codepoints: + msg = "captured text exceeds max_text_codepoints" + raise ValueError(msg) + return cls( + pane_id=pane_id, + lines=tuple(result.stdout), + command=tuple(result.cmd), + start=start, + end=end, + join_wrapped=join_wrapped, + started_ns=started_ns, + finished_ns=finished_ns, + ) diff --git a/tests/test_observation.py b/tests/test_observation.py new file mode 100644 index 000000000..76ce1027f --- /dev/null +++ b/tests/test_observation.py @@ -0,0 +1,142 @@ +"""Retained capture values preserve text, routing and failure distinctions.""" + +from __future__ import annotations + +import dataclasses +import os +import pathlib +import shlex +import subprocess +import sys +import typing as t + +import pytest + +from libtmux import Pane, PaneObservation, exc +from libtmux.common import tmux_cmd + +if t.TYPE_CHECKING: + from libtmux.server import Server + + +def test_observation_owns_text_and_actual_command( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A controlled backend permits alias mutation after the capture returns.""" + result = object.__new__(tmux_cmd) + result.stdout = ["界 e\u0301 😀", "second"] + result.stderr = [] + result.returncode = 0 + result.cmd = ["backend", "capture-pane", "-p", "-S", "0", "-E", "-", "-J"] + pane = object.__new__(Pane) + pane.pane_id = "%23" + calls = [] + + def capture(cmd: str, *args: object, target: str | int | None = None) -> tmux_cmd: + calls.append((cmd, args, target)) + return result + + monkeypatch.setattr(pane, "cmd", capture) + value = PaneObservation.capture(pane, start=0, end="-", join_wrapped=True) + result.stdout[0] = "changed" + result.cmd[0] = "changed" + assert value.lines == ("界 e\u0301 😀", "second") + assert value.command[0] == "backend" + assert value.text == "界 e\u0301 😀\nsecond" + assert (value.start, value.end, value.join_wrapped) == (0, "-", True) + assert value.pane_id == "%23" + assert calls == [("capture-pane", ("-p", "-S", "0", "-E", "-", "-J"), "%23")] + assert 0 < value.started_ns <= value.finished_ns + assert value.target_lifetime_verified is None + with pytest.raises(dataclasses.FrozenInstanceError): + setattr(value, "pane_id", "%24") # noqa: B010 - test runtime freezing + assert not isinstance(value, Pane) + assert not hasattr(value, "server") and not hasattr(value, "cmd") + + +def test_observation_bounds_and_backend_failures( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A controlled backend distinguishes empty text, refusal, and native errors.""" + pane = object.__new__(Pane) + pane.pane_id = "%23" + calls = [] + result = object.__new__(tmux_cmd) + result.stdout, result.stderr, result.cmd, result.returncode = [], [], [], 0 + failure = RuntimeError("remote backend failed") + + def capture(*args: object, **kwargs: object) -> tmux_cmd: + calls.append(args) + return result + + monkeypatch.setattr(pane, "cmd", capture) + for limit in (0, -1, True, 1.5): + with pytest.raises(ValueError, match="positive integer"): + PaneObservation.capture(pane, max_text_codepoints=t.cast("int", limit)) + with pytest.raises(ValueError, match="start"): + PaneObservation.capture(pane, start=t.cast("int", "invalid")) + assert not calls + assert PaneObservation.capture(pane).lines == () + result.stdout = ["😀", "e\u0301"] + assert PaneObservation.capture(pane, max_text_codepoints=4).text == "😀\ne\u0301" + with pytest.raises(ValueError, match="exceeds"): + PaneObservation.capture(pane, max_text_codepoints=3) + result.stderr = ["no such pane"] + with pytest.raises(exc.LibTmuxException, match="no such pane"): + PaneObservation.capture(pane) + result.stderr, result.returncode = [], 1 + with pytest.raises(exc.LibTmuxException, match="status 1"): + PaneObservation.capture(pane) + + def failed(*args: object, **kwargs: object) -> tmux_cmd: + raise failure + + monkeypatch.setattr(pane, "cmd", failed) + with pytest.raises(RuntimeError) as raised: + PaneObservation.capture(pane) + assert raised.value is failure + pane.pane_id = None + with pytest.raises(ValueError, match="pane_id"): + PaneObservation.capture(pane) + + +def test_observation_retains_cooperative_producer_after_removal( + server: Server, + tmp_path: pathlib.Path, +) -> None: + """A signalled producer supplies text without requiring shell startup control.""" + server.config_file = os.devnull + server.new_session(session_name="keeper", window_command="cat") + producer = tmp_path / "observation.py" + producer.write_text( + "import subprocess, sys\n" + "sys.stdout.write('界 e\\u0301 😀\\nretained\\n')\n" + "sys.stdout.flush()\n" + "subprocess.run(['tmux', '-L' + sys.argv[1], 'wait-for', '-S', " + "'observation-ready'], check=True, timeout=0.5)\n" + "sys.stdin.readline()\n", + ) + observed = server.new_session( + session_name="observed", + window_command=shlex.join( + [sys.executable, str(producer), str(server.socket_name)] + ), + ) + pane = observed.active_pane + assert pane is not None + subprocess.run( + ["tmux", f"-L{server.socket_name}", "wait-for", "observation-ready"], + check=True, + capture_output=True, + timeout=0.5, + ) + value = PaneObservation.capture(pane, start=-20) + assert "界 e\u0301 😀" in value.lines + assert "retained" in value.lines + before = value.lines + assert f"-L{server.socket_name}" in value.command + pane.kill() + assert value.lines == before and "retained" in value.text + with pytest.raises(exc.LibTmuxException): + PaneObservation.capture(pane) + assert server.is_alive() From 3f6124ba9ef450aaf9d5d8487bf4111eb4db2f27 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 1 Nov 2026 07:46:07 -0600 Subject: [PATCH 2/5] CHANGES(docs) Retained pane observations (#810) why: Readers need product notes before adopting this change. what: - Describe retained pane observations in the unreleased changelog - Reference PR #810 --- CHANGES | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGES b/CHANGES index 16765e2a1..101b83578 100644 --- a/CHANGES +++ b/CHANGES @@ -45,6 +45,14 @@ $ uvx --from 'libtmux' --prerelease allow python _Notes on the upcoming release will go here._ +### What's new + +#### Retained pane observations + +Retain immutable pane text and capture details with +`PaneObservation.capture()`, even after the pane changes or disappears. +These sampled values remain readable without another tmux query. (#810) + ### Documentation #### Cleaner `from_env` examples (#719) From 42b9b46ba8da2dc61adddaf73ea1cb3a8f6faaaa Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Thu, 5 Nov 2026 23:13:10 -0600 Subject: [PATCH 3/5] pane(fix[observation]) Freeze text before checking its limit why: A backend can change its mutable output after size validation, leaving an observation with more retained text than its admission limit permits. what: - Copy decoded lines once before measuring and retaining them - Cover native custom routing, redraw, pane removal and server removal - Document observation fields and qualify producer signal semantics --- CHANGES | 7 ++-- docs/api/libtmux.observation.md | 11 +++--- src/libtmux/observation.py | 22 ++++++++++- tests/test_observation.py | 65 +++++++++++++++++++++++++++------ 4 files changed, 83 insertions(+), 22 deletions(-) diff --git a/CHANGES b/CHANGES index 101b83578..b9d38be34 100644 --- a/CHANGES +++ b/CHANGES @@ -47,11 +47,12 @@ _Notes on the upcoming release will go here._ ### What's new -#### Retained pane observations +#### Retained pane observations (#810) Retain immutable pane text and capture details with -`PaneObservation.capture()`, even after the pane changes or disappears. -These sampled values remain readable without another tmux query. (#810) +{meth}`PaneObservation.capture() `, even after +the pane changes or disappears. These sampled values remain readable without +another tmux query. ### Documentation diff --git a/docs/api/libtmux.observation.md b/docs/api/libtmux.observation.md index 09fa206de..5892229ba 100644 --- a/docs/api/libtmux.observation.md +++ b/docs/api/libtmux.observation.md @@ -1,8 +1,9 @@ # Retained pane observations -`PaneObservation.capture(pane)` keeps decoded pane text and its capture command -in a frozen value. Read it after redraw or pane removal without querying tmux -again. The pane and server remain borrowed. +{meth}`PaneObservation.capture() ` keeps +decoded pane text and its capture command in a frozen value. Read it after +redraw or pane removal without querying tmux again. The pane and server remain +borrowed. ```python >>> from libtmux import PaneObservation @@ -38,8 +39,8 @@ persistent record is supplied. A later capture can recover then-visible text, not omitted output, erased history, or hidden terminal state. Visible text and echoed commands do not -prove application completion; use an explicit producer signal when your -application cooperates. +prove application completion. A cooperating producer can signal an +application-defined milestone; the signal proves only that milestone. ```{eval-rst} .. autoclass:: libtmux.PaneObservation diff --git a/src/libtmux/observation.py b/src/libtmux/observation.py index 383f47c9e..ad6134136 100644 --- a/src/libtmux/observation.py +++ b/src/libtmux/observation.py @@ -21,6 +21,23 @@ class PaneObservation: monotonic nanoseconds around one command; it is not a server timestamp. ``pane_id`` records the requested target. Its daemon/object lifetime remains unknown with the legacy pane handle, so ``target_lifetime_verified`` is None. + + Attributes + ---------- + pane_id : str + Requested tmux pane ID. + lines : tuple[str, ...] + Owned decoded text, preserving the command's trailing-empty-line policy. + command : tuple[str, ...] + Actual command argv reported by the selected backend. + start, end : int | "-" | None + Requested capture range; None leaves that endpoint at tmux's default. + join_wrapped : bool + Whether the capture requested joined physical lines with ``-J``. + started_ns, finished_ns : int + Controller monotonic nanoseconds immediately before and after the command. + target_lifetime_verified : bool | None + None: the legacy pane handle supplies no daemon or pane lifetime proof. """ pane_id: str @@ -116,13 +133,14 @@ def capture( if result.returncode != 0: msg = f"command exited with status {result.returncode}" raise exc.LibTmuxException(msg, subcommand="capture-pane") - text_size = sum(map(len, result.stdout)) + max(0, len(result.stdout) - 1) + lines = tuple(result.stdout) + text_size = sum(map(len, lines)) + max(0, len(lines) - 1) if text_size > max_text_codepoints: msg = "captured text exceeds max_text_codepoints" raise ValueError(msg) return cls( pane_id=pane_id, - lines=tuple(result.stdout), + lines=lines, command=tuple(result.cmd), start=start, end=end, diff --git a/tests/test_observation.py b/tests/test_observation.py index 76ce1027f..eaac3e7ed 100644 --- a/tests/test_observation.py +++ b/tests/test_observation.py @@ -12,12 +12,9 @@ import pytest -from libtmux import Pane, PaneObservation, exc +from libtmux import Pane, PaneObservation, Server, exc from libtmux.common import tmux_cmd -if t.TYPE_CHECKING: - from libtmux.server import Server - def test_observation_owns_text_and_actual_command( monkeypatch: pytest.MonkeyPatch, @@ -77,6 +74,16 @@ def capture(*args: object, **kwargs: object) -> tmux_cmd: PaneObservation.capture(pane, start=t.cast("int", "invalid")) assert not calls assert PaneObservation.capture(pane).lines == () + + class MutableLines(list[str]): + """Simulate a backend replacing its buffer after a reader traverses it.""" + + def __iter__(self) -> t.Iterator[str]: + yield from super().__iter__() + self[:] = ["oversized"] + + result.stdout = MutableLines(["x"]) + assert PaneObservation.capture(pane, max_text_codepoints=1).text == "x" result.stdout = ["😀", "e\u0301"] assert PaneObservation.capture(pane, max_text_codepoints=4).text == "😀\ne\u0301" with pytest.raises(ValueError, match="exceeds"): @@ -84,9 +91,11 @@ def capture(*args: object, **kwargs: object) -> tmux_cmd: result.stderr = ["no such pane"] with pytest.raises(exc.LibTmuxException, match="no such pane"): PaneObservation.capture(pane) - result.stderr, result.returncode = [], 1 - with pytest.raises(exc.LibTmuxException, match="status 1"): - PaneObservation.capture(pane) + result.stdout, result.stderr = [], [] + for status in (1, None): + result.returncode = status + with pytest.raises(exc.LibTmuxException, match=f"status {status}"): + PaneObservation.capture(pane) def failed(*args: object, **kwargs: object) -> tmux_cmd: raise failure @@ -103,8 +112,9 @@ def failed(*args: object, **kwargs: object) -> tmux_cmd: def test_observation_retains_cooperative_producer_after_removal( server: Server, tmp_path: pathlib.Path, + monkeypatch: pytest.MonkeyPatch, ) -> None: - """A signalled producer supplies text without requiring shell startup control.""" + """Retain an actual routed capture through redraw and native teardown.""" server.config_file = os.devnull server.new_session(session_name="keeper", window_command="cat") producer = tmp_path / "observation.py" @@ -114,6 +124,11 @@ def test_observation_retains_cooperative_producer_after_removal( "sys.stdout.flush()\n" "subprocess.run(['tmux', '-L' + sys.argv[1], 'wait-for', '-S', " "'observation-ready'], check=True, timeout=0.5)\n" + "sys.stdin.readline()\n" + "sys.stdout.write('\\x1b[2J\\x1b[Hreplacement\\n')\n" + "sys.stdout.flush()\n" + "subprocess.run(['tmux', '-L' + sys.argv[1], 'wait-for', '-S', " + "'observation-redrawn'], check=True, timeout=0.5)\n" "sys.stdin.readline()\n", ) observed = server.new_session( @@ -130,13 +145,39 @@ def test_observation_retains_cooperative_producer_after_removal( capture_output=True, timeout=0.5, ) - value = PaneObservation.capture(pane, start=-20) + facade = Pane( + server=Server(socket_path=str(tmp_path / "unused-socket")), + pane_id=pane.pane_id, + ) + monkeypatch.setattr(facade, "cmd", pane.cmd) + assert not facade.server.is_alive() + value = PaneObservation.capture(facade, start=-20) assert "界 e\u0301 😀" in value.lines assert "retained" in value.lines - before = value.lines + with pytest.raises(ValueError, match="exceeds"): + PaneObservation.capture(facade, max_text_codepoints=1) + before = dataclasses.astuple(value) assert f"-L{server.socket_name}" in value.command + assert str(tmp_path / "unused-socket") not in value.command + pane.send_keys("", enter=True) + subprocess.run( + ["tmux", f"-L{server.socket_name}", "wait-for", "observation-redrawn"], + check=True, + capture_output=True, + timeout=0.5, + ) + later = PaneObservation.capture(facade, start=-20) + assert "replacement" in later.lines + assert "replacement" not in value.lines + assert later.started_ns >= value.finished_ns + assert dataclasses.astuple(value) == before pane.kill() - assert value.lines == before and "retained" in value.text + assert dataclasses.astuple(value) == before and "retained" in value.text with pytest.raises(exc.LibTmuxException): - PaneObservation.capture(pane) + PaneObservation.capture(facade) assert server.is_alive() + server.kill() + assert not server.is_alive() + assert dataclasses.astuple(value) == before and "retained" in value.text + with pytest.raises(exc.LibTmuxException): + PaneObservation.capture(facade) From 4e7afa33d8f92b07e9832e02e196cff354a25d24 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Fri, 6 Nov 2026 19:49:42 -0600 Subject: [PATCH 4/5] py(deps[dev]) Raise Ruff floor to 0.17.3 why: Keep development and CI linting on the same Ruff release, including corrected f-string conversions and safer lint fixes. what: - Raise Ruff floors in the development and lint dependency groups - Lock Ruff 0.17.3 with its published source and wheel hashes Ruff release notes: https://github.com/astral-sh/ruff/releases/tag/0.17.2 https://github.com/astral-sh/ruff/releases/tag/0.17.3 --- pyproject.toml | 4 ++-- uv.lock | 46 +++++++++++++++++++++++----------------------- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 855876066..1d80f8042 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,7 +70,7 @@ dev = [ "coverage", "pytest-cov", # Lint - "ruff>=0.17.1", + "ruff>=0.17.3", "mypy", ] @@ -95,7 +95,7 @@ coverage =[ ] lint = [ "typing-extensions; python_version < '3.11'", - "ruff>=0.17.1", + "ruff>=0.17.3", "mypy", ] diff --git a/uv.lock b/uv.lock index 4d9302a7d..e9dba824d 100644 --- a/uv.lock +++ b/uv.lock @@ -829,7 +829,7 @@ dev = [ { name = "pytest-rerunfailures" }, { name = "pytest-watcher" }, { name = "pytest-xdist" }, - { name = "ruff", specifier = ">=0.17.1" }, + { name = "ruff", specifier = ">=0.17.3" }, { name = "sphinx-autobuild" }, { name = "sphinx-autodoc-api-style", specifier = "==0.1.0a39" }, { name = "sphinx-autodoc-pytest-fixtures", specifier = "==0.1.0a39" }, @@ -844,7 +844,7 @@ docs = [ ] lint = [ { name = "mypy" }, - { name = "ruff", specifier = ">=0.17.1" }, + { name = "ruff", specifier = ">=0.17.3" }, { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] testing = [ @@ -1401,27 +1401,27 @@ wheels = [ [[package]] name = "ruff" -version = "0.17.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/f9/e7/e6d5749983b020e6cb1055abec0a6f361a8e94f0184cdcf56d4760995f02/ruff-0.17.1.tar.gz", hash = "sha256:5bb796c5112e9fb9527f2ef2faa0a130d6312d19de92bcfaddd70dbb2d41020f", size = 5323349, upload-time = "2026-10-15T15:23:18.64Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/2e/78/90c46ca6250709f7c37e397b60d06061adee8d0f7d13959ed6a8e49b14fd/ruff-0.17.1-py3-none-linux_armv6l.whl", hash = "sha256:1796c41eafec66f4635125dd1e074a7aa27b8d20c187d484360acf11d247fc4a", size = 10147528, upload-time = "2026-10-15T15:22:33.667Z" }, - { url = "https://files.pythonhosted.org/packages/aa/d2/a2e28bc35b083ae51fa07dfba5280a667c8b01ecaee7802fc8849dcd5c46/ruff-0.17.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:8eadb09a788010be29c895418bdfa513e4e1c65e64b94e5b19e4cd381f6cc7fb", size = 10225974, upload-time = "2026-10-15T15:22:36.328Z" }, - { url = "https://files.pythonhosted.org/packages/8e/71/7a9029a81c8206ee01a98f6cfeeb56e6c095af86857581a37045c46d7e94/ruff-0.17.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:29b454f18ca3eeaf37fbf140841dcf27d36109e29dee9aae8acecb68c26c6f74", size = 9270361, upload-time = "2026-10-15T15:22:38.651Z" }, - { url = "https://files.pythonhosted.org/packages/c0/8c/e075e9c917cb0575297880c96768304e881240171c870cbd8d9b7b54bec2/ruff-0.17.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:872e03dd231744d6c5ec5c8af6be52b71323fc6ee096e4c8b34d9f844ee3b978", size = 9938300, upload-time = "2026-10-15T15:22:41.284Z" }, - { url = "https://files.pythonhosted.org/packages/87/27/0b4bb926a49de2383f161272b4d863571a4c7ecdbf595a6bc58813a13367/ruff-0.17.1-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:4c0d6cb5f8fbac77eec9af49f4fc0eaf856b05545e372b0694d24b4e76b1c640", size = 9948464, upload-time = "2026-10-15T15:22:43.681Z" }, - { url = "https://files.pythonhosted.org/packages/14/27/518d57e0e02aecb8ea4acac6b57b51a53173d25fa734952bfdd7d531e88e/ruff-0.17.1-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:78beced4a3c94dfedbee4b999b95b6a27b35820fdc0afbacc6d37a8da26c1cd1", size = 10638639, upload-time = "2026-10-15T15:22:46.081Z" }, - { url = "https://files.pythonhosted.org/packages/01/82/d89a4e498ade59e6cee52d67f8da569019372212b87468c1fdeae884601c/ruff-0.17.1-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7feefc63921202894f0e158b0e32f45a5950d70a7fb693ccb9264816c25b1c05", size = 11337238, upload-time = "2026-10-15T15:22:48.894Z" }, - { url = "https://files.pythonhosted.org/packages/a2/7c/3b0fdef9352656317c977086fe1d802902406e4f2a0d8578da90c0e6d1c5/ruff-0.17.1-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:684154861a819bf1f433669d2a0ce9c3e54677c65b8ebb866cc2a7ec86345785", size = 10896327, upload-time = "2026-10-15T15:22:51.45Z" }, - { url = "https://files.pythonhosted.org/packages/62/86/5566290219708ce2928f3a29c4f843a1185b341ec6111c4631a33c5ceced/ruff-0.17.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a6ef98e51de8ef38082f90653ceeb84944bd7673783eea13e1647c5b9b064189", size = 10350811, upload-time = "2026-10-15T15:22:54.401Z" }, - { url = "https://files.pythonhosted.org/packages/ad/d2/ca8462dabb3c413990d49703ba306c30c862195a75448d080fa8fcce9775/ruff-0.17.1-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:8f9aa5b5bd5fa1937803ea609c8f153b8de39bf3e0e149897ae34b0c5b52f467", size = 10569994, upload-time = "2026-10-15T15:22:57.142Z" }, - { url = "https://files.pythonhosted.org/packages/e3/ad/dd1864c1f1db17c8cfb297ce70b352388e6977620f66f7182c52855407df/ruff-0.17.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:80e53b0e5faa3c5667f035daaa032893ae42b7cfe708c886d39ed131e54688ab", size = 10059672, upload-time = "2026-10-15T15:23:00.084Z" }, - { url = "https://files.pythonhosted.org/packages/65/45/3f56cf1d2168c2165cdd5ac6f9668aee66a4cfdd4caf2b2cc5ccb2b1d568/ruff-0.17.1-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:056c5d5fa0ac790051ae165d7035c7bf956d02de2db557f2e9b31d877a505fca", size = 9947803, upload-time = "2026-10-15T15:23:03.132Z" }, - { url = "https://files.pythonhosted.org/packages/aa/4b/5457cb2be4c1d1ea5e919558131a0f197a4a454a0530d9e30820e8206e4c/ruff-0.17.1-py3-none-musllinux_1_2_i686.whl", hash = "sha256:bd8f5a55b10f371642eacd0e8665a42a8b97da15c9a7187c79e697b77b5e0ce4", size = 10351807, upload-time = "2026-10-15T15:23:05.628Z" }, - { url = "https://files.pythonhosted.org/packages/49/fb/db15b4f8fa24a1e36b99e1401f42ef6df16ee299a48670d5d262b771e7d7/ruff-0.17.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:ce05e6f3973611d9550a600e04bb531061e368baba31610eb57c1509a8f21a0a", size = 10765716, upload-time = "2026-10-15T15:23:08.092Z" }, - { url = "https://files.pythonhosted.org/packages/0a/e8/1e186578076aff7a80735f625005fde678412ab609cd323ed182eb7d6b87/ruff-0.17.1-py3-none-win32.whl", hash = "sha256:1de0030a8aa78c65c5fecb84b2e5c390ac684c0452875a02afc7c083d49a496a", size = 9895093, upload-time = "2026-10-15T15:23:10.582Z" }, - { url = "https://files.pythonhosted.org/packages/6a/2e/da3d9589bae8e8b58f3a48bd5bc0b980232fb14a83bf02c3be7660f87c1b/ruff-0.17.1-py3-none-win_amd64.whl", hash = "sha256:5df76f16580fab58d0f6c98a3ac254a4abceb7b2489b8b678335869cff77b3d7", size = 10097955, upload-time = "2026-10-15T15:23:13.309Z" }, - { url = "https://files.pythonhosted.org/packages/df/c9/0f2a4dea06a5e12c1191ee3d96b1e1233797d0d5e18f97a2b909a95a9836/ruff-0.17.1-py3-none-win_arm64.whl", hash = "sha256:42400b9a6ff8515ff27796f07f92e0195be011c86e81e381606f58ea5502fef4", size = 9853542, upload-time = "2026-10-15T15:23:16.05Z" }, +version = "0.17.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/59/73/81f140c4edd9cc323de5478e6bbd3bbcfae9a82692df1a258de8cec6a6d2/ruff-0.17.3.tar.gz", hash = "sha256:a57049c8addb3662073859bb55a7ad35aa54f8a7c9ed268911d1333c5aadaaa9", size = 5339444, upload-time = "2026-10-27T00:34:05.914Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9e/8c/083365310c4e79c842f25bf5a842facbd9b0c0ec336f96dffa5074fe723d/ruff-0.17.3-py3-none-linux_armv6l.whl", hash = "sha256:ab86b84cd9d05e56d329742c0cabdcbe2d1d56c98f4a04aab9b5b66196febfb4", size = 10216522, upload-time = "2026-10-27T00:33:29.822Z" }, + { url = "https://files.pythonhosted.org/packages/72/26/4b2edf31cfebe9605d8f6ed8f1d6f376d3a53d4c9a123e62661c64c440f0/ruff-0.17.3-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e407b4a6852853a9a2cdce96963e94ad9775578bb44e7561a0f2829f3cc04b11", size = 10217786, upload-time = "2026-10-27T00:33:33.949Z" }, + { url = "https://files.pythonhosted.org/packages/a2/7e/537aba4b7f54397a374d2f6a6fc93e9c8015e18553f31a4a7b7dbced48b5/ruff-0.17.3-py3-none-macosx_11_0_arm64.whl", hash = "sha256:b75cc113b3aca388933d8296b667b1ac401a80317ea3074c9b0a66541199da29", size = 9440362, upload-time = "2026-10-27T00:33:35.784Z" }, + { url = "https://files.pythonhosted.org/packages/3d/66/283e39734f66c8a5ebaa93c22eb7b7515779a0b1d5a5c0ad20e05c0edb41/ruff-0.17.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ab5fa7ed5ce18554ea69d850ad162cbaa0c85fc47c08d83a569f806681c9a6ad", size = 10094281, upload-time = "2026-10-27T00:33:38.216Z" }, + { url = "https://files.pythonhosted.org/packages/21/4c/1ffc768497bd025a32c72152771e40c0b99bddc5cc6e4f50c7949a395346/ruff-0.17.3-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c673c170e27834d1262e3a9c1e97bdc9b9c3b180c63d89173ce69747232474c1", size = 10022543, upload-time = "2026-10-27T00:33:40.181Z" }, + { url = "https://files.pythonhosted.org/packages/73/c3/f90db547301080fcb82c92abf914c8bd57b89911d9b65a6c4cc6b52d0635/ruff-0.17.3-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:6a754c0341bc9ca151b7b335988b3263921c08859f84ca219b70cee825571b6f", size = 10683921, upload-time = "2026-10-27T00:33:42.182Z" }, + { url = "https://files.pythonhosted.org/packages/e5/98/92d4a8a26c6c96cf1a5b34dd59036d8a71e52d650aab065c58867e964e63/ruff-0.17.3-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4590b9d86c0b1543ebb09094254e191cd43fe8edaf330baa035aab03da251532", size = 11373408, upload-time = "2026-10-27T00:33:44.19Z" }, + { url = "https://files.pythonhosted.org/packages/43/02/1f24d2e3064c9753926deeb901afa57777b37ee46799b09ddd7aee6e5145/ruff-0.17.3-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bbde18beccd98c29a227c63c99022e3443b99258e08326df6425dfe0443705ef", size = 10977469, upload-time = "2026-10-27T00:33:46.179Z" }, + { url = "https://files.pythonhosted.org/packages/f0/20/fecedea2209f574ab92033b344e01a7f0c2dc76c6d6d19a14c9f8141173f/ruff-0.17.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7fa4b0f931cdbcb8a52044f370a3eb429fb42eb88807b0e800fcaa98dd42b24e", size = 10577491, upload-time = "2026-10-27T00:33:48.233Z" }, + { url = "https://files.pythonhosted.org/packages/33/36/b93fdf0bc6f84f0cd487aadfb0354deb40013669ea35ac3d26855de1e959/ruff-0.17.3-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:39405f341deec934b4289634324ad695f72df2970f9121582872eaf5b722f0f5", size = 10608748, upload-time = "2026-10-27T00:33:50.284Z" }, + { url = "https://files.pythonhosted.org/packages/5d/b7/7d3f5f14145daead1efb0b9a8289ed1daa100f419d60774375951723ce00/ruff-0.17.3-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:68074094f55ca3d29ab19491f640282f7a84061c4c7977aa5094b968ca457e9a", size = 10075057, upload-time = "2026-10-27T00:33:52.074Z" }, + { url = "https://files.pythonhosted.org/packages/b0/ed/93ff7a5909ee56e2bd4b982deae9e0efb2724417874a90c9e41ad66c6dd7/ruff-0.17.3-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:27bb571ac78fef178fe5118d2827df95c2aae74a48fff2b15f6acd03af5ff5bb", size = 10022431, upload-time = "2026-10-27T00:33:54.061Z" }, + { url = "https://files.pythonhosted.org/packages/9b/07/a83b9eeec8c1c3c0e4eda15f06c3a91001bfd2687ea2f07b750719bf9712/ruff-0.17.3-py3-none-musllinux_1_2_i686.whl", hash = "sha256:029c37cbd3de48ca37aa12117bead2d065f15da17d66bf84e0d4274013705db2", size = 10394903, upload-time = "2026-10-27T00:33:56.158Z" }, + { url = "https://files.pythonhosted.org/packages/af/b2/05c39857c2526fcbebe46ad93a8dc97424656dfef14d3ef933abe1ffd331/ruff-0.17.3-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:692fdb46d0fd9c71e380947dc5fc72f2c3f881073bc1f739e4579376231affbe", size = 10799780, upload-time = "2026-10-27T00:33:58.204Z" }, + { url = "https://files.pythonhosted.org/packages/ec/d9/47171a16739eb7a353936b31c20cf54340531e68c9af7d72fd7a784e235d/ruff-0.17.3-py3-none-win32.whl", hash = "sha256:46539cb031b01fd29ae0a02142483c46640b233ee12bb1c1b690bffa1555d5ca", size = 9908481, upload-time = "2026-10-27T00:34:00.087Z" }, + { url = "https://files.pythonhosted.org/packages/d0/a0/f08c1631bfd81faa6a90eaf70c37c786c11bed2046302b56bb506c25e1a0/ruff-0.17.3-py3-none-win_amd64.whl", hash = "sha256:56b8ffb3f3b3cbccb8b76b71b38261b7ed982ef5d20f5b447b1b61a7f4949b24", size = 10341333, upload-time = "2026-10-27T00:34:02.099Z" }, + { url = "https://files.pythonhosted.org/packages/99/d5/4ad4ed31413c301430918e70d3d38ae6f097af0766cb9ab8c9d502b2a4d6/ruff-0.17.3-py3-none-win_arm64.whl", hash = "sha256:81fce74bcd6be0e9da7c67c7553fd0f1f12964a2052cd728ef917b937a5ca1d9", size = 9854332, upload-time = "2026-10-27T00:34:03.847Z" }, ] [[package]] From ce4abc582f8bbf3f741b794c2283981d52ad54c7 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Fri, 6 Nov 2026 20:15:37 -0600 Subject: [PATCH 5/5] CHANGES(docs): Record the Ruff development floor why: Contributors need the lint-tool requirement alongside other development environment changes. what: - Document the Ruff 0.17.3 minimum for development and lint checks --- CHANGES | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGES b/CHANGES index b9d38be34..b11dd7fc3 100644 --- a/CHANGES +++ b/CHANGES @@ -68,6 +68,10 @@ it. ### Development +#### Ruff 0.17.3 for development (#810) + +Minimum `ruff>=0.17.3` (was `>=0.17.1`) for development and CI lint checks. + #### CI recovers from incompatible tmux caches (#835) CI rebuilds incompatible cached tmux installations before running tests.