""" Sequence-aware text wrapping functions. This module provides functions for wrapping text that may contain terminal escape sequences, with proper handling of Unicode grapheme clusters and character display widths. """ from __future__ import annotations # std imports import re import secrets import textwrap from typing import TYPE_CHECKING, NamedTuple # local from .wcwidth import width as _width from .wcwidth import iter_sequences from .grapheme import iter_graphemes from .sgr_state import propagate_sgr as _propagate_sgr from .escape_sequences import ZERO_WIDTH_PATTERN if TYPE_CHECKING: # pragma: no cover from typing import Any, Literal class _HyperlinkState(NamedTuple): """State for tracking an open OSC 8 hyperlink across line breaks.""" url: str # hyperlink target URL params: str # id=xxx and other key=value pairs separated by : terminator: str # BEL (\x07) or ST (\x1b\\) # Hyperlink parsing: captures (params, url, terminator) _HYPERLINK_OPEN_RE = re.compile(r'\x1b]8;([^;]*);([^\x07\x1b]*)(\x07|\x1b\\)') def _parse_hyperlink_open(seq: str) -> _HyperlinkState | None: """Parse OSC 8 open sequence, return state or None.""" if (m := _HYPERLINK_OPEN_RE.match(seq)): return _HyperlinkState(url=m.group(2), params=m.group(1), terminator=m.group(3)) return None def _make_hyperlink_open(url: str, params: str, terminator: str) -> str: """Generate OSC 8 open sequence.""" return f'\x1b]8;{params};{url}{terminator}' def _make_hyperlink_close(terminator: str) -> str: """Generate OSC 8 close sequence.""" return f'\x1b]8;;{terminator}' class SequenceTextWrapper(textwrap.TextWrapper): """ Sequence-aware text wrapper extending :class:`textwrap.TextWrapper`. This wrapper properly handles terminal escape sequences and Unicode grapheme clusters when calculating text width for wrapping. This implementation is based on the SequenceTextWrapper from the 'blessed' library, with contributions from Avram Lubkin and grayjk. The key difference from the blessed implementation is the addition of grapheme cluster support via :func:`~.iter_graphemes`, providing width calculation for ZWJ emoji sequences, VS-16 emojis and variations, regional indicator flags, and combining characters. OSC 8 hyperlinks are handled specially: when a hyperlink must span multiple lines, each line receives complete open/close sequences with a shared ``id`` parameter, ensuring terminals treat the fragments as a single hyperlink for hover underlining. If the original hyperlink already has an ``id`` parameter, it is preserved; otherwise, one is generated. """ def __init__(self, width: int = 70, *, control_codes: Literal['parse', 'strict', 'ignore'] = 'parse', tabsize: int = 8, ambiguous_width: int = 1, **kwargs: Any) -> None: """ Initialize the wrapper. :param width: Maximum line width in display cells. :param control_codes: How to handle control sequences (see :func:`~.width`). :param tabsize: Tab stop width for tab expansion. :param ambiguous_width: Width to use for East Asian Ambiguous (A) characters. :param kwargs: Additional arguments passed to :class:`textwrap.TextWrapper`. """ super().__init__(width=width, **kwargs) self.control_codes = control_codes self.tabsize = tabsize self.ambiguous_width = ambiguous_width @staticmethod def _next_hyperlink_id() -> str: """Generate unique hyperlink id as 8-character hex string.""" return secrets.token_hex(4) def _width(self, text: str) -> int: """Measure text width accounting for sequences.""" return _width(text, control_codes=self.control_codes, tabsize=self.tabsize, ambiguous_width=self.ambiguous_width) def _strip_sequences(self, text: str) -> str: """Strip all terminal sequences from text.""" result = [] for segment, is_seq in iter_sequences(text): if not is_seq: result.append(segment) return ''.join(result) def _extract_sequences(self, text: str) -> str: """Extract only terminal sequences from text.""" result = [] for segment, is_seq in iter_sequences(text): if is_seq: result.append(segment) return ''.join(result) def _split(self, text: str) -> list[str]: # pylint: disable=too-many-locals r""" Sequence-aware variant of :meth:`textwrap.TextWrapper._split`. This method ensures that terminal escape sequences don't interfere with the text splitting logic, particularly for hyphen-based word breaking. It builds a position mapping from stripped text to original text, calls the parent's _split on stripped text, then maps chunks back. OSC hyperlink sequences are treated as word boundaries:: >>> wrap('foo \x1b]8;;https://example.com\x07link\x1b]8;;\x07 bar', 6) ['foo', '\x1b]8;;https://example.com\x07link\x1b]8;;\x07', 'bar'] Both BEL (``\x07``) and ST (``\x1b\\``) terminators are supported. """ # pylint: disable=too-many-locals,too-many-branches # Build a mapping from stripped text positions to original text positions. # # Track where each character ENDS so that sequences between characters # attach to the following text (not preceding text). This ensures sequences # aren't lost when whitespace is dropped. # # char_end[i] = position in original text right after the i-th stripped char char_end: list[int] = [] stripped_text = '' original_pos = 0 prev_was_hyperlink_close = False for segment, is_seq in iter_sequences(text): if not is_seq: # Conditionally insert space after hyperlink close to force word boundary if prev_was_hyperlink_close and segment and not segment[0].isspace(): stripped_text += ' ' char_end.append(original_pos) for char in segment: original_pos += 1 char_end.append(original_pos) stripped_text += char prev_was_hyperlink_close = False else: is_hyperlink_close = segment.startswith(('\x1b]8;;\x1b\\', '\x1b]8;;\x07')) # Conditionally insert space before OSC sequences to artificially create word # boundary, but *not* before hyperlink close sequences, to ensure hyperlink is # terminated on the same line. if (segment.startswith('\x1b]') and stripped_text and not stripped_text[-1].isspace()): if not is_hyperlink_close: stripped_text += ' ' char_end.append(original_pos) # Escape sequences advance position but don't add to stripped text original_pos += len(segment) prev_was_hyperlink_close = is_hyperlink_close # Add sentinel for final position char_end.append(original_pos) # Use parent's _split on the stripped text # pylint: disable-next=protected-access stripped_chunks = textwrap.TextWrapper._split(self, stripped_text) # Handle text that contains only sequences (no visible characters). # Return the sequences as a single chunk to preserve them. if not stripped_chunks and text: return [text] # Map the chunks back to the original text with sequences result: list[str] = [] stripped_pos = 0 num_chunks = len(stripped_chunks) for idx, chunk in enumerate(stripped_chunks): chunk_len = len(chunk) # Start is where previous character ended (or 0 for first chunk) start_orig = 0 if stripped_pos == 0 else char_end[stripped_pos - 1] # End is where next character starts. For last chunk, use sentinel # to include any trailing sequences. if idx == num_chunks - 1: end_orig = char_end[-1] # sentinel includes trailing sequences else: end_orig = char_end[stripped_pos + chunk_len - 1] # Extract the corresponding portion from the original text # Skip empty chunks (from virtual spaces inserted at OSC boundaries) if start_orig != end_orig: result.append(text[start_orig:end_orig]) stripped_pos += chunk_len return result def _wrap_chunks(self, chunks: list[str]) -> list[str]: # pylint: disable=too-many-branches """ Wrap chunks into lines using sequence-aware width. Override TextWrapper._wrap_chunks to use _width instead of len. Follows stdlib's algorithm: greedily fill lines, handle long words. Also handle OSC hyperlink processing. When hyperlinks span multiple lines, each line gets complete open/close sequences with matching id parameters for hover underlining continuity per OSC 8 spec. """ # pylint: disable=too-many-branches,too-many-statements,too-complex,too-many-locals # pylint: disable=too-many-nested-blocks # the hyperlink code in particular really pushes the complexity rating of this method. # preferring to keep it "all in one method" because of so much local state and manipulation. if not chunks: return [] if self.max_lines is not None: if self.max_lines > 1: indent = self.subsequent_indent else: indent = self.initial_indent if (self._width(indent) + self._width(self.placeholder.lstrip()) > self.width): raise ValueError("placeholder too large for max width") lines: list[str] = [] is_first_line = True hyperlink_state: _HyperlinkState | None = None # Track the id we're using for the current hyperlink continuation current_hyperlink_id: str | None = None # Arrange in reverse order so items can be efficiently popped chunks = list(reversed(chunks)) while chunks: current_line: list[str] = [] current_width = 0 # Get the indent and available width for current line indent = self.initial_indent if is_first_line else self.subsequent_indent line_width = self.width - self._width(indent) # If continuing a hyperlink from previous line, prepend open sequence if hyperlink_state is not None: open_seq = _make_hyperlink_open( hyperlink_state.url, hyperlink_state.params, hyperlink_state.terminator) chunks[-1] = open_seq + chunks[-1] # Drop leading whitespace (except at very start) # When dropping, transfer any sequences to the next chunk. # Only drop if there's actual whitespace text, not if it's only sequences. stripped = self._strip_sequences(chunks[-1]) if self.drop_whitespace and lines and stripped and not stripped.strip(): sequences = self._extract_sequences(chunks[-1]) del chunks[-1] if sequences and chunks: chunks[-1] = sequences + chunks[-1] # Greedily add chunks that fit while chunks: chunk = chunks[-1] chunk_width = self._width(chunk) if current_width + chunk_width <= line_width: current_line.append(chunks.pop()) current_width += chunk_width else: break # Handle chunk that's too long for any line if chunks and self._width(chunks[-1]) > line_width: self._handle_long_word( chunks, current_line, current_width, line_width ) current_width = self._width(''.join(current_line)) # Remove any empty chunks left by _handle_long_word while chunks and not chunks[-1]: del chunks[-1] # Drop trailing whitespace # When dropping, transfer any sequences to the previous chunk. # Only drop if there's actual whitespace text, not if it's only sequences. stripped_last = self._strip_sequences(current_line[-1]) if current_line else '' if (self.drop_whitespace and current_line and stripped_last and not stripped_last.strip()): sequences = self._extract_sequences(current_line[-1]) current_width -= self._width(current_line[-1]) del current_line[-1] if sequences and current_line: current_line[-1] = current_line[-1] + sequences if current_line: # Check whether this is a normal append or max_lines # truncation. Matches stdlib textwrap precedence: # normal if max_lines not set, not yet reached, or no # remaining visible content that would need truncation. no_more_content = ( not chunks or self.drop_whitespace and len(chunks) == 1 and not self._strip_sequences(chunks[0]).strip() ) if (self.max_lines is None or len(lines) + 1 < self.max_lines or no_more_content and current_width <= line_width): line_content = ''.join(current_line) # Track hyperlink state through this line's content new_state = self._track_hyperlink_state(line_content, hyperlink_state) # If we end inside a hyperlink, append close sequence if new_state is not None: # Ensure we have an id for continuation if current_hyperlink_id is None: if 'id=' in new_state.params: current_hyperlink_id = new_state.params elif new_state.params: # Prepend id to existing params (per OSC 8 spec, params can have # multiple key=value pairs separated by :) current_hyperlink_id = ( f'id={self._next_hyperlink_id()}:{new_state.params}') else: current_hyperlink_id = f'id={self._next_hyperlink_id()}' line_content += _make_hyperlink_close(new_state.terminator) # Also need to inject the id into the opening # sequence if it didn't have one if 'id=' not in new_state.params: # Find and replace the original open sequence with one that has id old_open = _make_hyperlink_open( new_state.url, new_state.params, new_state.terminator) new_open = _make_hyperlink_open( new_state.url, current_hyperlink_id, new_state.terminator) line_content = line_content.replace(old_open, new_open, 1) # Update state for next line, using computed id hyperlink_state = _HyperlinkState( new_state.url, current_hyperlink_id, new_state.terminator) else: hyperlink_state = None current_hyperlink_id = None # Reset id when hyperlink closes # Strip trailing whitespace when drop_whitespace is enabled # (matches CPython #140627 fix behavior) if self.drop_whitespace: line_content = line_content.rstrip() lines.append(indent + line_content) is_first_line = False else: # max_lines reached with remaining content — # pop chunks until placeholder fits, then break. placeholder_w = self._width(self.placeholder) while current_line: last_text = self._strip_sequences(current_line[-1]) if (last_text.strip() and current_width + placeholder_w <= line_width): line_content = ''.join(current_line) new_state = self._track_hyperlink_state( line_content, hyperlink_state) if new_state is not None: line_content += _make_hyperlink_close( new_state.terminator) lines.append(indent + line_content + self.placeholder) break current_width -= self._width(current_line[-1]) del current_line[-1] else: if lines: prev_line = self._rstrip_visible(lines[-1]) if (self._width(prev_line) + placeholder_w <= self.width): lines[-1] = prev_line + self.placeholder break lines.append(indent + self.placeholder.lstrip()) break return lines def _track_hyperlink_state( self, text: str, state: _HyperlinkState | None) -> _HyperlinkState | None: """ Track hyperlink state through text. :param text: Text to scan for hyperlink sequences. :param state: Current state or None if outside hyperlink. :returns: Updated state after processing text. """ for segment, is_seq in iter_sequences(text): if is_seq: parsed_link = _parse_hyperlink_open(segment) if parsed_link is not None and parsed_link.url: # has URL = open state = parsed_link elif segment.startswith(('\x1b]8;;\x1b\\', '\x1b]8;;\x07')): # close state = None return state def _handle_long_word(self, reversed_chunks: list[str], cur_line: list[str], cur_len: int, width: int) -> None: """ Sequence-aware :meth:`textwrap.TextWrapper._handle_long_word`. This method ensures that word boundaries are not broken mid-sequence, and respects grapheme cluster boundaries when breaking long words. """ if width < 1: space_left = 1 else: space_left = width - cur_len chunk = reversed_chunks[-1] if self.break_long_words: break_at_hyphen = False hyphen_end = 0 # Handle break_on_hyphens: find last hyphen within space_left if self.break_on_hyphens: # Strip sequences to find hyphen in logical text stripped = self._strip_sequences(chunk) if len(stripped) > space_left: # Find last hyphen in the portion that fits hyphen_pos = stripped.rfind('-', 0, space_left) if hyphen_pos > 0 and any(c != '-' for c in stripped[:hyphen_pos]): # Map back to original position including sequences hyphen_end = self._map_stripped_pos_to_original(chunk, hyphen_pos + 1) break_at_hyphen = True # Break at grapheme boundaries to avoid splitting multi-codepoint characters if break_at_hyphen: actual_end = hyphen_end else: actual_end = self._find_break_position(chunk, space_left) # If no progress possible (e.g., wide char exceeds line width), # force at least one grapheme to avoid infinite loop. # Only force when cur_line is empty; if line has content, # appending nothing is safe and the line will be committed. if actual_end == 0 and not cur_line: actual_end = self._find_first_grapheme_end(chunk) cur_line.append(chunk[:actual_end]) reversed_chunks[-1] = chunk[actual_end:] elif not cur_line: cur_line.append(reversed_chunks.pop()) def _map_stripped_pos_to_original(self, text: str, stripped_pos: int) -> int: """Map a position in stripped text back to original text position.""" stripped_idx = 0 original_idx = 0 for segment, is_seq in iter_sequences(text): if is_seq: original_idx += len(segment) elif stripped_idx + len(segment) > stripped_pos: # Position is within this segment return original_idx + (stripped_pos - stripped_idx) else: stripped_idx += len(segment) original_idx += len(segment) # Caller guarantees stripped_pos < total stripped chars, so we always # return from within the loop. This line satisfies the type checker. return original_idx # pragma: no cover def _find_break_position(self, text: str, max_width: int) -> int: """Find string index in text that fits within max_width cells.""" idx = 0 width_so_far = 0 while idx < len(text): char = text[idx] # Skip escape sequences (they don't add width) if char == '\x1b': match = ZERO_WIDTH_PATTERN.match(text, idx) if match: idx = match.end() continue # Get grapheme (use start= to avoid slice allocation) grapheme = next(iter_graphemes(text, start=idx)) grapheme_width = self._width(grapheme) if width_so_far + grapheme_width > max_width: return idx # Found break point width_so_far += grapheme_width idx += len(grapheme) # Caller guarantees chunk_width > max_width, so a grapheme always # exceeds and we return from within the loop. Type checker requires this. return idx # pragma: no cover def _find_first_grapheme_end(self, text: str) -> int: """Find the end position of the first grapheme.""" return len(next(iter_graphemes(text))) def _rstrip_visible(self, text: str) -> str: """Strip trailing visible whitespace, preserving trailing sequences.""" segments = list(iter_sequences(text)) last_vis = -1 for i, (segment, is_seq) in enumerate(segments): if not is_seq and segment.rstrip(): last_vis = i if last_vis == -1: return '' result = [] for i, (segment, is_seq) in enumerate(segments): if i < last_vis: result.append(segment) elif i == last_vis: result.append(segment.rstrip()) elif is_seq: result.append(segment) return ''.join(result) def wrap(text: str, width: int = 70, *, control_codes: Literal['parse', 'strict', 'ignore'] = 'parse', tabsize: int = 8, expand_tabs: bool = True, replace_whitespace: bool = True, ambiguous_width: int = 1, initial_indent: str = '', subsequent_indent: str = '', fix_sentence_endings: bool = False, break_long_words: bool = True, break_on_hyphens: bool = True, drop_whitespace: bool = True, max_lines: int | None = None, placeholder: str = ' [...]', propagate_sgr: bool = True) -> list[str]: r""" Wrap text to fit within given width, returning a list of wrapped lines. Like :func:`textwrap.wrap`, but measures width in display cells rather than characters, correctly handling wide characters, combining marks, and terminal escape sequences. :param text: Text to wrap, may contain terminal sequences. :param width: Maximum line width in display cells. :param control_codes: How to handle terminal sequences (see :func:`~.width`). :param tabsize: Tab stop width for tab expansion. :param expand_tabs: If True (default), tab characters are expanded to spaces using ``tabsize``. :param replace_whitespace: If True (default), each whitespace character is replaced with a single space after tab expansion. When False, control whitespace like ``\n`` has zero display width (unlike :func:`textwrap.wrap` which counts ``len()``), so wrap points may differ from stdlib for non-space whitespace characters. :param ambiguous_width: Width to use for East Asian Ambiguous (A) characters. Default is ``1`` (narrow). Set to ``2`` for CJK contexts. :param initial_indent: String prepended to first line. :param subsequent_indent: String prepended to subsequent lines. :param fix_sentence_endings: If True, ensure sentences are always separated by exactly two spaces. :param break_long_words: If True, break words longer than width. :param break_on_hyphens: If True, allow breaking at hyphens. :param drop_whitespace: If True (default), whitespace at the beginning and end of each line (after wrapping but before indenting) is dropped. Set to False to preserve whitespace. :param max_lines: If set, output contains at most this many lines, with ``placeholder`` appended to the last line if the text was truncated. :param placeholder: String appended to the last line when text is truncated by ``max_lines``. Default is ``' [...]'``. :param propagate_sgr: If True (default), SGR (terminal styling) sequences are propagated across wrapped lines. Each line ends with a reset sequence and the next line begins with the active style restored. :returns: List of wrapped lines without trailing newlines. SGR (terminal styling) sequences are propagated across wrapped lines by default. Each line ends with a reset sequence and the next line begins with the active style restored:: >>> wrap('\x1b[1;34mHello world\x1b[0m', width=6) ['\x1b[1;34mHello\x1b[0m', '\x1b[1;34mworld\x1b[0m'] Set ``propagate_sgr=False`` to disable this behavior. Like :func:`textwrap.wrap`, newlines in the input text are treated as whitespace and collapsed. To preserve paragraph breaks, wrap each paragraph separately:: >>> text = 'First line.\nSecond line.' >>> wrap(text, 40) # newline collapsed to space ['First line. Second line.'] >>> [line for para in text.split('\n') ... for line in (wrap(para, 40) if para else [''])] ['First line.', 'Second line.'] .. seealso:: :func:`textwrap.wrap`, :class:`textwrap.TextWrapper` Standard library text wrapping (character-based). :class:`.SequenceTextWrapper` Class interface for advanced wrapping options. .. versionadded:: 0.3.0 .. versionchanged:: 0.5.0 Added ``propagate_sgr`` parameter (default True). .. versionchanged:: 0.6.0 Added ``expand_tabs``, ``replace_whitespace``, ``fix_sentence_endings``, ``drop_whitespace``, ``max_lines``, and ``placeholder`` parameters. Example:: >>> from wcwidth import wrap >>> wrap('hello world', 5) ['hello', 'world'] >>> wrap('中文字符', 4) # CJK characters (2 cells each) ['中文', '字符'] """ # pylint: disable=too-many-arguments,too-many-locals wrapper = SequenceTextWrapper( width=width, control_codes=control_codes, tabsize=tabsize, expand_tabs=expand_tabs, replace_whitespace=replace_whitespace, ambiguous_width=ambiguous_width, initial_indent=initial_indent, subsequent_indent=subsequent_indent, fix_sentence_endings=fix_sentence_endings, break_long_words=break_long_words, break_on_hyphens=break_on_hyphens, drop_whitespace=drop_whitespace, max_lines=max_lines, placeholder=placeholder, ) lines = wrapper.wrap(text) if propagate_sgr: lines = _propagate_sgr(lines) return lines