venv/lib/python3.11/site-packages/pip/_vendor/rich/text.py

   1 import re
   2 from functools import partial, reduce
   3 from math import gcd
   4 from operator import itemgetter
   5 from typing import (
   6     TYPE_CHECKING,
   7     Any,
   8     Callable,
   9     Dict,
  10     Iterable,
  11     List,
  12     NamedTuple,
  13     Optional,
  14     Tuple,
  15     Union,
  16 )
  17
  18 from ._loop import loop_last
  19 from ._pick import pick_bool
  20 from ._wrap import divide_line
  21 from .align import AlignMethod
  22 from .cells import cell_len, set_cell_size
  23 from .containers import Lines
  24 from .control import strip_control_codes
  25 from .emoji import EmojiVariant
  26 from .jupyter import JupyterMixin
  27 from .measure import Measurement
  28 from .segment import Segment
  29 from .style import Style, StyleType
  30
  31 if TYPE_CHECKING:  # pragma: no cover
  32     from .console import Console, ConsoleOptions, JustifyMethod, OverflowMethod
  33
  34 DEFAULT_JUSTIFY: "JustifyMethod" = "default"
  35 DEFAULT_OVERFLOW: "OverflowMethod" = "fold"
  36
  37
  38 _re_whitespace = re.compile(r"\s+$")
  39
  40 TextType = Union[str, "Text"]
  41
  42 GetStyleCallable = Callable[[str], Optional[StyleType]]
  43
  44
  45 class Span(NamedTuple):
  46     """A marked up region in some text."""
  47
  48     start: int
  49     """Span start index."""
  50     end: int
  51     """Span end index."""
  52     style: Union[str, Style]
  53     """Style associated with the span."""
  54
  55     def __repr__(self) -> str:
  56         return f"Span({self.start}, {self.end}, {self.style!r})"
  57
  58     def __bool__(self) -> bool:
  59         return self.end > self.start
  60
  61     def split(self, offset: int) -> Tuple["Span", Optional["Span"]]:
  62         """Split a span in to 2 from a given offset."""
  63
  64         if offset < self.start:
  65             return self, None
  66         if offset >= self.end:
  67             return self, None
  68
  69         start, end, style = self
  70         span1 = Span(start, min(end, offset), style)
  71         span2 = Span(span1.end, end, style)
  72         return span1, span2
  73
  74     def move(self, offset: int) -> "Span":
  75         """Move start and end by a given offset.
  76
  77         Args:
  78             offset (int): Number of characters to add to start and end.
  79
  80         Returns:
  81             TextSpan: A new TextSpan with adjusted position.
  82         """
  83         start, end, style = self
  84         return Span(start + offset, end + offset, style)
  85
  86     def right_crop(self, offset: int) -> "Span":
  87         """Crop the span at the given offset.
  88
  89         Args:
  90             offset (int): A value between start and end.
  91
  92         Returns:
  93             Span: A new (possibly smaller) span.
  94         """
  95         start, end, style = self
  96         if offset >= end:
  97             return self
  98         return Span(start, min(offset, end), style)
  99
 100
 101 class Text(JupyterMixin):
 102     """Text with color / style.
 103
 104     Args:
 105         text (str, optional): Default unstyled text. Defaults to "".
 106         style (Union[str, Style], optional): Base style for text. Defaults to "".
 107         justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
 108         overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
 109         no_wrap (bool, optional): Disable text wrapping, or None for default. Defaults to None.
 110         end (str, optional): Character to end text with. Defaults to "\\\\n".
 111         tab_size (int): Number of spaces per tab, or ``None`` to use ``console.tab_size``. Defaults to 8.
 112         spans (List[Span], optional). A list of predefined style spans. Defaults to None.
 113     """
 114
 115     __slots__ = [
 116         "_text",
 117         "style",
 118         "justify",
 119         "overflow",
 120         "no_wrap",
 121         "end",
 122         "tab_size",
 123         "_spans",
 124         "_length",
 125     ]
 126
 127     def __init__(
 128         self,
 129         text: str = "",
 130         style: Union[str, Style] = "",
 131         *,
 132         justify: Optional["JustifyMethod"] = None,
 133         overflow: Optional["OverflowMethod"] = None,
 134         no_wrap: Optional[bool] = None,
 135         end: str = "\n",
 136         tab_size: Optional[int] = 8,
 137         spans: Optional[List[Span]] = None,
 138     ) -> None:
 139         sanitized_text = strip_control_codes(text)
 140         self._text = [sanitized_text]
 141         self.style = style
 142         self.justify: Optional["JustifyMethod"] = justify
 143         self.overflow: Optional["OverflowMethod"] = overflow
 144         self.no_wrap = no_wrap
 145         self.end = end
 146         self.tab_size = tab_size
 147         self._spans: List[Span] = spans or []
 148         self._length: int = len(sanitized_text)
 149
 150     def __len__(self) -> int:
 151         return self._length
 152
 153     def __bool__(self) -> bool:
 154         return bool(self._length)
 155
 156     def __str__(self) -> str:
 157         return self.plain
 158
 159     def __repr__(self) -> str:
 160         return f"<text {self.plain!r} {self._spans!r}>"
 161
 162     def __add__(self, other: Any) -> "Text":
 163         if isinstance(other, (str, Text)):
 164             result = self.copy()
 165             result.append(other)
 166             return result
 167         return NotImplemented
 168
 169     def __eq__(self, other: object) -> bool:
 170         if not isinstance(other, Text):
 171             return NotImplemented
 172         return self.plain == other.plain and self._spans == other._spans
 173
 174     def __contains__(self, other: object) -> bool:
 175         if isinstance(other, str):
 176             return other in self.plain
 177         elif isinstance(other, Text):
 178             return other.plain in self.plain
 179         return False
 180
 181     def __getitem__(self, slice: Union[int, slice]) -> "Text":
 182         def get_text_at(offset: int) -> "Text":
 183             _Span = Span
 184             text = Text(
 185                 self.plain[offset],
 186                 spans=[
 187                     _Span(0, 1, style)
 188                     for start, end, style in self._spans
 189                     if end > offset >= start
 190                 ],
 191                 end="",
 192             )
 193             return text
 194
 195         if isinstance(slice, int):
 196             return get_text_at(slice)
 197         else:
 198             start, stop, step = slice.indices(len(self.plain))
 199             if step == 1:
 200                 lines = self.divide([start, stop])
 201                 return lines[1]
 202             else:
 203                 # This would be a bit of work to implement efficiently
 204                 # For now, its not required
 205                 raise TypeError("slices with step!=1 are not supported")
 206
 207     @property
 208     def cell_len(self) -> int:
 209         """Get the number of cells required to render this text."""
 210         return cell_len(self.plain)
 211
 212     @property
 213     def markup(self) -> str:
 214         """Get console markup to render this Text.
 215
 216         Returns:
 217             str: A string potentially creating markup tags.
 218         """
 219         from .markup import escape
 220
 221         output: List[str] = []
 222
 223         plain = self.plain
 224         markup_spans = [
 225             (0, False, self.style),
 226             *((span.start, False, span.style) for span in self._spans),
 227             *((span.end, True, span.style) for span in self._spans),
 228             (len(plain), True, self.style),
 229         ]
 230         markup_spans.sort(key=itemgetter(0, 1))
 231         position = 0
 232         append = output.append
 233         for offset, closing, style in markup_spans:
 234             if offset > position:
 235                 append(escape(plain[position:offset]))
 236                 position = offset
 237             if style:
 238                 append(f"[/{style}]" if closing else f"[{style}]")
 239         markup = "".join(output)
 240         return markup
 241
 242     @classmethod
 243     def from_markup(
 244         cls,
 245         text: str,
 246         *,
 247         style: Union[str, Style] = "",
 248         emoji: bool = True,
 249         emoji_variant: Optional[EmojiVariant] = None,
 250         justify: Optional["JustifyMethod"] = None,
 251         overflow: Optional["OverflowMethod"] = None,
 252         end: str = "\n",
 253     ) -> "Text":
 254         """Create Text instance from markup.
 255
 256         Args:
 257             text (str): A string containing console markup.
 258             emoji (bool, optional): Also render emoji code. Defaults to True.
 259             justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
 260             overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
 261             end (str, optional): Character to end text with. Defaults to "\\\\n".
 262
 263         Returns:
 264             Text: A Text instance with markup rendered.
 265         """
 266         from .markup import render
 267
 268         rendered_text = render(text, style, emoji=emoji, emoji_variant=emoji_variant)
 269         rendered_text.justify = justify
 270         rendered_text.overflow = overflow
 271         rendered_text.end = end
 272         return rendered_text
 273
 274     @classmethod
 275     def from_ansi(
 276         cls,
 277         text: str,
 278         *,
 279         style: Union[str, Style] = "",
 280         justify: Optional["JustifyMethod"] = None,
 281         overflow: Optional["OverflowMethod"] = None,
 282         no_wrap: Optional[bool] = None,
 283         end: str = "\n",
 284         tab_size: Optional[int] = 8,
 285     ) -> "Text":
 286         """Create a Text object from a string containing ANSI escape codes.
 287
 288         Args:
 289             text (str): A string containing escape codes.
 290             style (Union[str, Style], optional): Base style for text. Defaults to "".
 291             justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
 292             overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
 293             no_wrap (bool, optional): Disable text wrapping, or None for default. Defaults to None.
 294             end (str, optional): Character to end text with. Defaults to "\\\\n".
 295             tab_size (int): Number of spaces per tab, or ``None`` to use ``console.tab_size``. Defaults to 8.
 296         """
 297         from .ansi import AnsiDecoder
 298
 299         joiner = Text(
 300             "\n",
 301             justify=justify,
 302             overflow=overflow,
 303             no_wrap=no_wrap,
 304             end=end,
 305             tab_size=tab_size,
 306             style=style,
 307         )
 308         decoder = AnsiDecoder()
 309         result = joiner.join(line for line in decoder.decode(text))
 310         return result
 311
 312     @classmethod
 313     def styled(
 314         cls,
 315         text: str,
 316         style: StyleType = "",
 317         *,
 318         justify: Optional["JustifyMethod"] = None,
 319         overflow: Optional["OverflowMethod"] = None,
 320     ) -> "Text":
 321         """Construct a Text instance with a pre-applied styled. A style applied in this way won't be used
 322         to pad the text when it is justified.
 323
 324         Args:
 325             text (str): A string containing console markup.
 326             style (Union[str, Style]): Style to apply to the text. Defaults to "".
 327             justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
 328             overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
 329
 330         Returns:
 331             Text: A text instance with a style applied to the entire string.
 332         """
 333         styled_text = cls(text, justify=justify, overflow=overflow)
 334         styled_text.stylize(style)
 335         return styled_text
 336
 337     @classmethod
 338     def assemble(
 339         cls,
 340         *parts: Union[str, "Text", Tuple[str, StyleType]],
 341         style: Union[str, Style] = "",
 342         justify: Optional["JustifyMethod"] = None,
 343         overflow: Optional["OverflowMethod"] = None,
 344         no_wrap: Optional[bool] = None,
 345         end: str = "\n",
 346         tab_size: int = 8,
 347         meta: Optional[Dict[str, Any]] = None,
 348     ) -> "Text":
 349         """Construct a text instance by combining a sequence of strings with optional styles.
 350         The positional arguments should be either strings, or a tuple of string + style.
 351
 352         Args:
 353             style (Union[str, Style], optional): Base style for text. Defaults to "".
 354             justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
 355             overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
 356             end (str, optional): Character to end text with. Defaults to "\\\\n".
 357             tab_size (int): Number of spaces per tab, or ``None`` to use ``console.tab_size``. Defaults to 8.
 358             meta (Dict[str, Any], optional). Meta data to apply to text, or None for no meta data. Default to None
 359
 360         Returns:
 361             Text: A new text instance.
 362         """
 363         text = cls(
 364             style=style,
 365             justify=justify,
 366             overflow=overflow,
 367             no_wrap=no_wrap,
 368             end=end,
 369             tab_size=tab_size,
 370         )
 371         append = text.append
 372         _Text = Text
 373         for part in parts:
 374             if isinstance(part, (_Text, str)):
 375                 append(part)
 376             else:
 377                 append(*part)
 378         if meta:
 379             text.apply_meta(meta)
 380         return text
 381
 382     @property
 383     def plain(self) -> str:
 384         """Get the text as a single string."""
 385         if len(self._text) != 1:
 386             self._text[:] = ["".join(self._text)]
 387         return self._text[0]
 388
 389     @plain.setter
 390     def plain(self, new_text: str) -> None:
 391         """Set the text to a new value."""
 392         if new_text != self.plain:
 393             sanitized_text = strip_control_codes(new_text)
 394             self._text[:] = [sanitized_text]
 395             old_length = self._length
 396             self._length = len(sanitized_text)
 397             if old_length > self._length:
 398                 self._trim_spans()
 399
 400     @property
 401     def spans(self) -> List[Span]:
 402         """Get a reference to the internal list of spans."""
 403         return self._spans
 404
 405     @spans.setter
 406     def spans(self, spans: List[Span]) -> None:
 407         """Set spans."""
 408         self._spans = spans[:]
 409
 410     def blank_copy(self, plain: str = "") -> "Text":
 411         """Return a new Text instance with copied meta data (but not the string or spans)."""
 412         copy_self = Text(
 413             plain,
 414             style=self.style,
 415             justify=self.justify,
 416             overflow=self.overflow,
 417             no_wrap=self.no_wrap,
 418             end=self.end,
 419             tab_size=self.tab_size,
 420         )
 421         return copy_self
 422
 423     def copy(self) -> "Text":
 424         """Return a copy of this instance."""
 425         copy_self = Text(
 426             self.plain,
 427             style=self.style,
 428             justify=self.justify,
 429             overflow=self.overflow,
 430             no_wrap=self.no_wrap,
 431             end=self.end,
 432             tab_size=self.tab_size,
 433         )
 434         copy_self._spans[:] = self._spans
 435         return copy_self
 436
 437     def stylize(
 438         self,
 439         style: Union[str, Style],
 440         start: int = 0,
 441         end: Optional[int] = None,
 442     ) -> None:
 443         """Apply a style to the text, or a portion of the text.
 444
 445         Args:
 446             style (Union[str, Style]): Style instance or style definition to apply.
 447             start (int): Start offset (negative indexing is supported). Defaults to 0.
 448             end (Optional[int], optional): End offset (negative indexing is supported), or None for end of text. Defaults to None.
 449         """
 450         if style:
 451             length = len(self)
 452             if start < 0:
 453                 start = length + start
 454             if end is None:
 455                 end = length
 456             if end < 0:
 457                 end = length + end
 458             if start >= length or end <= start:
 459                 # Span not in text or not valid
 460                 return
 461             self._spans.append(Span(start, min(length, end), style))
 462
 463     def stylize_before(
 464         self,
 465         style: Union[str, Style],
 466         start: int = 0,
 467         end: Optional[int] = None,
 468     ) -> None:
 469         """Apply a style to the text, or a portion of the text. Styles will be applied before other styles already present.
 470
 471         Args:
 472             style (Union[str, Style]): Style instance or style definition to apply.
 473             start (int): Start offset (negative indexing is supported). Defaults to 0.
 474             end (Optional[int], optional): End offset (negative indexing is supported), or None for end of text. Defaults to None.
 475         """
 476         if style:
 477             length = len(self)
 478             if start < 0:
 479                 start = length + start
 480             if end is None:
 481                 end = length
 482             if end < 0:
 483                 end = length + end
 484             if start >= length or end <= start:
 485                 # Span not in text or not valid
 486                 return
 487             self._spans.insert(0, Span(start, min(length, end), style))
 488
 489     def apply_meta(
 490         self, meta: Dict[str, Any], start: int = 0, end: Optional[int] = None
 491     ) -> None:
 492         """Apply meta data to the text, or a portion of the text.
 493
 494         Args:
 495             meta (Dict[str, Any]): A dict of meta information.
 496             start (int): Start offset (negative indexing is supported). Defaults to 0.
 497             end (Optional[int], optional): End offset (negative indexing is supported), or None for end of text. Defaults to None.
 498
 499         """
 500         style = Style.from_meta(meta)
 501         self.stylize(style, start=start, end=end)
 502
 503     def on(self, meta: Optional[Dict[str, Any]] = None, **handlers: Any) -> "Text":
 504         """Apply event handlers (used by Textual project).
 505
 506         Example:
 507             >>> from rich.text import Text
 508             >>> text = Text("hello world")
 509             >>> text.on(click="view.toggle('world')")
 510
 511         Args:
 512             meta (Dict[str, Any]): Mapping of meta information.
 513             **handlers: Keyword args are prefixed with "@" to defined handlers.
 514
 515         Returns:
 516             Text: Self is returned to method may be chained.
 517         """
 518         meta = {} if meta is None else meta
 519         meta.update({f"@{key}": value for key, value in handlers.items()})
 520         self.stylize(Style.from_meta(meta))
 521         return self
 522
 523     def remove_suffix(self, suffix: str) -> None:
 524         """Remove a suffix if it exists.
 525
 526         Args:
 527             suffix (str): Suffix to remove.
 528         """
 529         if self.plain.endswith(suffix):
 530             self.right_crop(len(suffix))
 531
 532     def get_style_at_offset(self, console: "Console", offset: int) -> Style:
 533         """Get the style of a character at give offset.
 534
 535         Args:
 536             console (~Console): Console where text will be rendered.
 537             offset (int): Offset in to text (negative indexing supported)
 538
 539         Returns:
 540             Style: A Style instance.
 541         """
 542         # TODO: This is a little inefficient, it is only used by full justify
 543         if offset < 0:
 544             offset = len(self) + offset
 545         get_style = console.get_style
 546         style = get_style(self.style).copy()
 547         for start, end, span_style in self._spans:
 548             if end > offset >= start:
 549                 style += get_style(span_style, default="")
 550         return style
 551
 552     def highlight_regex(
 553         self,
 554         re_highlight: str,
 555         style: Optional[Union[GetStyleCallable, StyleType]] = None,
 556         *,
 557         style_prefix: str = "",
 558     ) -> int:
 559         """Highlight text with a regular expression, where group names are
 560         translated to styles.
 561
 562         Args:
 563             re_highlight (str): A regular expression.
 564             style (Union[GetStyleCallable, StyleType]): Optional style to apply to whole match, or a callable
 565                 which accepts the matched text and returns a style. Defaults to None.
 566             style_prefix (str, optional): Optional prefix to add to style group names.
 567
 568         Returns:
 569             int: Number of regex matches
 570         """
 571         count = 0
 572         append_span = self._spans.append
 573         _Span = Span
 574         plain = self.plain
 575         for match in re.finditer(re_highlight, plain):
 576             get_span = match.span
 577             if style:
 578                 start, end = get_span()
 579                 match_style = style(plain[start:end]) if callable(style) else style
 580                 if match_style is not None and end > start:
 581                     append_span(_Span(start, end, match_style))
 582
 583             count += 1
 584             for name in match.groupdict().keys():
 585                 start, end = get_span(name)
 586                 if start != -1 and end > start:
 587                     append_span(_Span(start, end, f"{style_prefix}{name}"))
 588         return count
 589
 590     def highlight_words(
 591         self,
 592         words: Iterable[str],
 593         style: Union[str, Style],
 594         *,
 595         case_sensitive: bool = True,
 596     ) -> int:
 597         """Highlight words with a style.
 598
 599         Args:
 600             words (Iterable[str]): Worlds to highlight.
 601             style (Union[str, Style]): Style to apply.
 602             case_sensitive (bool, optional): Enable case sensitive matchings. Defaults to True.
 603
 604         Returns:
 605             int: Number of words highlighted.
 606         """
 607         re_words = "|".join(re.escape(word) for word in words)
 608         add_span = self._spans.append
 609         count = 0
 610         _Span = Span
 611         for match in re.finditer(
 612             re_words, self.plain, flags=0 if case_sensitive else re.IGNORECASE
 613         ):
 614             start, end = match.span(0)
 615             add_span(_Span(start, end, style))
 616             count += 1
 617         return count
 618
 619     def rstrip(self) -> None:
 620         """Strip whitespace from end of text."""
 621         self.plain = self.plain.rstrip()
 622
 623     def rstrip_end(self, size: int) -> None:
 624         """Remove whitespace beyond a certain width at the end of the text.
 625
 626         Args:
 627             size (int): The desired size of the text.
 628         """
 629         text_length = len(self)
 630         if text_length > size:
 631             excess = text_length - size
 632             whitespace_match = _re_whitespace.search(self.plain)
 633             if whitespace_match is not None:
 634                 whitespace_count = len(whitespace_match.group(0))
 635                 self.right_crop(min(whitespace_count, excess))
 636
 637     def set_length(self, new_length: int) -> None:
 638         """Set new length of the text, clipping or padding is required."""
 639         length = len(self)
 640         if length != new_length:
 641             if length < new_length:
 642                 self.pad_right(new_length - length)
 643             else:
 644                 self.right_crop(length - new_length)
 645
 646     def __rich_console__(
 647         self, console: "Console", options: "ConsoleOptions"
 648     ) -> Iterable[Segment]:
 649         tab_size: int = console.tab_size or self.tab_size or 8
 650         justify = self.justify or options.justify or DEFAULT_JUSTIFY
 651
 652         overflow = self.overflow or options.overflow or DEFAULT_OVERFLOW
 653
 654         lines = self.wrap(
 655             console,
 656             options.max_width,
 657             justify=justify,
 658             overflow=overflow,
 659             tab_size=tab_size or 8,
 660             no_wrap=pick_bool(self.no_wrap, options.no_wrap, False),
 661         )
 662         all_lines = Text("\n").join(lines)
 663         yield from all_lines.render(console, end=self.end)
 664
 665     def __rich_measure__(
 666         self, console: "Console", options: "ConsoleOptions"
 667     ) -> Measurement:
 668         text = self.plain
 669         lines = text.splitlines()
 670         max_text_width = max(cell_len(line) for line in lines) if lines else 0
 671         words = text.split()
 672         min_text_width = (
 673             max(cell_len(word) for word in words) if words else max_text_width
 674         )
 675         return Measurement(min_text_width, max_text_width)
 676
 677     def render(self, console: "Console", end: str = "") -> Iterable["Segment"]:
 678         """Render the text as Segments.
 679
 680         Args:
 681             console (Console): Console instance.
 682             end (Optional[str], optional): Optional end character.
 683
 684         Returns:
 685             Iterable[Segment]: Result of render that may be written to the console.
 686         """
 687         _Segment = Segment
 688         text = self.plain
 689         if not self._spans:
 690             yield Segment(text)
 691             if end:
 692                 yield _Segment(end)
 693             return
 694         get_style = partial(console.get_style, default=Style.null())
 695
 696         enumerated_spans = list(enumerate(self._spans, 1))
 697         style_map = {index: get_style(span.style) for index, span in enumerated_spans}
 698         style_map[0] = get_style(self.style)
 699
 700         spans = [
 701             (0, False, 0),
 702             *((span.start, False, index) for index, span in enumerated_spans),
 703             *((span.end, True, index) for index, span in enumerated_spans),
 704             (len(text), True, 0),
 705         ]
 706         spans.sort(key=itemgetter(0, 1))
 707
 708         stack: List[int] = []
 709         stack_append = stack.append
 710         stack_pop = stack.remove
 711
 712         style_cache: Dict[Tuple[Style, ...], Style] = {}
 713         style_cache_get = style_cache.get
 714         combine = Style.combine
 715
 716         def get_current_style() -> Style:
 717             """Construct current style from stack."""
 718             styles = tuple(style_map[_style_id] for _style_id in sorted(stack))
 719             cached_style = style_cache_get(styles)
 720             if cached_style is not None:
 721                 return cached_style
 722             current_style = combine(styles)
 723             style_cache[styles] = current_style
 724             return current_style
 725
 726         for (offset, leaving, style_id), (next_offset, _, _) in zip(spans, spans[1:]):
 727             if leaving:
 728                 stack_pop(style_id)
 729             else:
 730                 stack_append(style_id)
 731             if next_offset > offset:
 732                 yield _Segment(text[offset:next_offset], get_current_style())
 733         if end:
 734             yield _Segment(end)
 735
 736     def join(self, lines: Iterable["Text"]) -> "Text":
 737         """Join text together with this instance as the separator.
 738
 739         Args:
 740             lines (Iterable[Text]): An iterable of Text instances to join.
 741
 742         Returns:
 743             Text: A new text instance containing join text.
 744         """
 745
 746         new_text = self.blank_copy()
 747
 748         def iter_text() -> Iterable["Text"]:
 749             if self.plain:
 750                 for last, line in loop_last(lines):
 751                     yield line
 752                     if not last:
 753                         yield self
 754             else:
 755                 yield from lines
 756
 757         extend_text = new_text._text.extend
 758         append_span = new_text._spans.append
 759         extend_spans = new_text._spans.extend
 760         offset = 0
 761         _Span = Span
 762
 763         for text in iter_text():
 764             extend_text(text._text)
 765             if text.style:
 766                 append_span(_Span(offset, offset + len(text), text.style))
 767             extend_spans(
 768                 _Span(offset + start, offset + end, style)
 769                 for start, end, style in text._spans
 770             )
 771             offset += len(text)
 772         new_text._length = offset
 773         return new_text
 774
 775     def expand_tabs(self, tab_size: Optional[int] = None) -> None:
 776         """Converts tabs to spaces.
 777
 778         Args:
 779             tab_size (int, optional): Size of tabs. Defaults to 8.
 780
 781         """
 782         if "\t" not in self.plain:
 783             return
 784         pos = 0
 785         if tab_size is None:
 786             tab_size = self.tab_size
 787         assert tab_size is not None
 788         result = self.blank_copy()
 789         append = result.append
 790
 791         _style = self.style
 792         for line in self.split("\n", include_separator=True):
 793             parts = line.split("\t", include_separator=True)
 794             for part in parts:
 795                 if part.plain.endswith("\t"):
 796                     part._text = [part.plain[:-1] + " "]
 797                     append(part)
 798                     pos += len(part)
 799                     spaces = tab_size - ((pos - 1) % tab_size) - 1
 800                     if spaces:
 801                         append(" " * spaces, _style)
 802                         pos += spaces
 803                 else:
 804                     append(part)
 805         self._text = [result.plain]
 806         self._length = len(self.plain)
 807         self._spans[:] = result._spans
 808
 809     def truncate(
 810         self,
 811         max_width: int,
 812         *,
 813         overflow: Optional["OverflowMethod"] = None,
 814         pad: bool = False,
 815     ) -> None:
 816         """Truncate text if it is longer that a given width.
 817
 818         Args:
 819             max_width (int): Maximum number of characters in text.
 820             overflow (str, optional): Overflow method: "crop", "fold", or "ellipsis". Defaults to None, to use self.overflow.
 821             pad (bool, optional): Pad with spaces if the length is less than max_width. Defaults to False.
 822         """
 823         _overflow = overflow or self.overflow or DEFAULT_OVERFLOW
 824         if _overflow != "ignore":
 825             length = cell_len(self.plain)
 826             if length > max_width:
 827                 if _overflow == "ellipsis":
 828                     self.plain = set_cell_size(self.plain, max_width - 1) + "…"
 829                 else:
 830                     self.plain = set_cell_size(self.plain, max_width)
 831             if pad and length < max_width:
 832                 spaces = max_width - length
 833                 self._text = [f"{self.plain}{' ' * spaces}"]
 834                 self._length = len(self.plain)
 835
 836     def _trim_spans(self) -> None:
 837         """Remove or modify any spans that are over the end of the text."""
 838         max_offset = len(self.plain)
 839         _Span = Span
 840         self._spans[:] = [
 841             (
 842                 span
 843                 if span.end < max_offset
 844                 else _Span(span.start, min(max_offset, span.end), span.style)
 845             )
 846             for span in self._spans
 847             if span.start < max_offset
 848         ]
 849
 850     def pad(self, count: int, character: str = " ") -> None:
 851         """Pad left and right with a given number of characters.
 852
 853         Args:
 854             count (int): Width of padding.
 855         """
 856         assert len(character) == 1, "Character must be a string of length 1"
 857         if count:
 858             pad_characters = character * count
 859             self.plain = f"{pad_characters}{self.plain}{pad_characters}"
 860             _Span = Span
 861             self._spans[:] = [
 862                 _Span(start + count, end + count, style)
 863                 for start, end, style in self._spans
 864             ]
 865
 866     def pad_left(self, count: int, character: str = " ") -> None:
 867         """Pad the left with a given character.
 868
 869         Args:
 870             count (int): Number of characters to pad.
 871             character (str, optional): Character to pad with. Defaults to " ".
 872         """
 873         assert len(character) == 1, "Character must be a string of length 1"
 874         if count:
 875             self.plain = f"{character * count}{self.plain}"
 876             _Span = Span
 877             self._spans[:] = [
 878                 _Span(start + count, end + count, style)
 879                 for start, end, style in self._spans
 880             ]
 881
 882     def pad_right(self, count: int, character: str = " ") -> None:
 883         """Pad the right with a given character.
 884
 885         Args:
 886             count (int): Number of characters to pad.
 887             character (str, optional): Character to pad with. Defaults to " ".
 888         """
 889         assert len(character) == 1, "Character must be a string of length 1"
 890         if count:
 891             self.plain = f"{self.plain}{character * count}"
 892
 893     def align(self, align: AlignMethod, width: int, character: str = " ") -> None:
 894         """Align text to a given width.
 895
 896         Args:
 897             align (AlignMethod): One of "left", "center", or "right".
 898             width (int): Desired width.
 899             character (str, optional): Character to pad with. Defaults to " ".
 900         """
 901         self.truncate(width)
 902         excess_space = width - cell_len(self.plain)
 903         if excess_space:
 904             if align == "left":
 905                 self.pad_right(excess_space, character)
 906             elif align == "center":
 907                 left = excess_space // 2
 908                 self.pad_left(left, character)
 909                 self.pad_right(excess_space - left, character)
 910             else:
 911                 self.pad_left(excess_space, character)
 912
 913     def append(
 914         self, text: Union["Text", str], style: Optional[Union[str, "Style"]] = None
 915     ) -> "Text":
 916         """Add text with an optional style.
 917
 918         Args:
 919             text (Union[Text, str]): A str or Text to append.
 920             style (str, optional): A style name. Defaults to None.
 921
 922         Returns:
 923             Text: Returns self for chaining.
 924         """
 925
 926         if not isinstance(text, (str, Text)):
 927             raise TypeError("Only str or Text can be appended to Text")
 928
 929         if len(text):
 930             if isinstance(text, str):
 931                 sanitized_text = strip_control_codes(text)
 932                 self._text.append(sanitized_text)
 933                 offset = len(self)
 934                 text_length = len(sanitized_text)
 935                 if style is not None:
 936                     self._spans.append(Span(offset, offset + text_length, style))
 937                 self._length += text_length
 938             elif isinstance(text, Text):
 939                 _Span = Span
 940                 if style is not None:
 941                     raise ValueError(
 942                         "style must not be set when appending Text instance"
 943                     )
 944                 text_length = self._length
 945                 if text.style is not None:
 946                     self._spans.append(
 947                         _Span(text_length, text_length + len(text), text.style)
 948                     )
 949                 self._text.append(text.plain)
 950                 self._spans.extend(
 951                     _Span(start + text_length, end + text_length, style)
 952                     for start, end, style in text._spans
 953                 )
 954                 self._length += len(text)
 955         return self
 956
 957     def append_text(self, text: "Text") -> "Text":
 958         """Append another Text instance. This method is more performant that Text.append, but
 959         only works for Text.
 960
 961         Returns:
 962             Text: Returns self for chaining.
 963         """
 964         _Span = Span
 965         text_length = self._length
 966         if text.style is not None:
 967             self._spans.append(_Span(text_length, text_length + len(text), text.style))
 968         self._text.append(text.plain)
 969         self._spans.extend(
 970             _Span(start + text_length, end + text_length, style)
 971             for start, end, style in text._spans
 972         )
 973         self._length += len(text)
 974         return self
 975
 976     def append_tokens(
 977         self, tokens: Iterable[Tuple[str, Optional[StyleType]]]
 978     ) -> "Text":
 979         """Append iterable of str and style. Style may be a Style instance or a str style definition.
 980
 981         Args:
 982             pairs (Iterable[Tuple[str, Optional[StyleType]]]): An iterable of tuples containing str content and style.
 983
 984         Returns:
 985             Text: Returns self for chaining.
 986         """
 987         append_text = self._text.append
 988         append_span = self._spans.append
 989         _Span = Span
 990         offset = len(self)
 991         for content, style in tokens:
 992             append_text(content)
 993             if style is not None:
 994                 append_span(_Span(offset, offset + len(content), style))
 995             offset += len(content)
 996         self._length = offset
 997         return self
 998
 999     def copy_styles(self, text: "Text") -> None:
1000         """Copy styles from another Text instance.
1001
1002         Args:
1003             text (Text): A Text instance to copy styles from, must be the same length.
1004         """
1005         self._spans.extend(text._spans)
1006
1007     def split(
1008         self,
1009         separator: str = "\n",
1010         *,
1011         include_separator: bool = False,
1012         allow_blank: bool = False,
1013     ) -> Lines:
1014         """Split rich text in to lines, preserving styles.
1015
1016         Args:
1017             separator (str, optional): String to split on. Defaults to "\\\\n".
1018             include_separator (bool, optional): Include the separator in the lines. Defaults to False.
1019             allow_blank (bool, optional): Return a blank line if the text ends with a separator. Defaults to False.
1020
1021         Returns:
1022             List[RichText]: A list of rich text, one per line of the original.
1023         """
1024         assert separator, "separator must not be empty"
1025
1026         text = self.plain
1027         if separator not in text:
1028             return Lines([self.copy()])
1029
1030         if include_separator:
1031             lines = self.divide(
1032                 match.end() for match in re.finditer(re.escape(separator), text)
1033             )
1034         else:
1035
1036             def flatten_spans() -> Iterable[int]:
1037                 for match in re.finditer(re.escape(separator), text):
1038                     start, end = match.span()
1039                     yield start
1040                     yield end
1041
1042             lines = Lines(
1043                 line for line in self.divide(flatten_spans()) if line.plain != separator
1044             )
1045
1046         if not allow_blank and text.endswith(separator):
1047             lines.pop()
1048
1049         return lines
1050
1051     def divide(self, offsets: Iterable[int]) -> Lines:
1052         """Divide text in to a number of lines at given offsets.
1053
1054         Args:
1055             offsets (Iterable[int]): Offsets used to divide text.
1056
1057         Returns:
1058             Lines: New RichText instances between offsets.
1059         """
1060         _offsets = list(offsets)
1061
1062         if not _offsets:
1063             return Lines([self.copy()])
1064
1065         text = self.plain
1066         text_length = len(text)
1067         divide_offsets = [0, *_offsets, text_length]
1068         line_ranges = list(zip(divide_offsets, divide_offsets[1:]))
1069
1070         style = self.style
1071         justify = self.justify
1072         overflow = self.overflow
1073         _Text = Text
1074         new_lines = Lines(
1075             _Text(
1076                 text[start:end],
1077                 style=style,
1078                 justify=justify,
1079                 overflow=overflow,
1080             )
1081             for start, end in line_ranges
1082         )
1083         if not self._spans:
1084             return new_lines
1085
1086         _line_appends = [line._spans.append for line in new_lines._lines]
1087         line_count = len(line_ranges)
1088         _Span = Span
1089
1090         for span_start, span_end, style in self._spans:
1091
1092             lower_bound = 0
1093             upper_bound = line_count
1094             start_line_no = (lower_bound + upper_bound) // 2
1095
1096             while True:
1097                 line_start, line_end = line_ranges[start_line_no]
1098                 if span_start < line_start:
1099                     upper_bound = start_line_no - 1
1100                 elif span_start > line_end:
1101                     lower_bound = start_line_no + 1
1102                 else:
1103                     break
1104                 start_line_no = (lower_bound + upper_bound) // 2
1105
1106             if span_end < line_end:
1107                 end_line_no = start_line_no
1108             else:
1109                 end_line_no = lower_bound = start_line_no
1110                 upper_bound = line_count
1111
1112                 while True:
1113                     line_start, line_end = line_ranges[end_line_no]
1114                     if span_end < line_start:
1115                         upper_bound = end_line_no - 1
1116                     elif span_end > line_end:
1117                         lower_bound = end_line_no + 1
1118                     else:
1119                         break
1120                     end_line_no = (lower_bound + upper_bound) // 2
1121
1122             for line_no in range(start_line_no, end_line_no + 1):
1123                 line_start, line_end = line_ranges[line_no]
1124                 new_start = max(0, span_start - line_start)
1125                 new_end = min(span_end - line_start, line_end - line_start)
1126                 if new_end > new_start:
1127                     _line_appends[line_no](_Span(new_start, new_end, style))
1128
1129         return new_lines
1130
1131     def right_crop(self, amount: int = 1) -> None:
1132         """Remove a number of characters from the end of the text."""
1133         max_offset = len(self.plain) - amount
1134         _Span = Span
1135         self._spans[:] = [
1136             (
1137                 span
1138                 if span.end < max_offset
1139                 else _Span(span.start, min(max_offset, span.end), span.style)
1140             )
1141             for span in self._spans
1142             if span.start < max_offset
1143         ]
1144         self._text = [self.plain[:-amount]]
1145         self._length -= amount
1146
1147     def wrap(
1148         self,
1149         console: "Console",
1150         width: int,
1151         *,
1152         justify: Optional["JustifyMethod"] = None,
1153         overflow: Optional["OverflowMethod"] = None,
1154         tab_size: int = 8,
1155         no_wrap: Optional[bool] = None,
1156     ) -> Lines:
1157         """Word wrap the text.
1158
1159         Args:
1160             console (Console): Console instance.
1161             width (int): Number of characters per line.
1162             emoji (bool, optional): Also render emoji code. Defaults to True.
1163             justify (str, optional): Justify method: "default", "left", "center", "full", "right". Defaults to "default".
1164             overflow (str, optional): Overflow method: "crop", "fold", or "ellipsis". Defaults to None.
1165             tab_size (int, optional): Default tab size. Defaults to 8.
1166             no_wrap (bool, optional): Disable wrapping, Defaults to False.
1167
1168         Returns:
1169             Lines: Number of lines.
1170         """
1171         wrap_justify = justify or self.justify or DEFAULT_JUSTIFY
1172         wrap_overflow = overflow or self.overflow or DEFAULT_OVERFLOW
1173
1174         no_wrap = pick_bool(no_wrap, self.no_wrap, False) or overflow == "ignore"
1175
1176         lines = Lines()
1177         for line in self.split(allow_blank=True):
1178             if "\t" in line:
1179                 line.expand_tabs(tab_size)
1180             if no_wrap:
1181                 new_lines = Lines([line])
1182             else:
1183                 offsets = divide_line(str(line), width, fold=wrap_overflow == "fold")
1184                 new_lines = line.divide(offsets)
1185             for line in new_lines:
1186                 line.rstrip_end(width)
1187             if wrap_justify:
1188                 new_lines.justify(
1189                     console, width, justify=wrap_justify, overflow=wrap_overflow
1190                 )
1191             for line in new_lines:
1192                 line.truncate(width, overflow=wrap_overflow)
1193             lines.extend(new_lines)
1194         return lines
1195
1196     def fit(self, width: int) -> Lines:
1197         """Fit the text in to given width by chopping in to lines.
1198
1199         Args:
1200             width (int): Maximum characters in a line.
1201
1202         Returns:
1203             Lines: Lines container.
1204         """
1205         lines: Lines = Lines()
1206         append = lines.append
1207         for line in self.split():
1208             line.set_length(width)
1209             append(line)
1210         return lines
1211
1212     def detect_indentation(self) -> int:
1213         """Auto-detect indentation of code.
1214
1215         Returns:
1216             int: Number of spaces used to indent code.
1217         """
1218
1219         _indentations = {
1220             len(match.group(1))
1221             for match in re.finditer(r"^( *)(.*)$", self.plain, flags=re.MULTILINE)
1222         }
1223
1224         try:
1225             indentation = (
1226                 reduce(gcd, [indent for indent in _indentations if not indent % 2]) or 1
1227             )
1228         except TypeError:
1229             indentation = 1
1230
1231         return indentation
1232
1233     def with_indent_guides(
1234         self,
1235         indent_size: Optional[int] = None,
1236         *,
1237         character: str = "│",
1238         style: StyleType = "dim green",
1239     ) -> "Text":
1240         """Adds indent guide lines to text.
1241
1242         Args:
1243             indent_size (Optional[int]): Size of indentation, or None to auto detect. Defaults to None.
1244             character (str, optional): Character to use for indentation. Defaults to "│".
1245             style (Union[Style, str], optional): Style of indent guides.
1246
1247         Returns:
1248             Text: New text with indentation guides.
1249         """
1250
1251         _indent_size = self.detect_indentation() if indent_size is None else indent_size
1252
1253         text = self.copy()
1254         text.expand_tabs()
1255         indent_line = f"{character}{' ' * (_indent_size - 1)}"
1256
1257         re_indent = re.compile(r"^( *)(.*)$")
1258         new_lines: List[Text] = []
1259         add_line = new_lines.append
1260         blank_lines = 0
1261         for line in text.split(allow_blank=True):
1262             match = re_indent.match(line.plain)
1263             if not match or not match.group(2):
1264                 blank_lines += 1
1265                 continue
1266             indent = match.group(1)
1267             full_indents, remaining_space = divmod(len(indent), _indent_size)
1268             new_indent = f"{indent_line * full_indents}{' ' * remaining_space}"
1269             line.plain = new_indent + line.plain[len(new_indent) :]
1270             line.stylize(style, 0, len(new_indent))
1271             if blank_lines:
1272                 new_lines.extend([Text(new_indent, style=style)] * blank_lines)
1273                 blank_lines = 0
1274             add_line(line)
1275         if blank_lines:
1276             new_lines.extend([Text("", style=style)] * blank_lines)
1277
1278         new_text = text.blank_copy("\n").join(new_lines)
1279         return new_text
1280
1281
1282 if __name__ == "__main__":  # pragma: no cover
1283     from pip._vendor.rich.console import Console
1284
1285     text = Text(
1286         """\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"""
1287     )
1288     text.highlight_words(["Lorem"], "bold")
1289     text.highlight_words(["ipsum"], "italic")
1290
1291     console = Console()
1292
1293     console.rule("justify='left'")
1294     console.print(text, style="red")
1295     console.print()
1296
1297     console.rule("justify='center'")
1298     console.print(text, style="green", justify="center")
1299     console.print()
1300
1301     console.rule("justify='right'")
1302     console.print(text, style="blue", justify="right")
1303     console.print()
1304
1305     console.rule("justify='full'")
1306     console.print(text, style="magenta", justify="full")
1307     console.print()