ttyscan 0.0.4__tar.gz → 0.0.8__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ttyscan
3
- Version: 0.0.4
3
+ Version: 0.0.8
4
4
  Summary: Queries a terminal emulator for its type, size and capabilities
5
5
  Project-URL: Homepage, https://github.com/jquast/ttyscan
6
6
  Author-email: Jeff Quast <contact@jeffquast.com>
@@ -89,7 +89,7 @@ legacy calls to curses of `setupterm(3)`_ to succeed::
89
89
  $ echo $TERM, $TERMINFO
90
90
  rio, /home/jquast/.config/ttyscan/terminfo
91
91
 
92
- $ file -b /home/jquast/.config/ttyscan/terminfo/r/rio
92
+ $ file -b $TERMINFO/r/rio
93
93
  Compiled terminfo entry "rio"
94
94
 
95
95
  $ python -c 'import curses;curses.setupterm()'; echo $?
@@ -109,14 +109,18 @@ CLI Arguments
109
109
  -v, --verbose Print diagnostic information to stderr
110
110
  -f, --force Force export of all values even if unchanged
111
111
  -t, --termcap Also export TERMCAP value
112
+ --version show program's version number and exit
112
113
 
113
114
  *ttyscan* saves a `terminfo(5)`_ file to $XDG_CONFIG_HOME/ttyscan/terminfo or
114
115
  ~/.config/ttyscan/terminfo, and does not re-query or re-create it when it already exists from
115
116
  previous executions, unless ``--force`` argument is used.
116
117
 
117
- Typical total execution time is under 200ms. The default timeout query can be changed by
118
- environment value TTYSCAN_QUERY_TIMEOUT=1.0 (float), in seconds. If timeout is reached, terminal
118
+ Typical total execution time is under 200ms. The default query timeout can be changed by
119
+ environment value ``TTYSCAN_QUERY_TIMEOUT=1.0`` (float), in seconds. If timeout is reached, terminal
119
120
  response may "bleed" into subsequent programs, (like a shell prompt).
121
+ After receiving the initial response, a secondary drain phase collects any remaining XTGETTCAP
122
+ replies, controlled by ``TTYSCAN_DRAIN_TIMEOUT=0.2`` (float). Increase this value if some
123
+ capabilities are intermittently missing, particularly over high-latency SSH connections.
120
124
 
121
125
  Installation
122
126
  ------------
@@ -174,12 +178,19 @@ of support for ``XTGETTCAP``:
174
178
  ``TERM=xterm-256color`` and ``TERM=xterm`` are the most ubiquitous terminal name, you should be
175
179
  just fine.
176
180
 
177
- - **None**: alacritty (refuses: `alacritty/vte#98`_), bobcat, cmd.exe, ConEmu, cool-retro-term,
178
- Extraterm, Hyper, Konsole (requested: `KDE#507017`_), linux fbdev, mintty, PuTTY, QTerminal,
179
- rxvt-unicode, screen, securecrt, st, Tabby, Apple Terminal, Terminal.exe (planned:
181
+ - **No Support**: alacritty (refuses: `alacritty/vte#98`_), bobcat, cmd.exe,
182
+ Extraterm, Hyper, Konsole (requested: `KDE#507017`_), linux fbdev, mintty,
183
+ rxvt-unicode, screen, securecrt, st, Tabby, Terminal.exe (planned:
180
184
  `microsoft/terminal#17735`_), terminology, tmux (passthrough: `tmux/tmux#3755`_), libvterm, VS
181
185
  Code (xterm.js, proposal: `xtermjs/xterm.js#4107`_), weston-terminal, and zutty.
182
186
 
187
+ - **Non-Compliant**: ConEmu, cool-retro-term, Apple Terminal, PuTTY, QTerminal: When a terminal emulator
188
+ does not support XTGETTCAP, it **should** silently consume VT100 Mode DCS queries without answer.
189
+
190
+ However, some non-compliant terminals display XTGETTCAP query output, eg. ``+q544e+q524742+q636f6c6f7273+q626c696e6b+..``
191
+ visually: QTerminal, cool-retro-term, and qtermwidget (`fixed upstream <https://github.com/lxqt/qtermwidget/pull/644>`_),
192
+ PuTTY, ConEmu.exe, and Apple's Terminal.app all fail to parse DCS queries, displaying raw sequence output.
193
+
183
194
  Architecture
184
195
  ------------
185
196
 
@@ -191,6 +202,8 @@ Architecture
191
202
  - DEC Private Mode 2048 (In-Band Resize) to determine the window size
192
203
  - Or failing that, using Cursor Position Report sequence like done in XTerm's `resize.c
193
204
  <https://github.com/joejulian/xterm/blob/master/resize.c>`_
205
+ - DECRQSS_ (Request Setting Selection) to probe truecolor support when ``RGB`` is unavailable,
206
+ by setting and querying a 24-bit background color
194
207
 
195
208
  Details
196
209
  -------
@@ -231,6 +244,7 @@ values when they differ.
231
244
  .. _`agetty(8)`: https://linux.die.net/man/8/agetty
232
245
  .. _`alacritty/vte#98`: https://github.com/alacritty/vte/issues/98
233
246
  .. _contour: https://github.com/contour-terminal/contour
247
+ .. _DECRQSS: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Device-Control-functions:DCS-plus-q-Pt-ST.F95
234
248
  .. _foot: https://codeberg.org/dnkl/foot#xtgettcap
235
249
  .. _ghostty: https://mitchellh.com/writing/ghostty-devlog-004
236
250
  .. _`KDE#507017`: https://bugs.kde.org/show_bug.cgi?id=507017
@@ -59,7 +59,7 @@ legacy calls to curses of `setupterm(3)`_ to succeed::
59
59
  $ echo $TERM, $TERMINFO
60
60
  rio, /home/jquast/.config/ttyscan/terminfo
61
61
 
62
- $ file -b /home/jquast/.config/ttyscan/terminfo/r/rio
62
+ $ file -b $TERMINFO/r/rio
63
63
  Compiled terminfo entry "rio"
64
64
 
65
65
  $ python -c 'import curses;curses.setupterm()'; echo $?
@@ -79,14 +79,18 @@ CLI Arguments
79
79
  -v, --verbose Print diagnostic information to stderr
80
80
  -f, --force Force export of all values even if unchanged
81
81
  -t, --termcap Also export TERMCAP value
82
+ --version show program's version number and exit
82
83
 
83
84
  *ttyscan* saves a `terminfo(5)`_ file to $XDG_CONFIG_HOME/ttyscan/terminfo or
84
85
  ~/.config/ttyscan/terminfo, and does not re-query or re-create it when it already exists from
85
86
  previous executions, unless ``--force`` argument is used.
86
87
 
87
- Typical total execution time is under 200ms. The default timeout query can be changed by
88
- environment value TTYSCAN_QUERY_TIMEOUT=1.0 (float), in seconds. If timeout is reached, terminal
88
+ Typical total execution time is under 200ms. The default query timeout can be changed by
89
+ environment value ``TTYSCAN_QUERY_TIMEOUT=1.0`` (float), in seconds. If timeout is reached, terminal
89
90
  response may "bleed" into subsequent programs, (like a shell prompt).
91
+ After receiving the initial response, a secondary drain phase collects any remaining XTGETTCAP
92
+ replies, controlled by ``TTYSCAN_DRAIN_TIMEOUT=0.2`` (float). Increase this value if some
93
+ capabilities are intermittently missing, particularly over high-latency SSH connections.
90
94
 
91
95
  Installation
92
96
  ------------
@@ -144,12 +148,19 @@ of support for ``XTGETTCAP``:
144
148
  ``TERM=xterm-256color`` and ``TERM=xterm`` are the most ubiquitous terminal name, you should be
145
149
  just fine.
146
150
 
147
- - **None**: alacritty (refuses: `alacritty/vte#98`_), bobcat, cmd.exe, ConEmu, cool-retro-term,
148
- Extraterm, Hyper, Konsole (requested: `KDE#507017`_), linux fbdev, mintty, PuTTY, QTerminal,
149
- rxvt-unicode, screen, securecrt, st, Tabby, Apple Terminal, Terminal.exe (planned:
151
+ - **No Support**: alacritty (refuses: `alacritty/vte#98`_), bobcat, cmd.exe,
152
+ Extraterm, Hyper, Konsole (requested: `KDE#507017`_), linux fbdev, mintty,
153
+ rxvt-unicode, screen, securecrt, st, Tabby, Terminal.exe (planned:
150
154
  `microsoft/terminal#17735`_), terminology, tmux (passthrough: `tmux/tmux#3755`_), libvterm, VS
151
155
  Code (xterm.js, proposal: `xtermjs/xterm.js#4107`_), weston-terminal, and zutty.
152
156
 
157
+ - **Non-Compliant**: ConEmu, cool-retro-term, Apple Terminal, PuTTY, QTerminal: When a terminal emulator
158
+ does not support XTGETTCAP, it **should** silently consume VT100 Mode DCS queries without answer.
159
+
160
+ However, some non-compliant terminals display XTGETTCAP query output, eg. ``+q544e+q524742+q636f6c6f7273+q626c696e6b+..``
161
+ visually: QTerminal, cool-retro-term, and qtermwidget (`fixed upstream <https://github.com/lxqt/qtermwidget/pull/644>`_),
162
+ PuTTY, ConEmu.exe, and Apple's Terminal.app all fail to parse DCS queries, displaying raw sequence output.
163
+
153
164
  Architecture
154
165
  ------------
155
166
 
@@ -161,6 +172,8 @@ Architecture
161
172
  - DEC Private Mode 2048 (In-Band Resize) to determine the window size
162
173
  - Or failing that, using Cursor Position Report sequence like done in XTerm's `resize.c
163
174
  <https://github.com/joejulian/xterm/blob/master/resize.c>`_
175
+ - DECRQSS_ (Request Setting Selection) to probe truecolor support when ``RGB`` is unavailable,
176
+ by setting and querying a 24-bit background color
164
177
 
165
178
  Details
166
179
  -------
@@ -201,6 +214,7 @@ values when they differ.
201
214
  .. _`agetty(8)`: https://linux.die.net/man/8/agetty
202
215
  .. _`alacritty/vte#98`: https://github.com/alacritty/vte/issues/98
203
216
  .. _contour: https://github.com/contour-terminal/contour
217
+ .. _DECRQSS: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Device-Control-functions:DCS-plus-q-Pt-ST.F95
204
218
  .. _foot: https://codeberg.org/dnkl/foot#xtgettcap
205
219
  .. _ghostty: https://mitchellh.com/writing/ghostty-devlog-004
206
220
  .. _`KDE#507017`: https://bugs.kde.org/show_bug.cgi?id=507017
@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
4
4
 
5
5
  [project]
6
6
  name = "ttyscan"
7
- version = '0.0.4'
7
+ version = '0.0.8'
8
8
  description = "Queries a terminal emulator for its type, size and capabilities"
9
9
  readme = "README.rst"
10
10
  requires-python = ">=3.6"
@@ -15,13 +15,16 @@ from ttyscan import (
15
15
  check_colorterm,
16
16
  check_lines_columns,
17
17
  check_term,
18
+ check_term_program,
18
19
  classify_caps,
20
+ decqss_query,
19
21
  escape_value,
20
22
  has_meaningful_caps,
21
23
  hex_decode,
22
24
  hex_encode,
23
25
  normalize_terminal_name,
24
26
  pack_short_le,
27
+ probe_truecolor,
25
28
  sanitize_term_name,
26
29
  shell_escape,
27
30
  terminfo_file_path,
@@ -30,6 +33,8 @@ from ttyscan import (
30
33
  unescape_terminfo,
31
34
  verbose,
32
35
  warn,
36
+ _parse_xtversion_text,
37
+ xtversion_query,
33
38
  )
34
39
  from ttyscan import write_terminfo as _write_terminfo
35
40
 
@@ -74,6 +79,61 @@ def _pty_run(args, env, response, timeout=5.0):
74
79
  return output.decode("utf-8", errors="replace"), status
75
80
 
76
81
 
82
+ def _pty_run_staggered(args, env, responses, timeout=5.0):
83
+ """Run a command in a PTY child, writing response chunks with delays.
84
+
85
+ ``responses`` is a list of ``(delay_sec, data)`` tuples. Each chunk
86
+ is written after its corresponding delay, allowing multiple
87
+ ``read_until`` rounds to consume separate response segments.
88
+ Returns ``(output_text, wait_status)``.
89
+ """
90
+ import fcntl
91
+ import select
92
+ import struct
93
+ import termios
94
+
95
+ pid, master_fd = os.forkpty()
96
+ if pid == 0:
97
+ os.execve(sys.executable, args, env)
98
+ os._exit(1)
99
+
100
+ winsize = struct.pack("HHHH", 31, 128, 0, 0)
101
+ fcntl.ioctl(master_fd, termios.TIOCSWINSZ, winsize)
102
+ attrs = termios.tcgetattr(master_fd)
103
+ attrs[3] = attrs[3] & ~termios.ECHO
104
+ termios.tcsetattr(master_fd, termios.TCSANOW, attrs)
105
+
106
+ output = b""
107
+ deadline = __import__("time").monotonic() + timeout
108
+ for delay, chunk in responses:
109
+ __import__("time").sleep(delay)
110
+ os.write(master_fd, chunk)
111
+ if __import__("time").monotonic() >= deadline:
112
+ break
113
+ ready, _, _ = select.select([master_fd], [], [], 0.3)
114
+ if ready:
115
+ try:
116
+ chunk = os.read(master_fd, 4096)
117
+ except OSError:
118
+ break
119
+ output += chunk
120
+
121
+ # drain remaining output
122
+ while __import__("time").monotonic() < deadline:
123
+ ready, _, _ = select.select([master_fd], [], [], 0.3)
124
+ if ready:
125
+ try:
126
+ chunk = os.read(master_fd, 4096)
127
+ except OSError:
128
+ break
129
+ if not chunk:
130
+ break
131
+ output += chunk
132
+
133
+ _, status = os.waitpid(pid, 0)
134
+ return output.decode("utf-8", errors="replace"), status
135
+
136
+
77
137
  @pytest.mark.parametrize("name,hexstr", [("TN", "544e"), ("RGB", "524742")])
78
138
  def test_hex_encode(name, hexstr):
79
139
  """Encode ASCII string to hex."""
@@ -293,6 +353,80 @@ def test_normalize_terminal_name(name, expected):
293
353
  assert normalize_terminal_name(name) == expected
294
354
 
295
355
 
356
+ @pytest.mark.parametrize("text,expected", [
357
+ ("kitty(0.24.2)", ("kitty", "0.24.2")),
358
+ ("XTerm(367)", ("XTerm", "367")),
359
+ ("tmux 3.2a", ("tmux", "3.2a")),
360
+ ("X.Org 7.7.0(370)", ("X.Org", "7.7.0(370)")),
361
+ ("foot", ("foot", "")),
362
+ ("", ("", "")),
363
+ ])
364
+ def test_parse_xtversion_text(text, expected):
365
+ """Parse XTVERSION response text into name and version."""
366
+ assert _parse_xtversion_text(text) == expected
367
+
368
+
369
+ @pytest.mark.parametrize("name,version,force,env,expected", [
370
+ ("kitty", "0.24.2", False, {},
371
+ ["export TERM_PROGRAM='kitty'", "export TERM_PROGRAM_VERSION='0.24.2'"]),
372
+ ("kitty", "0.24.2", False,
373
+ {"TERM_PROGRAM": "kitty", "TERM_PROGRAM_VERSION": "0.24.2"}, None),
374
+ ("kitty", "0.24.2", True,
375
+ {"TERM_PROGRAM": "kitty", "TERM_PROGRAM_VERSION": "0.24.2"},
376
+ ["export TERM_PROGRAM='kitty'", "export TERM_PROGRAM_VERSION='0.24.2'"]),
377
+ ("xterm", "", False, {},
378
+ ["export TERM_PROGRAM='xterm'"]),
379
+ ("X.Org", "7.7.0(370)", False, {},
380
+ ["export TERM_PROGRAM='X.Org'", "export TERM_PROGRAM_VERSION='7.7.0(370)'"]),
381
+ ])
382
+ def test_check_term_program(name, version, force, env, expected):
383
+ """Check TERM_PROGRAM/TERM_PROGRAM_VERSION export logic."""
384
+ with patch.dict(os.environ, env, clear=True):
385
+ assert check_term_program(name, version, force) == expected
386
+
387
+
388
+ @pytest.mark.parametrize("read_until_result,expected", [
389
+ ((None, ""), None),
390
+ ((None, "\x1bP>|kitty(0.24.2)\x1b\\"), None),
391
+ ((None, "\x1b[31;128R"), None),
392
+ ])
393
+ def test_xtversion_query_no_cpr(read_until_result, expected):
394
+ """xtversion_query returns None when CPR boundary not found."""
395
+ with patch('ttyscan.read_until', return_value=read_until_result):
396
+ assert xtversion_query(3, 4, 0.25) is expected
397
+
398
+
399
+ @pytest.mark.parametrize("data,expected_name,expected_version", [
400
+ ("\x1bP>|kitty(0.24.2)\x1b\\", "kitty", "0.24.2"),
401
+ ("\x1bP>|tmux 3.2a\x1b\\", "tmux", "3.2a"),
402
+ ("\x1bP>|foot\x1b\\", "foot", ""),
403
+ ])
404
+ def test_xtversion_query_parsed(data, expected_name, expected_version):
405
+ """xtversion_query extracts name/version from DCS response."""
406
+ import re as _re_mod
407
+ from ttyscan import _RE_CPR_BOUNDARY
408
+
409
+ full_buf = data + "\x1b[31;128R"
410
+ cpr_match = _re_mod.search(_RE_CPR_BOUNDARY, full_buf)
411
+ read_until_return = (cpr_match, full_buf)
412
+ with patch('ttyscan.read_until', return_value=read_until_return):
413
+ result = xtversion_query(3, 4, 0.25)
414
+ assert result == (expected_name, expected_version)
415
+
416
+
417
+ def test_xtversion_query_no_dcs():
418
+ """xtversion_query returns None when no DCS response found before CPR."""
419
+ import re as _re_mod
420
+ from ttyscan import _RE_CPR_BOUNDARY
421
+
422
+ full_buf = "\x1b[31;128R"
423
+ cpr_match = _re_mod.search(_RE_CPR_BOUNDARY, full_buf)
424
+ read_until_return = (cpr_match, full_buf)
425
+ with patch('ttyscan.read_until', return_value=read_until_return):
426
+ result = xtversion_query(3, 4, 0.25)
427
+ assert result is None
428
+
429
+
296
430
  @pytest.mark.parametrize("func,args,enabled,expected_in", [
297
431
  (warn, ("test message",), None, "ttyscan: test message"),
298
432
  (verbose, ("test message", True), True, "ttyscan: test message"),
@@ -350,6 +484,83 @@ def test_write_terminfo(tmp_path, term, str_caps, num_caps, bool_caps):
350
484
  assert fpath.stat().st_size > 0
351
485
 
352
486
 
487
+ @pytest.mark.parametrize("setting_id,read_until_result,expected", [
488
+ ("m",
489
+ (None, ""),
490
+ None),
491
+ ("m",
492
+ (None, "\x1bP1$r0m\x1b\\"),
493
+ None),
494
+ ("m",
495
+ (None, "\x1b[31;128R"),
496
+ None),
497
+ ])
498
+ def test_decqss_query_no_cpr(setting_id, read_until_result, expected):
499
+ """decqss_query returns None when CPR boundary not found."""
500
+ with patch('ttyscan.read_until', return_value=read_until_result):
501
+ assert decqss_query(3, 4, setting_id, 0.25) is expected
502
+
503
+
504
+ @pytest.mark.parametrize("setting_id,buf,expected", [
505
+ ("m",
506
+ "\x1bP1$r0m\x1b\\\x1b[31;128R",
507
+ "0"),
508
+ ("m",
509
+ "\x1bP1$r48:2:1:2:3m\x1b\\\x1b[31;128R",
510
+ "48:2:1:2:3"),
511
+ (" q",
512
+ "\x1bP1$r2 q\x1b\\\x1b[31;128R",
513
+ "2"),
514
+ ])
515
+ def test_decqss_query_valid(setting_id, buf, expected):
516
+ """decqss_query parses valid DECRQSS responses."""
517
+ import re as _re_mod
518
+ from ttyscan import _RE_CPR_BOUNDARY
519
+
520
+ cpr_match = _re_mod.search(_RE_CPR_BOUNDARY, buf)
521
+ with patch('ttyscan.read_until', return_value=(cpr_match, buf)):
522
+ assert decqss_query(3, 4, setting_id, 0.25) == expected
523
+
524
+
525
+ @pytest.mark.parametrize("buf", [
526
+ "\x1bP0$rm\x1b\\\x1b[31;128R",
527
+ "\x1b[31;128R",
528
+ ])
529
+ def test_decqss_query_invalid(buf):
530
+ """decqss_query returns None for Ps=0 or missing response."""
531
+ import re as _re_mod
532
+ from ttyscan import _RE_CPR_BOUNDARY
533
+
534
+ cpr_match = _re_mod.search(_RE_CPR_BOUNDARY, buf)
535
+ with patch('ttyscan.read_until', return_value=(cpr_match, buf)):
536
+ assert decqss_query(3, 4, 'm', 0.25) is None
537
+
538
+
539
+ @pytest.mark.parametrize("original,probed,expected,verbose_msg", [
540
+ ("0", "48:2:1:2:3", True, None),
541
+ ("0", "0", False, None),
542
+ ("0", "40", False, None),
543
+ (None, None, False, "DECRQSS not supported by this terminal"),
544
+ ])
545
+ def test_probe_truecolor(original, probed, expected, verbose_msg):
546
+ """probe_truecolor detects truecolor via DECRQSS SGR set/query."""
547
+ decrqss_responses = [original, probed]
548
+ with patch('ttyscan.decqss_query', side_effect=decrqss_responses), \
549
+ patch('ttyscan.write_all'), \
550
+ patch('ttyscan.verbose') as mock_verbose:
551
+ assert probe_truecolor(3, 4, 0.25, True) == expected
552
+ if verbose_msg:
553
+ mock_verbose.assert_called_with(verbose_msg, True)
554
+
555
+
556
+ def test_probe_truecolor_fails_on_second_query():
557
+ """probe_truecolor returns False when probe query fails."""
558
+ with patch('ttyscan.decqss_query', side_effect=["0", None]), \
559
+ patch('ttyscan.write_all'), \
560
+ patch('ttyscan.verbose'):
561
+ assert probe_truecolor(3, 4, 0.25, False) is False
562
+
563
+
353
564
  def test_main_help():
354
565
  """ttyscan --help prints usage and exits 0."""
355
566
  result = subprocess.run(
@@ -523,6 +734,7 @@ _XT_RESP = {
523
734
  "cols_80": b"\x1bP1+r636f6c73=3830\x1b\\",
524
735
  "lines_24": b"\x1bP1+r6c696e6573=3234\x1b\\",
525
736
  "rgb_8_8_8": b"\x1bP1+r524742=382f382f38\x1b\\",
737
+ "xtversion_kitty": b"\x1bP>|kitty(0.24.2)\x1b\\",
526
738
  }
527
739
  _CPR_31_128 = b"\x1b[31;128R"
528
740
  _CPR_5_10 = b"\x1b[5;10R"
@@ -531,6 +743,11 @@ _CPR_999_999 = b"\x1b[999;999R"
531
743
  _DECRPM_none = b"\x1b[?2048;1$y"
532
744
  _DECRPM_set = b"\x1b[?2048;2$y"
533
745
  _RESIZE_31_128 = b"\x1b[48;31;128;0;0t"
746
+ _DECRQSS_SGR_ORIGINAL = b"\x1bP1$r0m\x1b\\"
747
+ _DECRQSS_SGR_TRUECOLOR = b"\x1bP1$r48:2:1:2:3m\x1b\\"
748
+ _DECRQSS_SGR_PALETTE = b"\x1bP1$r40m\x1b\\"
749
+ _DECRQSS_SGR_INVALID = b"\x1bP0$r\x1b\\"
750
+ _XTVERSION_XTERM = b"\x1bP>|XTerm(367)\x1b\\"
534
751
 
535
752
 
536
753
  @pytest.mark.skipif(sys.platform == "win32", reason="pty requires unix")
@@ -623,3 +840,105 @@ def test_generate_exports_pty(flags, response, expected, not_expected, tmp_path)
623
840
  terminfo_file = terminfo_file_path(safe, terminfo_dir)
624
841
  assert terminfo_file.exists()
625
842
  assert terminfo_file.stat().st_size > 0
843
+
844
+
845
+ @pytest.mark.skipif(sys.platform == "win32", reason="pty requires unix")
846
+ @pytest.mark.parametrize("flags,responses,env_extra,expected,not_expected", [
847
+ # DECRQSS detects truecolor when neither COLORTERM nor XTGETTCAP RGB indicate it
848
+ ("-v",
849
+ [(0.0, _XT_RESP["tn_xterm"] + _CPR_31_128),
850
+ (0.1, _DECRQSS_SGR_ORIGINAL + _CPR_5_10),
851
+ (0.1, _DECRQSS_SGR_TRUECOLOR + _CPR_6_7),
852
+ (0.1, _DECRPM_none + _CPR_5_10),
853
+ (0.1, _CPR_999_999),
854
+ (0.1, _CPR_999_999)],
855
+ {"TERM_PROGRAM": "xterm"},
856
+ ["export COLORTERM=truecolor", "export TERM=xterm"],
857
+ ["export LINES=", "export COLUMNS=", "export TERMINFO=", "export TERMCAP="]),
858
+ # DECRQSS probe skipped when COLORTERM already truecolor
859
+ ("-v",
860
+ [(0.0, _XT_RESP["tn_xterm"] + _CPR_31_128),
861
+ (0.1, _DECRPM_none + _CPR_5_10),
862
+ (0.1, _CPR_999_999),
863
+ (0.1, _CPR_999_999)],
864
+ {"TERM_PROGRAM": "xterm", "COLORTERM": "truecolor"},
865
+ ["export TERM=xterm"],
866
+ ["export COLORTERM=truecolor"]),
867
+ # DECRQSS probe skipped when XTGETTCAP RGB=8/8/8
868
+ ("-v",
869
+ [(0.0, _XT_RESP["tn_xterm"] + _XT_RESP["rgb_8_8_8"] + _CPR_31_128),
870
+ (0.1, _DECRPM_none + _CPR_31_128),
871
+ (0.1, _CPR_999_999),
872
+ (0.1, _CPR_999_999)],
873
+ {"TERM_PROGRAM": "xterm"},
874
+ ["export COLORTERM=truecolor", "export TERM=xterm"],
875
+ ["export TERMINFO=", "export TERMCAP="]),
876
+ # -f forces DECRQSS probe even when COLORTERM already truecolor
877
+ ("-vf",
878
+ [(0.0, _XT_RESP["tn_xterm"] + _CPR_31_128),
879
+ (0.1, _XTVERSION_XTERM + _CPR_5_10),
880
+ (0.1, _DECRQSS_SGR_ORIGINAL + _CPR_6_7),
881
+ (0.1, _DECRQSS_SGR_TRUECOLOR + _CPR_5_10),
882
+ (0.1, _DECRPM_none + _CPR_6_7),
883
+ (0.1, _CPR_999_999),
884
+ (0.1, _CPR_999_999),
885
+ (0.1, _CPR_31_128)],
886
+ {"TERM_PROGRAM": "xterm", "COLORTERM": "truecolor"},
887
+ ["export COLORTERM=truecolor", "export TERM=xterm"],
888
+ []),
889
+ # DECRQSS unsupported: no probe response, no COLORTERM export
890
+ ("-v",
891
+ [(0.0, _XT_RESP["tn_xterm"] + _CPR_31_128),
892
+ (0.1, _DECRPM_none + _CPR_5_10),
893
+ (0.1, _CPR_999_999),
894
+ (0.1, _CPR_999_999)],
895
+ {"TERM_PROGRAM": "xterm"},
896
+ ["export TERM=xterm"],
897
+ ["export COLORTERM=truecolor"]),
898
+ # DECRQSS returns palette index (non-truecolor): no COLORTERM export
899
+ ("-v",
900
+ [(0.0, _XT_RESP["tn_xterm"] + _CPR_31_128),
901
+ (0.1, _DECRQSS_SGR_ORIGINAL + _CPR_5_10),
902
+ (0.1, _DECRQSS_SGR_PALETTE + _CPR_6_7),
903
+ (0.1, _DECRPM_none + _CPR_5_10),
904
+ (0.1, _CPR_999_999),
905
+ (0.1, _CPR_999_999)],
906
+ {"TERM_PROGRAM": "xterm"},
907
+ ["export TERM=xterm"],
908
+ ["export COLORTERM=truecolor"]),
909
+ # DECRQSS probe with XTGETTCAP not supported (empty init): COLORTERM only
910
+ ("-v",
911
+ [(0.0, _CPR_31_128),
912
+ (0.1, _DECRQSS_SGR_ORIGINAL + _CPR_5_10),
913
+ (0.1, _DECRQSS_SGR_TRUECOLOR + _CPR_6_7)],
914
+ {"TERM_PROGRAM": "xterm"},
915
+ ["export COLORTERM=truecolor"],
916
+ ["export TERM=", "export TERMINFO=", "export LINES=", "export COLUMNS="]),
917
+ ])
918
+ def test_decrqss_probe_pty(flags, responses, env_extra, expected,
919
+ not_expected, tmp_path):
920
+ """PTY integration: DECRQSS truecolor probe scenarios."""
921
+ env = {
922
+ **dict(os.environ),
923
+ "XDG_CONFIG_HOME": str(tmp_path),
924
+ "TTYSCAN_QUERY_TIMEOUT": "0.5",
925
+ }
926
+ env.pop("COLORTERM", None)
927
+ env["TERM"] = "dumb"
928
+ env.update(env_extra)
929
+
930
+ project_coverage = os.path.join(os.path.dirname(__file__), ".coverage")
931
+ env["COVERAGE_FILE"] = project_coverage
932
+
933
+ text, status = _pty_run_staggered(
934
+ [sys.executable, "-m", "coverage", "run", "--append",
935
+ "-m", "ttyscan"] + flags.split(),
936
+ env, responses)
937
+
938
+ assert os.WIFEXITED(status)
939
+ assert os.WEXITSTATUS(status) == 0
940
+
941
+ for s in expected:
942
+ assert s in text, f"expected {s!r} not found in output:\n{text}"
943
+ for s in not_expected:
944
+ assert s not in text, f"unexpected {s!r} found in output:\n{text}"
@@ -17,7 +17,7 @@ try:
17
17
  except ImportError as exc:
18
18
  sys.exit(f"ttyscan: unsupported platform (missing required module: {exc})")
19
19
 
20
- __version__ = "0.0.4"
20
+ __version__ = "0.0.8"
21
21
 
22
22
 
23
23
  def warn(msg):
@@ -40,6 +40,8 @@ except ValueError:
40
40
  f"is not a valid float, using default 0.2")
41
41
  _TTYSCAN_DRAIN_TIMEOUT = 0.2
42
42
 
43
+ _READ_BUFFER = b''
44
+
43
45
  _CANONICAL_BOOL_CAPS = [
44
46
  "bw", "am", "xsb", "xhp", "xenl", "eo", "gn", "hc", "km", "hs",
45
47
  "in", "da", "db", "mir", "msgr", "os", "eslok", "xt", "hz", "ul",
@@ -120,12 +122,16 @@ _BOOL_SET = frozenset(_CANONICAL_BOOL_CAPS)
120
122
  _NUM_SET = frozenset(_CANONICAL_NUM_CAPS)
121
123
  _STR_SET = frozenset(_CANONICAL_STR_CAPS)
122
124
 
125
+ # VTE-based terminals (GNOME Terminal, et al.) send malformed ``\\x1bP0+r\\x1b\\\\``
126
+ # (empty hex name) for unsupported capabilities, so zero-or-more hex digits.
123
127
  _RE_XTGETTCAP_RESPONSE = re.compile(
124
- r'\x1bP([01])\+r([0-9a-fA-F]+)(?:=([0-9a-fA-F]*))?\x1b\\')
128
+ r'\x1bP([01])\+r([0-9a-fA-F]*)(?:=([0-9a-fA-F]*))?\x1b\\')
129
+ _RE_XTVERSION_RESPONSE = re.compile(r'\x1bP>\|(.+?)\x1b\\')
125
130
  _RE_CPR = re.compile(r'\x1b\[(\d+);(\d+)R')
126
131
  _RE_CPR_BOUNDARY = re.compile(r'\x1b\[[0-9]+;[0-9]+R')
127
132
  _RE_DECRPM = re.compile(r'\x1b\[\?(\d+);([0-4])\$y')
128
133
  _RE_RESIZE = re.compile(r'\x1b\[48;(\d+);(\d+);(\d+);(\d+)t')
134
+ _RE_DECRQSS_RESPONSE = re.compile(r'\x1bP([01])\$r([^\x1b]*)\x1b\\')
129
135
 
130
136
  _TERMINFO_MAGIC = 0o432
131
137
  _TERMINFO_MAGIC2 = 0o1036
@@ -299,7 +305,11 @@ def write_all(fd, data):
299
305
 
300
306
 
301
307
  def read_available(r_fd, timeout):
308
+ global _READ_BUFFER
302
309
  buf = bytearray()
310
+ if _READ_BUFFER:
311
+ buf.extend(_READ_BUFFER)
312
+ _READ_BUFFER = b''
303
313
  stime = time.monotonic()
304
314
  max_size = 131072
305
315
  while True:
@@ -350,6 +360,7 @@ def read_until(r_fd, w_fd, queries, pattern, timeout):
350
360
 
351
361
 
352
362
  def xtgettcap_query(r_fd, w_fd, caps, timeout):
363
+ global _READ_BUFFER
353
364
  if not caps:
354
365
  return {}
355
366
  queries = [f'\x1bP+q{hex_encode(c)}\x1b\\' for c in caps]
@@ -358,13 +369,18 @@ def xtgettcap_query(r_fd, w_fd, caps, timeout):
358
369
  return {}
359
370
  drain_deadline = time.monotonic() + _TTYSCAN_DRAIN_TIMEOUT
360
371
  while time.monotonic() < drain_deadline:
361
- raw = read_available(r_fd, 0.05)
362
- if not raw:
372
+ remaining = drain_deadline - time.monotonic()
373
+ if remaining <= 0:
363
374
  break
375
+ raw = read_available(r_fd, min(remaining, 0.05))
376
+ if not raw:
377
+ continue
364
378
  decoded = raw.decode('latin-1', errors='replace')
365
- if not _RE_XTGETTCAP_RESPONSE.search(decoded):
379
+ if _RE_XTGETTCAP_RESPONSE.search(decoded):
380
+ data += decoded
381
+ else:
382
+ _READ_BUFFER = raw + _READ_BUFFER
366
383
  break
367
- data += decoded
368
384
  data = data[:match.start()] + data[match.end():]
369
385
  capabilities = {}
370
386
  for m in _RE_XTGETTCAP_RESPONSE.finditer(data):
@@ -379,6 +395,29 @@ def xtgettcap_query(r_fd, w_fd, caps, timeout):
379
395
  return capabilities
380
396
 
381
397
 
398
+ def _parse_xtversion_text(text):
399
+ if ' ' in text:
400
+ name, version = text.split(' ', 1)
401
+ return name, version
402
+ if '(' in text:
403
+ parts = text.split('(', 1)
404
+ name = parts[0]
405
+ version = parts[1].rstrip(')')
406
+ return name, version
407
+ return text, ''
408
+
409
+
410
+ def xtversion_query(r_fd, w_fd, timeout):
411
+ match, data = read_until(r_fd, w_fd, ['\x1b[>q'],
412
+ _RE_CPR_BOUNDARY.pattern, timeout)
413
+ if match is None:
414
+ return None
415
+ data = data[:match.start()] + data[match.end():]
416
+ for m in _RE_XTVERSION_RESPONSE.finditer(data):
417
+ return _parse_xtversion_text(m.group(1))
418
+ return None
419
+
420
+
382
421
  def decrqm_query(r_fd, w_fd, mode, timeout):
383
422
  result = read_until(r_fd, w_fd,
384
423
  [f'\x1b[?{mode}$p'],
@@ -393,6 +432,63 @@ def decrqm_query(r_fd, w_fd, mode, timeout):
393
432
  return None
394
433
 
395
434
 
435
+ def decqss_query(r_fd, w_fd, setting_id, timeout):
436
+ """Query terminal state via DECRQSS.
437
+
438
+ Sends ``DCS $ q <setting_id> ST`` with a CPR boundary fence. Returns the
439
+ decoded parameter string on success, with the echoed setting identifier
440
+ stripped. Returns ``None`` when the terminal does not support DECRQSS or
441
+ the setting is invalid.
442
+ """
443
+ match, data = read_until(r_fd, w_fd,
444
+ [f'\x1bP$q{setting_id}\x1b\\'],
445
+ _RE_CPR_BOUNDARY.pattern, timeout)
446
+ if match is None:
447
+ return None
448
+ data = data[:match.start()] + data[match.end():]
449
+ for m in _RE_DECRQSS_RESPONSE.finditer(data):
450
+ if m.group(1) == '1':
451
+ pt = m.group(2)
452
+ if pt.endswith(setting_id):
453
+ return pt[:-len(setting_id)]
454
+ return pt
455
+ return None
456
+
457
+
458
+ def probe_truecolor(r_fd, w_fd, timeout, verbose_enabled):
459
+ """Detect truecolor support via DECRQSS SGR set/query/restore.
460
+
461
+ Queries the current SGR to capture the original rendering state, sets the
462
+ background to a known truecolor value using colon-delimited RGB, then
463
+ queries SGR again to verify the color was accepted. Restores the original
464
+ SGR afterward. Returns ``True`` if the probed background color appears in
465
+ the DECRQSS response, indicating 24-bit color support.
466
+ """
467
+ original = decqss_query(r_fd, w_fd, 'm', timeout)
468
+ if original is None:
469
+ verbose("DECRQSS not supported by this terminal", verbose_enabled)
470
+ return False
471
+
472
+ probe_bg = '48:2:1:2:3'
473
+ write_all(w_fd, f'\x1b[{probe_bg}m')
474
+ probed = decqss_query(r_fd, w_fd, 'm', timeout)
475
+ write_all(w_fd, f'\x1b[{original}m')
476
+
477
+ if probed is None:
478
+ verbose("DECRQSS probe query failed", verbose_enabled)
479
+ return False
480
+ # Terminals may normalize the response, e.g. inserting an empty
481
+ # color-space-identifier or using semicolon delimiters:
482
+ # "48:2::1:2:3" or "48;2;1;2;3" vs our probe "48:2:1:2:3".
483
+ # Check for the RGB triple "1 2 3" appearing after a "48 2" prefix
484
+ # with any combination of colon/semicolon delimiters.
485
+ result = bool(re.search(r'48[:;]2[:;]*1[:;]2[:;]3', probed))
486
+ if not result:
487
+ verbose(f"DECRQSS truecolor probe: color not accepted: {probed!r}",
488
+ verbose_enabled)
489
+ return result
490
+
491
+
396
492
  def detect_size(r_fd, w_fd, verbose_enabled):
397
493
  decrpm = decrqm_query(r_fd, w_fd, 2048, 0.25)
398
494
  has_inband = decrpm is not None and decrpm == 2
@@ -654,6 +750,17 @@ def check_term(caps, force):
654
750
  return None
655
751
 
656
752
 
753
+ def check_term_program(name, version, force):
754
+ exports = []
755
+ env_name = os.environ.get("TERM_PROGRAM", "")
756
+ if force or env_name != name:
757
+ exports.append(f"export TERM_PROGRAM={shell_escape(name)}")
758
+ env_version = os.environ.get("TERM_PROGRAM_VERSION", "")
759
+ if force or env_version != version:
760
+ exports.append(f"export TERM_PROGRAM_VERSION={shell_escape(version)}")
761
+ return exports or None
762
+
763
+
657
764
  def check_lines_columns(rows, cols, winsize, force):
658
765
  term_cols, term_rows = winsize
659
766
  env_lines = os.environ.get("LINES")
@@ -671,8 +778,6 @@ def check_lines_columns(rows, cols, winsize, force):
671
778
 
672
779
 
673
780
  def generate_exports(verbose_enabled=False, force=False, termcap=False):
674
- verbose("probing terminal via XTGETTCAP ...", verbose_enabled)
675
-
676
781
  r_fd, w_fd = open_tty()
677
782
  if r_fd is None or w_fd is None:
678
783
  verbose("no terminal available", verbose_enabled)
@@ -684,27 +789,42 @@ def generate_exports(verbose_enabled=False, force=False, termcap=False):
684
789
 
685
790
  init_caps = xtgettcap_query(r_fd, w_fd, _INIT_XTGETTCAP_CAPS,
686
791
  timeout=_TTYSCAN_QUERY_TIMEOUT)
687
- if not init_caps:
688
- verbose("XTGETTCAP not supported by this terminal", verbose_enabled)
689
- return []
690
792
 
691
- tn_raw = init_caps.get("TN")
692
- if not tn_raw:
693
- verbose("no TN (terminal name) capability, cannot export further",
694
- verbose_enabled)
695
- return []
793
+ exports = []
696
794
 
697
- tn = normalize_terminal_name(tn_raw)
795
+ xtversion = None
796
+ if force or os.environ.get("TERM_PROGRAM") is None:
797
+ xtversion = xtversion_query(r_fd, w_fd, timeout=_TTYSCAN_QUERY_TIMEOUT)
798
+ if xtversion:
799
+ name, version = xtversion
800
+ verbose(f"XTVERSION: {name} {version}", verbose_enabled)
801
+ tp_export = check_term_program(name, version, force)
802
+ if tp_export:
803
+ exports.extend(tp_export)
804
+ else:
805
+ verbose("XTVERSION not supported by this terminal", verbose_enabled)
806
+ else:
807
+ verbose("skipping XTVERSION (TERM_PROGRAM already set)", verbose_enabled)
698
808
 
699
- exports = []
809
+ colorterm = os.environ.get("COLORTERM", "")
810
+ has_env_tc = colorterm in ("truecolor", "24bit")
811
+ rgb = init_caps.get("RGB", "") if init_caps else ""
812
+ has_rgb_tc = False
813
+ if rgb:
814
+ try:
815
+ has_rgb_tc = int(rgb.split("/", 1)[0]) == 8
816
+ except ValueError:
817
+ pass
700
818
 
701
- ct_export = check_colorterm(init_caps, force)
702
- if ct_export:
703
- exports.append(ct_export)
819
+ decrqss_tc = False
820
+ if force or (not has_env_tc and not has_rgb_tc):
821
+ if probe_truecolor(r_fd, w_fd, _TTYSCAN_QUERY_TIMEOUT,
822
+ verbose_enabled):
823
+ verbose("truecolor confirmed via DECRQSS", verbose_enabled)
824
+ decrqss_tc = True
704
825
 
705
- term_export = check_term(init_caps, force)
706
- if term_export:
707
- exports.append(term_export)
826
+ if decrqss_tc:
827
+ exports.append("export COLORTERM=truecolor")
708
828
 
709
829
  size = detect_size(r_fd, w_fd, verbose_enabled)
710
830
  if size:
@@ -724,7 +844,36 @@ def generate_exports(verbose_enabled=False, force=False, termcap=False):
724
844
  if lc:
725
845
  exports.extend(lc)
726
846
 
727
- if not force and not termcap and has_terminfo(tn):
847
+ if not init_caps:
848
+ verbose("XTGETTCAP not supported by this terminal", verbose_enabled)
849
+ return exports
850
+
851
+ tn_raw = init_caps.get("TN")
852
+ if not tn_raw:
853
+ verbose("no TN (terminal name) capability, cannot export further",
854
+ verbose_enabled)
855
+ return exports
856
+
857
+ tn = normalize_terminal_name(tn_raw)
858
+
859
+ if not decrqss_tc:
860
+ ct_export = check_colorterm(init_caps, force)
861
+ if ct_export:
862
+ exports.append(ct_export)
863
+
864
+ term_export = check_term(init_caps, force)
865
+ if term_export:
866
+ exports.append(term_export)
867
+
868
+ if not force and not termcap and (
869
+ has_terminfo(tn)
870
+ or terminfo_installed_at(sanitize_term_name(tn), ttyscan_terminfo_dir())
871
+ ):
872
+ if not has_terminfo(tn):
873
+ terminfo_value = str(ttyscan_terminfo_dir())
874
+ current_terminfo = os.environ.get("TERMINFO")
875
+ if force or current_terminfo != terminfo_value:
876
+ exports.append(f"export TERMINFO={terminfo_value}")
728
877
  verbose(f"XTGETTCAP supported, terminal: {tn}", verbose_enabled)
729
878
  verbose("terminfo already available in system database", verbose_enabled)
730
879
  return exports
@@ -762,16 +911,21 @@ def generate_exports(verbose_enabled=False, force=False, termcap=False):
762
911
  terminfo_dir = ttyscan_terminfo_dir()
763
912
  safe_term = sanitize_term_name(tn)
764
913
 
765
- if not has_terminfo(tn) or force:
914
+ if (not has_terminfo(tn)
915
+ and not terminfo_installed_at(safe_term, terminfo_dir)) or force:
766
916
  write_terminfo(tn, str_caps, num_caps, bool_caps, terminfo_dir)
767
917
  verbose(f"writing {terminfo_file_path(safe_term, terminfo_dir)}",
768
918
  verbose_enabled)
919
+ elif has_terminfo(tn):
920
+ verbose("terminfo already available in system database", verbose_enabled)
921
+ elif terminfo_installed_at(safe_term, terminfo_dir):
922
+ verbose(f"terminfo exists at {terminfo_file_path(safe_term, terminfo_dir)}",
923
+ verbose_enabled)
924
+
925
+ if force or not has_terminfo(tn):
769
926
  terminfo_value = str(terminfo_dir)
770
- current_terminfo = os.environ.get("TERMINFO")
771
- if force or current_terminfo != terminfo_value:
927
+ if force or os.environ.get("TERMINFO") != terminfo_value:
772
928
  exports.append(f"export TERMINFO={terminfo_value}")
773
- else:
774
- verbose("terminfo already available in system database", verbose_enabled)
775
929
 
776
930
  if termcap:
777
931
  entry = build_termcap_entry(tn, str_caps, num_caps, bool_caps)
@@ -816,6 +970,10 @@ def main(argv=None):
816
970
  "-t", "--termcap", action="store_true",
817
971
  help="Also export TERMCAP value",
818
972
  )
973
+ parser.add_argument(
974
+ "--version", action="version",
975
+ version=f"ttyscan {__version__}",
976
+ )
819
977
  args = parser.parse_args(argv)
820
978
 
821
979
  exports = generate_exports(
File without changes
File without changes