markdown_tables.py 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. """CJK/wide-character-aware re-alignment of model-emitted markdown tables.
  2. Models pad tables assuming one cell per character; CJK glyphs and most emoji
  3. take two, so body rows drift right on real terminals. This rebuilds padding
  4. with ``wcwidth.wcswidth`` while preserving pipes/dashes (Rich already aligns CJK).
  5. Deliberately conservative: only contiguous ``| ... |`` blocks with a divider are
  6. rewritten; single-line/mid-stream fragments pass through (callers buffer rows and
  7. flush complete blocks). ``wcswidth`` returns ``-1`` for some emoji+variation-selector
  8. sequences (``⚠️``); those clamp to 0 — a 1-cell drift beats widening every table.
  9. """
  10. from __future__ import annotations
  11. import re
  12. from typing import List
  13. from wcwidth import wcswidth
  14. __all__ = ["is_table_divider", "looks_like_table_row", "realign_markdown_tables", "split_table_row"]
  15. _DIVIDER_CELL_RE = re.compile(r"^\s*:?-{3,}:?\s*$")
  16. _MIN_COL_WIDTH = 3 # matches the divider's minimum dash run.
  17. def _disp_width(s: str) -> int:
  18. """``wcswidth`` clamped to >= 0 (it returns -1 for control/unknown sequences)."""
  19. return max(wcswidth(s), 0)
  20. def split_table_row(row: str) -> list[str]:
  21. """Split ``| a | b | c |`` into ``["a", "b", "c"]`` with trims."""
  22. return [c.strip() for c in row.strip().removeprefix("|").removesuffix("|").split("|")]
  23. def is_table_divider(row: str) -> bool:
  24. """True when ``row`` is a markdown table separator line."""
  25. cells = split_table_row(row)
  26. return len(cells) > 1 and all(_DIVIDER_CELL_RE.match(c) for c in cells)
  27. def looks_like_table_row(row: str) -> bool:
  28. """True when ``row`` could plausibly be a markdown table row.
  29. Intentionally permissive for streaming callers deciding whether to buffer a
  30. line (a false positive at most delays printing one line). A leading pipe is
  31. the strongest signal; without it we accept >= 2 pipes so models that omit
  32. the leading pipe still match.
  33. """
  34. stripped = row.strip()
  35. return bool(stripped) and (stripped.startswith("|") or stripped.count("|") >= 2)
  36. def _render_block(rows: list[list[str]], available_width: int | None = None) -> list[str]:
  37. """Render ``rows`` (header + body, divider implied) at uniform widths.
  38. When the horizontal table would exceed ``available_width`` fall back to a
  39. vertical key-value rendering: terminal soft-wrap mid-cell destroys alignment
  40. visually even when the bytes are perfectly padded.
  41. """
  42. ncols = max(len(r) for r in rows)
  43. rows = [r + [""] * (ncols - len(r)) for r in rows]
  44. widths = [max(_MIN_COL_WIDTH, *(_disp_width(r[c]) for r in rows)) for c in range(ncols)]
  45. # `| ` + cell + ` ` per column, plus the closing `|`.
  46. if available_width is not None and sum(widths) + 3 * ncols + 1 > max(available_width, 20):
  47. return _render_vertical(rows, ncols, available_width)
  48. def _row(cells: list[str]) -> str:
  49. return "| " + " | ".join(c + " " * max(0, widths[k] - _disp_width(c)) for k, c in enumerate(cells)) + " |"
  50. out = [_row(rows[0]), "|" + "|".join("-" * (w + 2) for w in widths) + "|"]
  51. out.extend(_row(r) for r in rows[1:])
  52. return out
  53. def _hard_break(word: str, w: int) -> list[str]:
  54. """Split a single over-wide word into display-width-``w`` chunks."""
  55. out: list[str] = []
  56. buf, bw = "", 0
  57. for ch in word:
  58. cw = _disp_width(ch) or 1
  59. if bw + cw > w and buf:
  60. out.append(buf)
  61. buf, bw = ch, cw
  62. else:
  63. buf, bw = buf + ch, bw + cw
  64. return out + [buf] if buf else out
  65. def _wrap_to_width(text: str, width: int) -> list[str]:
  66. """Soft-wrap ``text`` at word boundaries to ``width`` display cells.
  67. Words wider than ``width`` are hard-broken. Empty input yields a single
  68. empty string so the caller's row count stays predictable.
  69. """
  70. if width <= 0 or not text:
  71. return [text]
  72. words = text.split()
  73. if not words:
  74. return [""]
  75. lines: list[str] = []
  76. current, current_w = "", 0
  77. def _start(word: str, ww: int) -> None:
  78. nonlocal current, current_w
  79. if ww <= width:
  80. current, current_w = word, ww
  81. else:
  82. pieces = _hard_break(word, width)
  83. lines.extend(pieces[:-1])
  84. current = pieces[-1] if pieces else ""
  85. current_w = _disp_width(current)
  86. for word in words:
  87. ww = _disp_width(word)
  88. if not current:
  89. _start(word, ww)
  90. elif current_w + 1 + ww <= width:
  91. current += " " + word
  92. current_w += 1 + ww
  93. else:
  94. lines.append(current)
  95. _start(word, ww)
  96. if current:
  97. lines.append(current)
  98. return lines or [""]
  99. def _render_vertical(rows: list[list[str]], ncols: int, available_width: int) -> list[str]:
  100. """Render a too-wide table as ``Header: value`` blocks (Claude Code's narrow fallback).
  101. Each body row becomes one block with continuation lines indented two spaces,
  102. blocks separated by a thin ``─`` rule; every line stays under ``available_width``.
  103. """
  104. if not rows:
  105. return []
  106. labels = [h or f"Column {i + 1}" for i, h in enumerate(rows[0] + [""] * (ncols - len(rows[0])))]
  107. separator = "─" * (max(20, min(40, available_width - 2)) if available_width else 30)
  108. cont_budget = max(10, available_width - 2) # continuation lines are indented two spaces
  109. out: list[str] = []
  110. for ri, row in enumerate(rows[1:]):
  111. if ri > 0:
  112. out.append(separator)
  113. for ci, label in enumerate(labels):
  114. value = row[ci] if ci < len(row) else ""
  115. if not value:
  116. out.append(f"{label}:")
  117. continue
  118. wrapped = _wrap_to_width(value, max(10, available_width - _disp_width(label) - 2))
  119. out.append(f"{label}: {wrapped[0]}")
  120. # Re-flow continuation text at the wider continuation budget.
  121. for cl in _wrap_to_width(" ".join(wrapped[1:]), cont_budget) if len(wrapped) > 1 else ():
  122. if cl.strip():
  123. out.append(f" {cl}")
  124. return out
  125. def realign_markdown_tables(text: str, available_width: int | None = None) -> str:
  126. """Rewrite every ``| ... |`` + divider block with wcwidth-aware padding.
  127. Non-table lines are returned verbatim, so this is safe on arbitrary prose.
  128. With ``available_width`` (terminal cells), tables wider than that render as
  129. vertical key-value pairs instead of soft-wrapping mid-cell.
  130. """
  131. if "|" not in text:
  132. return text
  133. lines = text.split("\n")
  134. out: list[str] = []
  135. i, n = 0, len(lines)
  136. while i < n:
  137. line = lines[i]
  138. # A table starts with a header row whose next line is a divider.
  139. if "|" in line and i + 1 < n and is_table_divider(lines[i + 1]):
  140. header = split_table_row(line)
  141. body: list[list[str]] = []
  142. j = i + 2
  143. while j < n and "|" in lines[j] and lines[j].strip():
  144. if not is_table_divider(lines[j]):
  145. body.append(split_table_row(lines[j]))
  146. j += 1
  147. if any(header) or body:
  148. out.extend(_render_block([header] + body, available_width))
  149. i = j
  150. continue
  151. out.append(line)
  152. i += 1
  153. return "\n".join(out)