Predictable error contract for display_message wrappers

Đang mở
#676 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
30/100
Loại issue
Tính năng
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Ít trao đổi
Công nghệ
python
Lĩnh vực
api, cli

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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:

  1. 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.
  2. 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)
Ngôn ngữ chính
Python
Star
1.2k
Fork
127
Merge trung bình
2 giờ 13 phút
Pull request đã merge (30 ngày)
1

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của tmux-python/libtmux

Tất cả issue của tmux-python/libtmux

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.