Skip to content

Commit cc50e86

Browse files
committed
Highlight matching delimiters in the REPL
1 parent 5503a5e commit cc50e86

9 files changed

Lines changed: 689 additions & 16 deletions

File tree

‎Doc/tutorial/appendix.rst‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,11 @@ control capabilities.
1717
Since Python 3.13, a new interactive shell is used by default.
1818
This one supports color, multiline editing, history browsing, and
1919
paste mode. To disable color, see :ref:`using-on-controlling-color` for
20-
details. Function keys provide some additional functionality.
20+
details. When the cursor touches a parenthesis, bracket, brace, or string
21+
quote, its matching delimiter is highlighted. This includes triple quotes
22+
and expressions in formatted and template strings. Delimiters within
23+
string contents and comments are ignored. Function keys provide some
24+
additional functionality.
2125
:kbd:`F1` enters the interactive help browser :mod:`pydoc`.
2226
:kbd:`F2` allows for browsing command-line history with neither output nor the
2327
:term:`>>>` and :term:`...` prompts. :kbd:`F3` enters "paste mode", which

‎Lib/_colorize.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,6 +412,7 @@ class Syntax(ThemeSection):
412412
number: str = ANSIColors.YELLOW
413413
op: str = ANSIColors.RESET
414414
definition: str = ANSIColors.BOLD
415+
matching_delimiter: str = ANSIColors.INTENSE_BACKGROUND_BLACK
415416
soft_keyword: str = ANSIColors.BOLD_BLUE
416417
reset: str = ANSIColors.RESET
417418

‎Lib/_pyrepl/reader.py‎

Lines changed: 59 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,10 @@
3737
from .layout import LayoutMap, LayoutResult, LayoutRow, WrappedRow, layout_content_lines
3838
from .layout import wrapped_row_end
3939
from .render import RenderCell, RenderLine, RenderedScreen, ScreenOverlay
40-
from .utils import ANSI_ESCAPE_SEQUENCE, ColorSpan, THEME, StyleRef, gen_colors
40+
from .utils import (
41+
ANSI_ESCAPE_SEQUENCE, ColorSpan, THEME, StyleRef,
42+
find_matching_delimiter, gen_colors,
43+
)
4144
from .trace import trace
4245

4346

@@ -304,6 +307,7 @@ class Reader:
304307
cxy: CursorXY = field(init=False)
305308
lxy: CursorXY = field(init=False)
306309
scheduled_commands: list[CommandName] = field(default_factory=list)
310+
_matching_delimiter: tuple[int, int] | None = field(init=False)
307311
can_colorize: bool = False
308312
gen_colors: Callable[[str], Iterator[ColorSpan]] = gen_colors
309313
threading_hook: Callback | None = None
@@ -386,6 +390,7 @@ def __post_init__(self) -> None:
386390
self.input_trans = input.KeymapTranslator(
387391
self.keymap, invalid_cls="invalid-key", character_cls="self-insert"
388392
)
393+
self._matching_delimiter = None
389394
self.layout = LayoutMap.empty()
390395
self.cxy = self.pos2xy()
391396
self.lxy = (self.pos, 0)
@@ -429,9 +434,8 @@ def calc_screen(self) -> RenderedScreen:
429434
self,
430435
reuse_full=True,
431436
)
432-
assert not self.last_refresh_cache.line_end_offsets or (
433-
self.last_refresh_cache.line_end_offsets[-1] >= len(self.buffer)
434-
), "Buffer modified without invalidate_buffer() call"
437+
# A short screen can cache only a prefix of the buffer.
438+
# get_cached_location() then falls back to a full rebuild.
435439
else:
436440
offset, num_common_lines = self.last_refresh_cache.get_cached_location(
437441
self,
@@ -602,8 +606,51 @@ def _render_message_lines(self) -> tuple[RenderLine, ...]:
602606
def get_screen_overlays(self) -> tuple[ScreenOverlay, ...]:
603607
return ()
604608

609+
def _get_matching_delimiter(self) -> tuple[int, int] | None:
610+
if not self.can_colorize or self.finished:
611+
return None
612+
if not any(
613+
0 <= i < len(self.buffer) and self.buffer[i] in "()[]{}\"'"
614+
for i in (self.pos, self.pos - 1)
615+
):
616+
return None
617+
return find_matching_delimiter(self.get_unicode(), self.pos)
618+
619+
def _matching_delimiter_overlays(
620+
self, base_screen: RenderedScreen
621+
) -> tuple[ScreenOverlay, ...]:
622+
if (
623+
self._matching_delimiter is None
624+
or not self.last_refresh_cache.line_end_offsets
625+
):
626+
return ()
627+
628+
changed_rows: dict[int, list[RenderCell]] = {}
629+
start, end = self._matching_delimiter
630+
for offset in range(start, end):
631+
# pos_to_xy() clamps positions beyond the cached layout.
632+
if offset >= self.last_refresh_cache.line_end_offsets[-1]:
633+
break
634+
# The delimiter's end disambiguates a wrap boundary.
635+
x, y = self.layout.pos_to_xy(offset + 1)
636+
cells = changed_rows.setdefault(y, list(base_screen.lines[y].cells))
637+
column = 0
638+
for i, cell in enumerate(cells):
639+
if column == x - 1 and cell.width:
640+
cells[i] = replace(
641+
cell, style=StyleRef.from_tag("matching_delimiter")
642+
)
643+
break
644+
column += cell.width
645+
return tuple(
646+
ScreenOverlay(y, (RenderLine.from_cells(cells),))
647+
for y, cells in changed_rows.items()
648+
)
649+
605650
def compose_rendered_screen(self, base_screen: RenderedScreen) -> RenderedScreen:
606-
overlays = list(self.get_screen_overlays())
651+
self._matching_delimiter = self._get_matching_delimiter()
652+
overlays = list(self._matching_delimiter_overlays(base_screen))
653+
overlays.extend(self.get_screen_overlays())
607654
message_lines = self._render_message_lines()
608655
if message_lines:
609656
overlays.append(ScreenOverlay(len(base_screen.lines), message_lines))
@@ -826,6 +873,7 @@ def prepare(self) -> None:
826873
self.finished = False
827874
del self.buffer[:]
828875
self.pos = 0
876+
self._matching_delimiter = None
829877
self.layout = LayoutMap.empty()
830878
self.cxy = self.pos2xy()
831879
self.lxy = (self.pos, 0)
@@ -892,6 +940,11 @@ def error(self, msg: str = "none") -> None:
892940
self.invalidate_message()
893941

894942
def update_screen(self) -> None:
943+
if (
944+
not self.invalidation.needs_screen_refresh
945+
and self._get_matching_delimiter() != self._matching_delimiter
946+
):
947+
self.invalidate_overlay()
895948
if self.invalidation.is_cursor_only:
896949
self.update_cursor()
897950
self.clear_invalidation()
@@ -939,12 +992,12 @@ def do_cmd(self, cmd: CommandInput) -> None:
939992
and not self.invalidation.is_cursor_only
940993
):
941994
self.invalidate_cursor()
995+
self.finished = bool(command.finish)
942996
self.update_screen()
943997

944998
if command_type is not commands.digit_arg:
945999
self.last_command = command_type
9461000

947-
self.finished = bool(command.finish)
9481001
if self.finished:
9491002
self.console.finish()
9501003
self.finish()

‎Lib/_pyrepl/simple_interact.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ def maybe_run_command(statement: str) -> bool:
159159
r.cmpltn_reset()
160160
if r.input_trans is r.isearch_trans:
161161
r.do_cmd(("isearch-end", [""]))
162+
r.finished = True
162163
r.pos = len(r.get_unicode())
163164
r.invalidate_full()
164165
r.refresh()

‎Lib/_pyrepl/utils.py‎

Lines changed: 82 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -116,12 +116,7 @@ def unbracket(s: str, including_content: bool = False) -> str:
116116
return s.translate(ZERO_WIDTH_TRANS)
117117

118118

119-
def gen_colors(buffer: str) -> Iterator[ColorSpan]:
120-
"""Returns a list of index spans to color using the given color tag.
121-
122-
The input `buffer` should be a valid start of a Python code block, i.e.
123-
it cannot be a block starting in the middle of a multiline string.
124-
"""
119+
def _get_token_stream(buffer: str) -> tuple[Iterator[TI], list[int]]:
125120
sio = StringIO(buffer)
126121
line_lengths = [0] + [len(line) for line in sio.readlines()]
127122
# make line_lengths cumulative
@@ -130,6 +125,87 @@ def gen_colors(buffer: str) -> Iterator[ColorSpan]:
130125

131126
sio.seek(0)
132127
gen = tokenize.generate_tokens(sio.readline)
128+
return gen, line_lengths
129+
130+
131+
def find_matching_delimiter(buffer: str, pos: int) -> tuple[int, int] | None:
132+
"""Return the half-open span of the partner touching the cursor."""
133+
# A delimiter under the cursor takes precedence, even inside literal data.
134+
candidate = next((
135+
i for i in (pos, pos - 1)
136+
if 0 <= i < len(buffer) and buffer[i] in "()[]{}\"'"
137+
), None)
138+
if candidate is None:
139+
return None
140+
141+
gen, line_lengths = _get_token_stream(buffer)
142+
try:
143+
return _find_matching_delimiter_from_token_stream(
144+
gen, line_lengths, candidate
145+
)
146+
except SyntaxError, tokenize.TokenError:
147+
# Incomplete input can still contain complete pairs.
148+
return None
149+
150+
151+
def _find_matching_delimiter_from_token_stream(
152+
token_generator: Iterator[TI],
153+
line_lengths: list[int],
154+
candidate: int,
155+
) -> tuple[int, int] | None:
156+
brackets: list[tuple[str, int]] = []
157+
strings: list[tuple[int, int]] = []
158+
closing = {")": "(", "]": "[", "}": "{"}
159+
for token in token_generator:
160+
if token.type == T.ERRORTOKEN and token.string in {"\"", "'"}:
161+
# An unfinished short string can expose apparent operators.
162+
break
163+
offset = line_lengths[token.start[0] - 1] + token.start[1]
164+
pair = None
165+
match token.type:
166+
case T.STRING | T.FSTRING_START | T.TSTRING_START:
167+
# Token boundaries already account for prefixes and escapes.
168+
quote_index = next(
169+
i for i, c in enumerate(token.string) if c in "\"'"
170+
)
171+
delimiter = token.string[quote_index]
172+
width = 3 if token.string.startswith(delimiter * 3, quote_index) else 1
173+
opening = (offset + quote_index, offset + quote_index + width)
174+
if token.type == T.STRING:
175+
end = line_lengths[token.end[0] - 1] + token.end[1]
176+
pair = (opening, (end - width, end))
177+
else:
178+
strings.append(opening)
179+
case T.FSTRING_END | T.TSTRING_END:
180+
opening = strings.pop()
181+
pair = (opening, (offset, offset + len(token.string)))
182+
case T.OP if token.string in "()[]{}":
183+
if token.string in "([{":
184+
brackets.append((token.string, offset))
185+
elif brackets and brackets[-1][0] == closing[token.string]:
186+
_, opening_offset = brackets.pop()
187+
pair = (
188+
(opening_offset, opening_offset + 1), (offset, offset + 1)
189+
)
190+
else:
191+
# Do not pair across an incorrectly nested delimiter.
192+
brackets.clear()
193+
if pair is not None:
194+
opening, ending = pair
195+
if opening[0] <= candidate < opening[1]:
196+
return ending
197+
if ending[0] <= candidate < ending[1]:
198+
return opening
199+
return None
200+
201+
202+
def gen_colors(buffer: str) -> Iterator[ColorSpan]:
203+
"""Returns a list of index spans to color using the given color tag.
204+
205+
The input `buffer` should be a valid start of a Python code block, i.e.
206+
it cannot be a block starting in the middle of a multiline string.
207+
"""
208+
gen, line_lengths = _get_token_stream(buffer)
133209
last_emitted: ColorSpan | None = None
134210
try:
135211
for color in gen_colors_from_token_stream(gen, line_lengths):

‎Lib/test/test_pyrepl/test_interact.py‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,52 @@
88
from test.support import force_not_colorized
99

1010
from _pyrepl.console import InteractiveColoredConsole
11-
from _pyrepl.simple_interact import _more_lines
11+
from _pyrepl.simple_interact import _more_lines, run_multiline_interactive_console
12+
from .support import FakeConsole, prepare_reader
1213

1314
class TestSimpleInteract(unittest.TestCase):
15+
def test_keyboard_interrupt_clears_matching_delimiter_overlay(self):
16+
backend = FakeConsole(())
17+
reader = prepare_reader(backend)
18+
reader.can_colorize = True
19+
reader.buffer = list("(x)")
20+
reader.pos = 0
21+
reader.refresh()
22+
23+
matching_cells = [
24+
cell
25+
for overlay in reader.rendered_screen.overlays
26+
for line in overlay.lines
27+
for cell in line.cells
28+
if cell.style.tag == "matching_delimiter"
29+
]
30+
self.assertEqual([cell.text for cell in matching_cells], [")"])
31+
32+
console = InteractiveColoredConsole()
33+
reader.push_input_trans(reader.isearch_trans)
34+
with (
35+
patch("_pyrepl.readline._setup"),
36+
patch("_pyrepl.simple_interact._get_reader", return_value=reader),
37+
patch(
38+
"_pyrepl.simple_interact.multiline_input",
39+
side_effect=[KeyboardInterrupt, EOFError],
40+
),
41+
patch.object(console, "runsource", wraps=console.runsource) as runsource,
42+
contextlib.redirect_stderr(io.StringIO()) as stderr,
43+
):
44+
run_multiline_interactive_console(console)
45+
46+
self.assertEqual("".join(reader.buffer), "(x)")
47+
self.assertFalse(
48+
any(
49+
cell.style.tag == "matching_delimiter"
50+
for line in reader.rendered_screen.composed_lines
51+
for cell in line.cells
52+
)
53+
)
54+
self.assertIn("KeyboardInterrupt", stderr.getvalue())
55+
runsource.assert_not_called()
56+
1457
def test_multiple_statements(self):
1558
namespace = {}
1659
code = dedent("""\

0 commit comments

Comments
 (0)