cpython/Lib/_pyrepl/render.py at 3.15 · python/cpython · GitHub

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

from __future__ import annotations

from collections.abc import Iterable, Sequence

from dataclasses import dataclass, field

from typing import Literal, Protocol, Self

from _colorize import ANSIColors

from .types import CursorXY

from .utils import ANSI_ESCAPE_SEQUENCE, THEME, StyleRef, str_width

type RenderStyle = StyleRef | str | None

type LineUpdateKind = Literal[

"insert_char",

"replace_char",

"replace_span",

"delete_then_insert",

"rewrite_suffix",

]

class _ThemeSyntax(Protocol):

"""Protocol for theme objects that map tag names to SGR escape strings."""

def __getitem__(self, key: str, /) -> str: ...

@dataclass(frozen=True, slots=True)

class RenderCell:

"""One terminal cell: a character, its column width, and SGR style.

A screen row like ``>>> def`` is a sequence of cells::

> > > d e f

╰─╯╰─╯╰─╯╰─╯╰─╯╰─╯╰─╯

"""

text: str

width: int

style: StyleRef = field(default_factory=StyleRef)

controls: tuple[str, ...] = ()

@property

def terminal_text(self) -> str:

return render_cells((self,))

def _theme_style(theme: _ThemeSyntax, tag: str) -> str:

return theme[tag]

def _style_escape(style: StyleRef) -> str:

if style.sgr:

return style.sgr

if style.tag is None:

return ""

return _theme_style(THEME(), style.tag)

def _update_terminal_state(state: str, escape: str) -> str:

if escape in {ANSIColors.RESET, "\x1b[m"}:

return ""

return state + escape

def _cells_from_rendered_text(text: str) -> tuple[RenderCell, ...]:

if not text:

return ()

cells: list[RenderCell] = []

pending_controls: list[str] = []

active_sgr = ""

index = 0

def append_plain_text(segment: str) -> None:

nonlocal pending_controls

if not segment:

return

if pending_controls:

cells.append(RenderCell("", 0, controls=tuple(pending_controls)))

pending_controls = []

for char in segment:

cells.append(

RenderCell(

char,

str_width(char),

style=StyleRef.from_sgr(active_sgr),

)

for match in ANSI_ESCAPE_SEQUENCE.finditer(text):

append_plain_text(text[index : match.start()])

escape = match.group(0)

if escape.endswith("m"):

active_sgr = _update_terminal_state(active_sgr, escape)

else:

pending_controls.append(escape)

index = match.end()

append_plain_text(text[index:])

if pending_controls:

cells.append(RenderCell("", 0, controls=tuple(pending_controls)))

return tuple(cells)

@dataclass(frozen=True, slots=True)

class RenderLine:

"""One physical screen row as a tuple of :class:`RenderCell` objects.

``text`` is the pre-rendered terminal string (characters + SGR escapes);

``width`` is the total visible column count.

"""

cells: tuple[RenderCell, ...]

text: str

width: int

@classmethod

def from_cells(cls, cells: Iterable[RenderCell]) -> Self:

cell_tuple = tuple(cells)

return cls(

cells=cell_tuple,

text=render_cells(cell_tuple),

width=sum(cell.width for cell in cell_tuple),

)

@classmethod

def from_parts(

cls,

parts: Sequence[str],

widths: Sequence[int],

styles: Sequence[RenderStyle] | None = None,

) -> Self:

if styles is None:

return cls.from_cells(

RenderCell(text, width)

for text, width in zip(parts, widths)

)

cells: list[RenderCell] = []

for text, width, style in zip(parts, widths, styles):

if isinstance(style, StyleRef):

cells.append(RenderCell(text, width, style=style))

elif style is None:

cells.append(RenderCell(text, width))

else:

cells.append(RenderCell(text, width, style=StyleRef.from_tag(style)))

return cls.from_cells(cells)

@classmethod

def from_rendered_text(cls, text: str) -> Self:

return cls.from_cells(_cells_from_rendered_text(text))

@dataclass(frozen=True, slots=True)

class ScreenOverlay:

"""An overlay that replaces or inserts lines at a screen position.

If *insert* is True, lines are spliced in (shifting content down);

if False (default), lines replace existing content at *y*.

Overlays are used to display tab completion menus and status messages.

For example, a tab-completion menu inserted below the input::

>>> os.path.j ← line 0 (base content)

join ← ScreenOverlay(y=1, insert=True)

junction ← (pushes remaining lines down)

... ← line 1 (shifted down by 2)

"""

y: int

lines: tuple[RenderLine, ...]

insert: bool = False

@dataclass(frozen=True, slots=True)

class RenderedScreen:

"""The complete screen state: content lines, cursor, and overlays.

``lines`` holds the base content; ``composed_lines`` is the final

result after overlays (completion menus, messages) are applied::

lines: composed_lines:

┌──────────────────┐ ┌──────────────────┐

│>>> os.path.j │ │>>> os.path.j │

│... │ ──► │ join │ ← overlay

└──────────────────┘ │... │

└──────────────────┘

"""

lines: tuple[RenderLine, ...]

cursor: CursorXY

overlays: tuple[ScreenOverlay, ...] = ()

composed_lines: tuple[RenderLine, ...] = field(init=False, default=())

def __post_init__(self) -> None:

object.__setattr__(self, "composed_lines", self._compose())

def _compose(self) -> tuple[RenderLine, ...]:

"""Apply overlays in tuple order; inserts shift subsequent positions."""

if not self.overlays:

return self.lines

lines = list(self.lines)

y_offset = 0

for overlay in self.overlays:

adjusted_y = overlay.y + y_offset

assert adjusted_y >= 0, (

f"Overlay y={overlay.y} with offset={y_offset} is negative; "

"overlays must be sorted by ascending y"

)

if overlay.insert:

# Splice overlay lines in, pushing existing content down.

lines[adjusted_y:adjusted_y] = overlay.lines

y_offset += len(overlay.lines)

else:

# Replace existing lines at the overlay position.

target_len = adjusted_y + len(overlay.lines)

if len(lines) < target_len:

lines.extend([EMPTY_RENDER_LINE] * (target_len - len(lines)))

for index, line in enumerate(overlay.lines):

lines[adjusted_y + index] = line

return tuple(lines)

@classmethod

def empty(cls) -> Self:

return cls((), (0, 0), ())

@classmethod

def from_screen_lines(

cls,

screen: Sequence[str],

cursor: CursorXY,

) -> Self:

return cls(

tuple(RenderLine.from_rendered_text(line) for line in screen),

cursor,

(),

)

def with_overlay(

self,

y: int,

lines: Iterable[RenderLine],

) -> Self:

return type(self)(

self.lines,

self.cursor,

self.overlays + (ScreenOverlay(y, tuple(lines)),),

)

@property

def screen_lines(self) -> tuple[str, ...]:

return tuple(line.text for line in self.composed_lines)

@dataclass(frozen=True, slots=True)

class LineDiff:

"""The changed region between an old and new version of one screen row.

When the user types ``e`` so the row changes from

``>>> nam`` to ``>>> name``::

>>> n a m old

>>> n a m e new

╰─╯

start_cell=7, new_cells=("m","e"), old_cells=("m",)

"""

start_cell: int

start_x: int

old_cells: tuple[RenderCell, ...]

new_cells: tuple[RenderCell, ...]

old_width: int

new_width: int

@property

def old_text(self) -> str:

return render_cells(self.old_cells)

@property

def new_text(self) -> str:

return render_cells(self.new_cells)

@property

def old_changed_width(self) -> int:

return sum(cell.width for cell in self.old_cells)

@property

def new_changed_width(self) -> int:

return sum(cell.width for cell in self.new_cells)

EMPTY_RENDER_LINE = RenderLine(cells=(), text="", width=0)

@dataclass(frozen=True, slots=True)

class LineUpdate:

kind: LineUpdateKind

y: int

start_cell: int

start_x: int

"""Screen x-coordinate where the update begins. Used for cursor positioning."""

cells: tuple[RenderCell, ...]

char_width: int = 0

clear_eol: bool = False

reset_to_margin: bool = False

"""If True, the console must resync the cursor position after writing

(needed when cells contain non-SGR escape sequences that may move the cursor)."""

text: str = field(init=False, default="")

def __post_init__(self) -> None:

object.__setattr__(self, "text", render_cells(self.cells))

def _controls_require_cursor_resync(controls: Sequence[str]) -> bool:

# Anything beyond SGR means the cursor may no longer be where we left it.

return any(not control.endswith("m") for control in controls)

def requires_cursor_resync(cells: Sequence[RenderCell]) -> bool:

return any(_controls_require_cursor_resync(cell.controls) for cell in cells)

def render_cells(

cells: Sequence[RenderCell],

visual_style: str | None = None,

) -> str:

"""Render a sequence of cells into a terminal string with SGR escapes.

Tracks the active SGR state to emit resets only when the style

actually changes, minimizing output bytes.

If *visual_style* is given (used by redraw visualization), it is appended

to every cell's style.

"""

rendered: list[str] = []

active_escape = ""

for cell in cells:

if cell.controls:

rendered.extend(cell.controls)

if not cell.text:

continue

target_escape = _style_escape(cell.style)

if visual_style is not None:

target_escape += visual_style

if target_escape != active_escape:

if active_escape:

rendered.append(ANSIColors.RESET)

if target_escape:

rendered.append(target_escape)

active_escape = target_escape

rendered.append(cell.text)

if active_escape:

rendered.append(ANSIColors.RESET)

return "".join(rendered)

def diff_render_lines(old: RenderLine, new: RenderLine) -> LineDiff | None:

if old == new:

return None

prefix = 0

start_x = 0

max_prefix = min(len(old.cells), len(new.cells))

while prefix < max_prefix and old.cells[prefix] == new.cells[prefix]:

# Stop at any cell with non-SGR controls, since those might affect

# cursor position and must be re-emitted.

if old.cells[prefix].controls:

break

start_x += old.cells[prefix].width

prefix += 1

old_suffix = len(old.cells)

new_suffix = len(new.cells)

while old_suffix > prefix and new_suffix > prefix:

old_cell = old.cells[old_suffix - 1]

new_cell = new.cells[new_suffix - 1]

if old_cell.controls or new_cell.controls or old_cell != new_cell:

break

old_suffix -= 1

new_suffix -= 1

# Extend diff range to include trailing zero-width combining characters,

# so we never render a combining char without its base character.

while old_suffix < len(old.cells) and old.cells[old_suffix].width == 0:

old_suffix += 1

while new_suffix < len(new.cells) and new.cells[new_suffix].width == 0:

new_suffix += 1

return LineDiff(

start_cell=prefix,

start_x=start_x,

old_cells=old.cells[prefix:old_suffix],

new_cells=new.cells[prefix:new_suffix],

old_width=old.width,

new_width=new.width,

)

cpython/Lib/_pyrepl/render.py at 3.15 · python/cpython · GitHub

Repository navigation

Expand file tree

Breadcrumbs

render.py

Latest commit

History

Breadcrumbs

render.py

File metadata and controls