@ossiq/cli-linux-x64 0.1.13 → 0.1.14

package/bin/ossiq/_internal/wcwidth/textwrap.py,cover

@@ -1,664 +0,0 @@
-> """
-> 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 secrets
-> import textwrap
-  
-> from typing import TYPE_CHECKING, Optional
-  
-  # local
-> from ._width import width as wcwidth_width
-> from .grapheme import iter_graphemes
-> from .hyperlink import HyperlinkParams
-> from .sgr_state import propagate_sgr as _propagate_sgr
-> from .escape_sequences import ZERO_WIDTH_PATTERN, iter_sequences
-  
-- if TYPE_CHECKING:  # pragma: no cover
--     from typing import Any, Literal
-  
-  
-> 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,
->                  term_program: bool | str = False,
->                  **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 term_program: Terminal software identifier for table correction.
->             ``False`` (default) disables override lookup.  ``True`` reads the
->             ``TERM_PROGRAM`` or ``TERM`` environment variable for auto-detection.
->             Accepts a canonical terminal name matching :func:`list_term_programs`,
->             such as from XTVERSION_, ENQ_, or ``TERM_PROGRAM``.
-  
->             .. versionadded:: 0.8.0
->         :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
->         self.term_program = term_program
-  
->     @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 wcwidth_width(text, control_codes=self.control_codes, tabsize=self.tabsize,
->                              ambiguous_width=self.ambiguous_width,
->                              term_program=self.term_program)
-  
->     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: Optional[HyperlinkParams] = None
-          # Track the id we're using for the current hyperlink continuation
->         current_hyperlink_id: Optional[str] = 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 = HyperlinkParams(
->                     url=hyperlink_state.url,
->                     params=hyperlink_state.params,
->                     terminator=hyperlink_state.terminator,
->                 ).make_open()
->                 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 += HyperlinkParams(
->                             terminator=new_state.terminator, url='').make_close()
-  
-                          # 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 = HyperlinkParams(
->                                 url=new_state.url,
->                                 params=new_state.params,
->                                 terminator=new_state.terminator,
->                             ).make_open()
->                             new_open = HyperlinkParams(
->                                 url=new_state.url,
->                                 params=current_hyperlink_id,
->                                 terminator=new_state.terminator,
->                             ).make_open()
->                             line_content = line_content.replace(old_open, new_open, 1)
-  
-                          # Update state for next line, using computed id
->                         hyperlink_state = HyperlinkParams(
->                             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 += HyperlinkParams(
->                                     terminator=new_state.terminator, url='').make_close()
->                             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: Optional[HyperlinkParams]) -> Optional[HyperlinkParams]:
->         """
->         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 = HyperlinkParams.parse(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)
-                  # Include first visible unit when break would take only leading sequences.
->                 if not cur_line and (
->                         actual_end == 0
->                         or (actual_end < len(chunk)
->                             and self._width(chunk[:actual_end]) == 0)):
->                     actual_end = self._find_first_visible_break(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_visible_break(self, text: str) -> int:
->         """End of leading escape sequences plus the first grapheme."""
->         idx = 0
->         while idx < len(text) and text[idx] == '\x1b':
->             match = ZERO_WIDTH_PATTERN.match(text, idx)
->             if match is None:
->                 break
->             idx = match.end()
->         if idx >= len(text):
-!             return len(text)
->         return idx + len(next(iter_graphemes(text, start=idx)))
-  
->     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,
->          term_program: bool | str = False,
->          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: Optional[int] = 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 term_program: Terminal software identifier for table correction.
->         ``False`` (default) disables override lookup.  ``True`` reads the
->         ``TERM_PROGRAM`` or ``TERM`` environment variable for auto-detection.
->         Accepts a canonical terminal name matching :func:`list_term_programs`,
->         such as from XTVERSION_, ENQ_, or ``TERM_PROGRAM``.
-  
->         .. versionadded:: 0.8.0
->     :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,
->         term_program=term_program,
->         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