Predictable error contract for display_message wrappers
まだ誰も着手していません。
評価
調査の方向性
Begin with Server.display_message, Window.display_message, and Pane.display_message and the existing display_message tests; reproduce the undefined-token case on tmux 3.4+ and compare success and stderr behavior. Review the warning change from #672 and observed real-use stderr before selecting a contract. Done means removing version-gated test skips, documenting escalation in MIGRATION, and adding a CHANGES entry.
索引モデルが issue の本文から書いたものです。
説明
What ships
A deliberate stderr-handling semantic for the three
`display_message` wrappers (`Server.display_message`,
`Window.display_message`, `Pane.display_message`). Likely one of:
- Version-gated raise via `has_gte_version("3.3")` (warn on tmux
3.2a where control-mode dispatch is unreliable, raise on 3.3+) - A per-call `raise_on_stderr: bool = False` kwarg so callers
opt in to escalation - A permanent `warnings.warn` contract with no escalation path
beyond `warnings.catch_warnings(filterwarnings("error"))`
The choice will be driven by observed user pain — what kinds of
stderr tmux actually emits in practice, and what shape of escalation
callers reach for.
Problem solved
Callers need a way to distinguish "tmux rejected my format string"
from "tmux returned empty legitimately." #672 softened the wrappers
to `warnings.warn` because raising had two issues:
- tmux 3.2a's control-mode dispatch path can fail silently (no
stderr emitted), so raising on stderr doesn't actually catch
that bug — it just made other tests skip with
`has_gte_version("3.3")` workarounds. - tmux uses stderr for both genuine errors and informational
messages, and the right escalation depends on tmux version and
call shape.
The warn-soften gives users access to the stderr without losing the
return value. This issue tracks the eventual deliberate contract.
Why this is its own shipment
The right contract depends on what kinds of stderr tmux actually
emits in practice, which is observable only after the wrappers see
real use in 0.57.0. Holding the decision until that data exists
prevents locking in a contract that the next release has to break.
Acceptance criteria
- Test asserting `display_message("#{undefined_token}")` on
tmux 3.4+ behaves according to the chosen contract on both
success and stderr paths - No `has_gte_version("3.3")` skip patches on the
`display_message` tests - MIGRATION note describing how callers escalate from warn to
exception (or rationale for permanent warn) - CHANGES entry for the contract change
Current state on master (post-0.57.0)
All three wrappers emit `warnings.warn("display-message: ")`
with `stacklevel=2`. Callers can already escalate via:
```python
import warnings
with warnings.catch_warnings():
warnings.filterwarnings("error", category=UserWarning)
result = pane.display_message("#{pane_id}", get_text=True)
```
The question this issue resolves is whether that escalation path
suffices, or whether the wrappers should grow a more deliberate API.
Refs
- Carved out per the three-auditor synthesis on #672
- Companion to #674 (typed format-token fields)
- 主要言語
- Python
- スター
- 1.2k
- フォーク
- 127
- 平均マージ
- 2時間 13分
- マージ済み PR(30日)
- 1
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
tmux-python/libtmux のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
tmux-python/libtmux#759 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
tmux-python/libtmux#745 · コメント 2 件 ·
-
enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
tmux-python/libtmux#744 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
tmux-python/libtmux#731 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
tmux-python/libtmux#654 ·
tmux-python/libtmux の issue をすべて見る
似ている issue
-
triage/confirmed
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
agentscope-ai/agentscope#2775 ·
-
comp/desktop P3 type/bug
難易度 1/5 1時間未満 初心者へのやさしさ 92/100
NousResearch/hermes-agent#118866 ·
-
bug
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
apache/cloudstack#14222 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100