daniel/tamigo-cli
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 4 Wiki Activity

Initial commit: Tamigo CLI with Gitea Actions and global installation support

Browse Source
This commit is contained in:
Daniel Dybing
2026-03-11 12:07:08 +01:00
commit 146b79660d
2675 changed files with 462625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

656
venv/lib/python3.12/site-packages/wcwidth/textwrap.py Normal file
View File

@@ -0,0 +1,656 @@
"""
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