Debian Codegraph @

Lib/_pyrepl/terminfo.py

raw
1 """Pure Python curses-like terminal capability queries."""
2
3 from dataclasses import dataclass, field
4 import errno
5 import os
6 from pathlib import Path
7 import re
8 import struct
9
10
11 # Terminfo constants
12 MAGIC16 = 0o432 # Magic number for 16-bit terminfo format
13 MAGIC32 = 0o1036 # Magic number for 32-bit terminfo format
14
15 # Special values for absent/cancelled capabilities
16 ABSENT_BOOLEAN = -1
17 ABSENT_NUMERIC = -1
18 CANCELLED_NUMERIC = -2
19 ABSENT_STRING = None
20 CANCELLED_STRING = None
21
22
23 # Standard string capability names from ncurses Caps file
24 # This matches the order used by ncurses when compiling terminfo
25 # fmt: off
26 _STRING_NAMES: tuple[str, ...] = (
27 "cbt", "bel", "cr", "csr", "tbc", "clear", "el", "ed", "hpa", "cmdch",
28 "cup", "cud1", "home", "civis", "cub1", "mrcup", "cnorm", "cuf1", "ll",
29 "cuu1", "cvvis", "dch1", "dl1", "dsl", "hd", "smacs", "blink", "bold",
30 "smcup", "smdc", "dim", "smir", "invis", "prot", "rev", "smso", "smul",
31 "ech", "rmacs", "sgr0", "rmcup", "rmdc", "rmir", "rmso", "rmul", "flash",
32 "ff", "fsl", "is1", "is2", "is3", "if", "ich1", "il1", "ip", "kbs", "ktbc",
33 "kclr", "kctab", "kdch1", "kdl1", "kcud1", "krmir", "kel", "ked", "kf0",
34 "kf1", "kf10", "kf2", "kf3", "kf4", "kf5", "kf6", "kf7", "kf8", "kf9",
35 "khome", "kich1", "kil1", "kcub1", "kll", "knp", "kpp", "kcuf1", "kind",
36 "kri", "khts", "kcuu1", "rmkx", "smkx", "lf0", "lf1", "lf10", "lf2", "lf3",
37 "lf4", "lf5", "lf6", "lf7", "lf8", "lf9", "rmm", "smm", "nel", "pad", "dch",
38 "dl", "cud", "ich", "indn", "il", "cub", "cuf", "rin", "cuu", "pfkey",
39 "pfloc", "pfx", "mc0", "mc4", "mc5", "rep", "rs1", "rs2", "rs3", "rf", "rc",
40 "vpa", "sc", "ind", "ri", "sgr", "hts", "wind", "ht", "tsl", "uc", "hu",
41 "iprog", "ka1", "ka3", "kb2", "kc1", "kc3", "mc5p", "rmp", "acsc", "pln",
42 "kcbt", "smxon", "rmxon", "smam", "rmam", "xonc", "xoffc", "enacs", "smln",
43 "rmln", "kbeg", "kcan", "kclo", "kcmd", "kcpy", "kcrt", "kend", "kent",
44 "kext", "kfnd", "khlp", "kmrk", "kmsg", "kmov", "knxt", "kopn", "kopt",
45 "kprv", "kprt", "krdo", "kref", "krfr", "krpl", "krst", "kres", "ksav",
46 "kspd", "kund", "kBEG", "kCAN", "kCMD", "kCPY", "kCRT", "kDC", "kDL",
47 "kslt", "kEND", "kEOL", "kEXT", "kFND", "kHLP", "kHOM", "kIC", "kLFT",
48 "kMSG", "kMOV", "kNXT", "kOPT", "kPRV", "kPRT", "kRDO", "kRPL", "kRIT",
49 "kRES", "kSAV", "kSPD", "kUND", "rfi", "kf11", "kf12", "kf13", "kf14",
50 "kf15", "kf16", "kf17", "kf18", "kf19", "kf20", "kf21", "kf22", "kf23",
51 "kf24", "kf25", "kf26", "kf27", "kf28", "kf29", "kf30", "kf31", "kf32",
52 "kf33", "kf34", "kf35", "kf36", "kf37", "kf38", "kf39", "kf40", "kf41",
53 "kf42", "kf43", "kf44", "kf45", "kf46", "kf47", "kf48", "kf49", "kf50",
54 "kf51", "kf52", "kf53", "kf54", "kf55", "kf56", "kf57", "kf58", "kf59",
55 "kf60", "kf61", "kf62", "kf63", "el1", "mgc", "smgl", "smgr", "fln", "sclk",
56 "dclk", "rmclk", "cwin", "wingo", "hup","dial", "qdial", "tone", "pulse",
57 "hook", "pause", "wait", "u0", "u1", "u2", "u3", "u4", "u5", "u6", "u7",
58 "u8", "u9", "op", "oc", "initc", "initp", "scp", "setf", "setb", "cpi",
59 "lpi", "chr", "cvr", "defc", "swidm", "sdrfq", "sitm", "slm", "smicm",
60 "snlq", "snrmq", "sshm", "ssubm", "ssupm", "sum", "rwidm", "ritm", "rlm",
61 "rmicm", "rshm", "rsubm", "rsupm", "rum", "mhpa", "mcud1", "mcub1", "mcuf1",
62 "mvpa", "mcuu1", "porder", "mcud", "mcub", "mcuf", "mcuu", "scs", "smgb",
63 "smgbp", "smglp", "smgrp", "smgt", "smgtp", "sbim", "scsd", "rbim", "rcsd",
64 "subcs", "supcs", "docr", "zerom", "csnm", "kmous", "minfo", "reqmp",
65 "getm", "setaf", "setab", "pfxl", "devt", "csin", "s0ds", "s1ds", "s2ds",
66 "s3ds", "smglr", "smgtb", "birep", "binel", "bicr", "colornm", "defbi",
67 "endbi", "setcolor", "slines", "dispc", "smpch", "rmpch", "smsc", "rmsc",
68 "pctrm", "scesc", "scesa", "ehhlm", "elhlm", "elohlm", "erhlm", "ethlm",
69 "evhlm", "sgr1", "slength", "OTi2", "OTrs", "OTnl", "OTbc", "OTko", "OTma",
70 "OTG2", "OTG3", "OTG1", "OTG4", "OTGR", "OTGL", "OTGU", "OTGD", "OTGH",
71 "OTGV", "OTGC","meml", "memu", "box1"
72 )
73 # fmt: on
74
75
76 def _get_terminfo_dirs() -> list[Path]:
77 """Get list of directories to search for terminfo files.
78
79 Based on ncurses behavior in:
80 - ncurses/tinfo/db_iterator.c:_nc_next_db()
81 - ncurses/tinfo/read_entry.c:_nc_read_entry()
82 """
83 dirs = []
84
85 terminfo = os.environ.get("TERMINFO")
86 if terminfo:
87 dirs.append(terminfo)
88
89 try:
90 home = Path.home()
91 dirs.append(str(home / ".terminfo"))
92 except RuntimeError:
93 pass
94
95 # Check TERMINFO_DIRS
96 terminfo_dirs = os.environ.get("TERMINFO_DIRS", "")
97 if terminfo_dirs:
98 for d in terminfo_dirs.split(":"):
99 if d:
100 dirs.append(d)
101
102 dirs.extend(
103 [
104 "/etc/terminfo",
105 "/lib/terminfo",
106 "/usr/lib/terminfo",
107 "/usr/share/terminfo",
108 "/usr/share/lib/terminfo",
109 "/usr/share/misc/terminfo",
110 "/usr/local/lib/terminfo",
111 "/usr/local/share/terminfo",
112 ]
113 )
114
115 return [Path(d) for d in dirs if Path(d).is_dir()]
116
117
118 def _validate_terminal_name_or_raise(terminal_name: str) -> None:
119 if not isinstance(terminal_name, str):
120 raise TypeError("`terminal_name` must be a string")
121
122 if not terminal_name:
123 raise ValueError("`terminal_name` cannot be empty")
124
125 if "\x00" in terminal_name:
126 raise ValueError("NUL character found in `terminal_name`")
127
128 t = Path(terminal_name)
129 if len(t.parts) > 1:
130 raise ValueError("`terminal_name` cannot contain path separators")
131
132
133 def _read_terminfo_file(terminal_name: str) -> bytes:
134 """Find and read terminfo file for given terminal name.
135
136 Terminfo files are stored in directories using the first character
137 of the terminal name as a subdirectory.
138 """
139 _validate_terminal_name_or_raise(terminal_name)
140 first_char = terminal_name[0].lower()
141 filename = terminal_name
142
143 for directory in _get_terminfo_dirs():
144 path = directory / first_char / filename
145 if path.is_file():
146 return path.read_bytes()
147
148 # Try with hex encoding of first char (for special chars)
149 hex_dir = "%02x" % ord(first_char)
150 path = directory / hex_dir / filename
151 if path.is_file():
152 return path.read_bytes()
153
154 raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), filename)
155
156
157 # Hard-coded terminal capabilities for common terminals
158 # This is a minimal subset needed by PyREPL
159 _TERMINAL_CAPABILITIES = {
160 # ANSI/xterm-compatible terminals
161 "ansi": {
162 # Bell
163 "bel": b"\x07",
164 # Cursor movement
165 "cub": b"\x1b[%p1%dD", # Move cursor left N columns
166 "cud": b"\x1b[%p1%dB", # Move cursor down N rows
167 "cuf": b"\x1b[%p1%dC", # Move cursor right N columns
168 "cuu": b"\x1b[%p1%dA", # Move cursor up N rows
169 "cub1": b"\x08", # Move cursor left 1 column
170 "cud1": b"\n", # Move cursor down 1 row
171 "cuf1": b"\x1b[C", # Move cursor right 1 column
172 "cuu1": b"\x1b[A", # Move cursor up 1 row
173 "cup": b"\x1b[%i%p1%d;%p2%dH", # Move cursor to row, column
174 "hpa": b"\x1b[%i%p1%dG", # Move cursor to column
175 # Clear operations
176 "clear": b"\x1b[H\x1b[2J", # Clear screen and home cursor
177 "el": b"\x1b[K", # Clear to end of line
178 # Insert/delete
179 "dch": b"\x1b[%p1%dP", # Delete N characters
180 "dch1": b"\x1b[P", # Delete 1 character
181 "ich": b"\x1b[%p1%d@", # Insert N characters
182 "ich1": b"", # Insert 1 character
183 # Cursor visibility
184 "civis": b"\x1b[?25l", # Make cursor invisible
185 "cnorm": b"\x1b[?12l\x1b[?25h", # Make cursor normal (visible)
186 # Scrolling
187 "ind": b"\n", # Scroll up one line
188 "ri": b"\x1bM", # Scroll down one line
189 # Keypad mode
190 "smkx": b"\x1b[?1h\x1b=", # Enable keypad mode
191 "rmkx": b"\x1b[?1l\x1b>", # Disable keypad mode
192 # Padding (not used in modern terminals)
193 "pad": b"",
194 # Function keys and special keys
195 "kdch1": b"\x1b[3~", # Delete key
196 "kcud1": b"\x1bOB", # Down arrow
197 "kend": b"\x1bOF", # End key
198 "kent": b"\x1bOM", # Enter key
199 "khome": b"\x1bOH", # Home key
200 "kich1": b"\x1b[2~", # Insert key
201 "kcub1": b"\x1bOD", # Left arrow
202 "knp": b"\x1b[6~", # Page down
203 "kpp": b"\x1b[5~", # Page up
204 "kcuf1": b"\x1bOC", # Right arrow
205 "kcuu1": b"\x1bOA", # Up arrow
206 # Function keys F1-F20
207 "kf1": b"\x1bOP",
208 "kf2": b"\x1bOQ",
209 "kf3": b"\x1bOR",
210 "kf4": b"\x1bOS",
211 "kf5": b"\x1b[15~",
212 "kf6": b"\x1b[17~",
213 "kf7": b"\x1b[18~",
214 "kf8": b"\x1b[19~",
215 "kf9": b"\x1b[20~",
216 "kf10": b"\x1b[21~",
217 "kf11": b"\x1b[23~",
218 "kf12": b"\x1b[24~",
219 "kf13": b"\x1b[1;2P",
220 "kf14": b"\x1b[1;2Q",
221 "kf15": b"\x1b[1;2R",
222 "kf16": b"\x1b[1;2S",
223 "kf17": b"\x1b[15;2~",
224 "kf18": b"\x1b[17;2~",
225 "kf19": b"\x1b[18;2~",
226 "kf20": b"\x1b[19;2~",
227 },
228 # Dumb terminal - minimal capabilities
229 "dumb": {
230 "bel": b"\x07", # Bell
231 "cud1": b"\n", # Move down 1 row (newline)
232 "ind": b"\n", # Scroll up one line (newline)
233 },
234 # Linux console
235 "linux": {
236 # Bell
237 "bel": b"\x07",
238 # Cursor movement
239 "cub": b"\x1b[%p1%dD", # Move cursor left N columns
240 "cud": b"\x1b[%p1%dB", # Move cursor down N rows
241 "cuf": b"\x1b[%p1%dC", # Move cursor right N columns
242 "cuu": b"\x1b[%p1%dA", # Move cursor up N rows
243 "cub1": b"\x08", # Move cursor left 1 column (backspace)
244 "cud1": b"\n", # Move cursor down 1 row (newline)
245 "cuf1": b"\x1b[C", # Move cursor right 1 column
246 "cuu1": b"\x1b[A", # Move cursor up 1 row
247 "cup": b"\x1b[%i%p1%d;%p2%dH", # Move cursor to row, column
248 "hpa": b"\x1b[%i%p1%dG", # Move cursor to column
249 # Clear operations
250 "clear": b"\x1b[H\x1b[J", # Clear screen and home cursor (different from ansi!)
251 "el": b"\x1b[K", # Clear to end of line
252 # Insert/delete
253 "dch": b"\x1b[%p1%dP", # Delete N characters
254 "dch1": b"\x1b[P", # Delete 1 character
255 "ich": b"\x1b[%p1%d@", # Insert N characters
256 "ich1": b"\x1b[@", # Insert 1 character
257 # Cursor visibility
258 "civis": b"\x1b[?25l\x1b[?1c", # Make cursor invisible
259 "cnorm": b"\x1b[?25h\x1b[?0c", # Make cursor normal
260 # Scrolling
261 "ind": b"\n", # Scroll up one line
262 "ri": b"\x1bM", # Scroll down one line
263 # Keypad mode
264 "smkx": b"\x1b[?1h\x1b=", # Enable keypad mode
265 "rmkx": b"\x1b[?1l\x1b>", # Disable keypad mode
266 # Function keys and special keys
267 "kdch1": b"\x1b[3~", # Delete key
268 "kcud1": b"\x1b[B", # Down arrow
269 "kend": b"\x1b[4~", # End key (different from ansi!)
270 "khome": b"\x1b[1~", # Home key (different from ansi!)
271 "kich1": b"\x1b[2~", # Insert key
272 "kcub1": b"\x1b[D", # Left arrow
273 "knp": b"\x1b[6~", # Page down
274 "kpp": b"\x1b[5~", # Page up
275 "kcuf1": b"\x1b[C", # Right arrow
276 "kcuu1": b"\x1b[A", # Up arrow
277 # Function keys
278 "kf1": b"\x1b[[A",
279 "kf2": b"\x1b[[B",
280 "kf3": b"\x1b[[C",
281 "kf4": b"\x1b[[D",
282 "kf5": b"\x1b[[E",
283 "kf6": b"\x1b[17~",
284 "kf7": b"\x1b[18~",
285 "kf8": b"\x1b[19~",
286 "kf9": b"\x1b[20~",
287 "kf10": b"\x1b[21~",
288 "kf11": b"\x1b[23~",
289 "kf12": b"\x1b[24~",
290 "kf13": b"\x1b[25~",
291 "kf14": b"\x1b[26~",
292 "kf15": b"\x1b[28~",
293 "kf16": b"\x1b[29~",
294 "kf17": b"\x1b[31~",
295 "kf18": b"\x1b[32~",
296 "kf19": b"\x1b[33~",
297 "kf20": b"\x1b[34~",
298 },
299 }
300
301 # Map common TERM values to capability sets
302 _TERM_ALIASES = {
303 "xterm": "ansi",
304 "xterm-color": "ansi",
305 "xterm-256color": "ansi",
306 "screen": "ansi",
307 "screen-256color": "ansi",
308 "tmux": "ansi",
309 "tmux-256color": "ansi",
310 "vt100": "ansi",
311 "vt220": "ansi",
312 "rxvt": "ansi",
313 "rxvt-unicode": "ansi",
314 "rxvt-unicode-256color": "ansi",
315 "unknown": "dumb",
316 }
317
318
319 @dataclass
320 class TermInfo:
321 terminal_name: str | bytes | None
322 fallback: bool = True
323
324 _capabilities: dict[str, bytes] = field(default_factory=dict)
325
326 def __post_init__(self) -> None:
327 """Initialize terminal capabilities for the given terminal type.
328
329 Based on ncurses implementation in:
330 - ncurses/tinfo/lib_setup.c:setupterm() and _nc_setupterm()
331 - ncurses/tinfo/lib_setup.c:TINFO_SETUP_TERM()
332
333 This version first attempts to read terminfo database files like ncurses,
334 then, if `fallback` is True, falls back to hardcoded capabilities for
335 common terminal types.
336 """
337 # If termstr is None or empty, try to get from environment
338 if not self.terminal_name:
339 self.terminal_name = os.environ.get("TERM") or "ANSI"
340
341 if isinstance(self.terminal_name, bytes):
342 self.terminal_name = self.terminal_name.decode("ascii")
343
344 try:
345 self._parse_terminfo_file(self.terminal_name)
346 except (OSError, ValueError):
347 if not self.fallback:
348 raise
349
350 term_type = _TERM_ALIASES.get(
351 self.terminal_name, self.terminal_name
352 )
353 if term_type not in _TERMINAL_CAPABILITIES:
354 term_type = "dumb"
355 self._capabilities = _TERMINAL_CAPABILITIES[term_type].copy()
356
357 def _parse_terminfo_file(self, terminal_name: str) -> None:
358 """Parse a terminfo file.
359
360 Populate the _capabilities dict for easy retrieval
361
362 Based on ncurses implementation in:
363 - ncurses/tinfo/read_entry.c:_nc_read_termtype()
364 - ncurses/tinfo/read_entry.c:_nc_read_file_entry()
365 - ncurses/tinfo/lib_ti.c:tigetstr()
366 """
367 data = _read_terminfo_file(terminal_name)
368 too_short = f"TermInfo file for {terminal_name!r} too short"
369 offset = 12
370 if len(data) < offset:
371 raise ValueError(too_short)
372
373 magic, name_size, bool_count, num_count, str_count, str_size = (
374 struct.unpack("<Hhhhhh", data[:offset])
375 )
376
377 if magic == MAGIC16:
378 number_size = 2
379 elif magic == MAGIC32:
380 number_size = 4
381 else:
382 raise ValueError(
383 f"TermInfo file for {terminal_name!r} uses unknown magic"
384 )
385
386 # Skip data than PyREPL doesn't need:
387 # - names (`|`-separated ASCII strings)
388 # - boolean capabilities (bytes with value 0 or 1)
389 # - numbers (little-endian integers, `number_size` bytes each)
390 offset += name_size
391 offset += bool_count
392 if offset % 2:
393 # Align to even byte boundary for numbers
394 offset += 1
395 offset += num_count * number_size
396 if offset > len(data):
397 raise ValueError(too_short)
398
399 # Read string offsets
400 end_offset = offset + 2 * str_count
401 if offset > len(data):
402 raise ValueError(too_short)
403 string_offset_data = data[offset:end_offset]
404 string_offsets = [
405 off for [off] in struct.iter_unpack("<h", string_offset_data)
406 ]
407 offset = end_offset
408
409 # Read string table
410 if offset + str_size > len(data):
411 raise ValueError(too_short)
412 string_table = data[offset : offset + str_size]
413
414 # Extract strings from string table
415 capabilities = {}
416 for cap, off in zip(_STRING_NAMES, string_offsets):
417 if off < 0:
418 # CANCELLED_STRING; we do not store those
419 continue
420 elif off < len(string_table):
421 # Find null terminator
422 end = string_table.find(0, off)
423 if end >= 0:
424 capabilities[cap] = string_table[off:end]
425 # in other cases this is ABSENT_STRING; we don't store those.
426
427 # Note: we don't support extended capabilities since PyREPL doesn't
428 # need them.
429
430 self._capabilities = capabilities
431
432 def get(self, cap: str) -> bytes | None:
433 """Get terminal capability string by name.
434 """
435 if not isinstance(cap, str):
436 raise TypeError(f"`cap` must be a string, not {type(cap)}")
437
438 return self._capabilities.get(cap)
439
440
441 def tparm(cap_bytes: bytes, *params: int) -> bytes:
442 """Parameterize a terminal capability string.
443
444 Based on ncurses implementation in:
445 - ncurses/tinfo/lib_tparm.c:tparm()
446 - ncurses/tinfo/lib_tparm.c:tparam_internal()
447
448 The ncurses version implements a full stack-based interpreter for
449 terminfo parameter strings. This pure Python version implements only
450 the subset of parameter substitution operations needed by PyREPL:
451 - %i (increment parameters for 1-based indexing)
452 - %p[1-9]%d (parameter substitution)
453 - %p[1-9]%{n}%+%d (parameter plus constant)
454 """
455 if not isinstance(cap_bytes, bytes):
456 raise TypeError(f"`cap` must be bytes, not {type(cap_bytes)}")
457
458 result = cap_bytes
459
460 # %i - increment parameters (1-based instead of 0-based)
461 increment = b"%i" in result
462 if increment:
463 result = result.replace(b"%i", b"")
464
465 # Replace %p1%d, %p2%d, etc. with actual parameter values
466 for i in range(len(params)):
467 pattern = b"%%p%d%%d" % (i + 1)
468 if pattern in result:
469 value = params[i]
470 if increment:
471 value += 1
472 result = result.replace(pattern, str(value).encode("ascii"))
473
474 # Handle %p1%{1}%+%d (parameter plus constant)
475 # Used in some cursor positioning sequences
476 pattern_re = re.compile(rb"%p(\d)%\{(\d+)\}%\+%d")
477 matches = list(pattern_re.finditer(result))
478 for match in reversed(matches): # reversed to maintain positions
479 param_idx = int(match.group(1))
480 constant = int(match.group(2))
481 value = params[param_idx] + constant
482 result = (
483 result[: match.start()]
484 + str(value).encode("ascii")
485 + result[match.end() :]
486 )
487
488 return result