2 # -*- coding: utf-8 -*-
4 # © Copyright 2021-2023, Scott Gasch
7 Utilities for dealing with and creating text chunks. For example:
9 - Make a bar graph / progress graph,
11 - left, right, center, justify text,
13 - indent / dedent text,
14 - create a header line,
15 - draw a box around some text.
26 from collections import defaultdict
27 from dataclasses import dataclass
28 from typing import Dict, Generator, List, Literal, Optional, Tuple, Union
30 from pyutils import string_utils
31 from pyutils.ansi import fg, reset
33 logger = logging.getLogger(__file__)
44 """Number of columns"""
47 def get_console_rows_columns() -> RowsColumns:
50 The number of rows/columns on the current console or None
51 if we can't tell or an error occurred.
54 Exception: if the console size can't be determined.
56 from pyutils.exec_utils import cmd
58 rows: Union[Optional[str], int] = os.environ.get("LINES", None)
59 cols: Union[Optional[str], int] = os.environ.get("COLUMNS", None)
60 if not rows or not cols:
62 size = os.get_terminal_size()
69 if not rows or not cols:
70 logger.debug("Rows: %s, cols: %s, trying stty.", rows, cols)
80 if not rows or not cols:
81 raise Exception("Can't determine console size?!")
82 return RowsColumns(int(rows), int(cols))
85 class BarGraphText(enum.Enum):
86 """What kind of text to include at the end of the bar graph?"""
89 """None, leave it blank."""
103 text: BarGraphText = BarGraphText.PERCENTAGE,
104 fgcolor: str = fg("school bus yellow"),
106 right_end: str = "]",
109 """Draws a progress graph at the current cursor position.
112 current: how many have we done so far?
113 total: how many are there to do total?
114 text: how should we render the text at the end?
115 width: how many columns wide should be progress graph be?
116 fgcolor: what color should "done" part of the graph be?
117 left_end: the character at the left side of the graph
118 right_end: the character at the right side of the graph
119 redraw: if True, omit a line feed after the carriage return
120 so that subsequent calls to this method redraw the graph
123 See also :meth:`bar_graph_string`, :meth:`sparkline`.
127 '[███████████████████████████████████ ] 0.5'
130 ret = "\r" if redraw else "\n"
131 bar = bar_graph_string(
140 print(bar, end=ret, flush=True, file=sys.stderr)
143 def _make_bar_graph_text(
144 text: BarGraphText, current: int, total: int, percentage: float
146 if text == BarGraphText.NONE:
148 elif text == BarGraphText.PERCENTAGE:
149 return f"{percentage:.1f}"
150 elif text == BarGraphText.FRACTION:
151 return f"{current} / {total}"
152 raise ValueError(text)
155 def bar_graph_string(
159 text: BarGraphText = BarGraphText.PERCENTAGE,
161 fgcolor: str = fg("school bus yellow"),
162 reset_seq: str = reset(),
164 right_end: str = "]",
166 """Returns a string containing a bar graph.
169 current: how many have we done so far?
170 total: how many are there to do total?
171 text: how should we render the text at the end?
172 width: how many columns wide should be progress graph be?
173 fgcolor: what color should "done" part of the graph be?
174 reset_seq: sequence to use to turn off color
175 left_end: the character at the left side of the graph
176 right_end: the character at the right side of the graph
179 ValueError: if percentage is invalid
181 See also :meth:`bar_graph`, :meth:`sparkline`.
183 >>> bar_graph_string(5, 10, fgcolor='', reset_seq='')
184 '[███████████████████████████████████ ] 0.5'
189 percentage = float(current) / float(total)
192 if percentage < 0.0 or percentage > 1.0:
193 raise ValueError(percentage)
194 txt = _make_bar_graph_text(text, current, total, percentage)
195 whole_width = math.floor(percentage * width)
196 if whole_width == width:
199 elif whole_width == 0 and percentage > 0.0:
202 remainder_width = (percentage * width) % 1
203 part_width = math.floor(remainder_width * 8)
204 part_char = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉"][part_width]
210 + " " * (width - whole_width - 1)
218 def sparkline(numbers: List[float]) -> Tuple[float, float, str]:
220 Makes a "sparkline" little inline histogram graph. Auto scales.
223 numbers: the population over which to create the sparkline
226 a three tuple containing:
228 * the minimum number in the population
229 * the maximum number in the population
230 * a string representation of the population in a concise format
232 See also :meth:`bar_graph`, :meth:`bar_graph_string`.
234 >>> sparkline([1, 2, 3, 5, 10, 3, 5, 7])
237 >>> sparkline([104, 99, 93, 96, 82, 77, 85, 73])
238 (73, 104, '█▇▆▆▃▂▄▁')
241 _bar = "▁▂▃▄▅▆▇█" # Unicode: 9601, 9602, 9603, 9604, 9605, 9606, 9607, 9608
244 min_num, max_num = min(numbers), max(numbers)
245 span = max_num - min_num
247 _bar[min([barcount - 1, int((n - min_num) / span * barcount)])] for n in numbers
249 return min_num, max_num, sline
252 def distribute_strings(
259 Distributes strings into a line for justified text.
262 strings: a list of string tokens to distribute
263 width: the width of the line to create
264 padding: the padding character to place between string chunks
267 The distributed, justified string.
269 See also :meth:`justify_string`, :meth:`justify_text`.
271 >>> distribute_strings(['this', 'is', 'a', 'test'], width=40)
274 ret = " " + " ".join(strings) + " "
275 assert len(string_utils.strip_ansi_sequences(ret)) < width
277 while len(string_utils.strip_ansi_sequences(ret)) < width:
278 spaces = [m.start() for m in re.finditer(r" ([^ ]|$)", ret)]
282 ret = before + padding + after
289 def _justify_string_by_chunk(string: str, width: int = 80, padding: str = " ") -> str:
291 Justifies a string chunk by chunk.
294 string: the string to be justified
295 width: how wide to make the output
296 padding: what padding character to use between chunks
301 >>> _justify_string_by_chunk("This is a test", 40)
303 >>> _justify_string_by_chunk("This is a test", 20)
307 assert len(string_utils.strip_ansi_sequences(string)) <= width
309 first, *rest, last = string.split()
311 len(string_utils.strip_ansi_sequences(first))
312 + len(string_utils.strip_ansi_sequences(last))
314 ret = first + distribute_strings(rest, width=w, padding=padding) + last
319 string: str, *, width: int = 80, alignment: str = "c", padding: str = " "
321 """Justify a string to width with left, right, center of justified
325 string: the string to justify
326 width: the width to justify the string to
327 alignment: a single character indicating the desired alignment:
328 * 'c' = centered within the width
329 * 'j' = justified at width
330 * 'l' = left alignment
331 * 'r' = right alignment
332 padding: the padding character to use while justifying
335 ValueError: if alignment argument is invalid.
337 >>> justify_string('This is another test', width=40, alignment='c')
338 ' This is another test '
339 >>> justify_string('This is another test', width=40, alignment='l')
340 'This is another test '
341 >>> justify_string('This is another test', width=40, alignment='r')
342 ' This is another test'
343 >>> justify_string('This is another test', width=40, alignment='j')
344 'This is another test'
346 alignment = alignment[0]
348 while len(string_utils.strip_ansi_sequences(string)) < width:
351 elif alignment == "r":
352 string = padding + string
353 elif alignment == "j":
354 return _justify_string_by_chunk(string, width=width, padding=padding)
355 elif alignment == "c":
356 if len(string) % 2 == 0:
359 string = padding + string
361 raise ValueError('alignment must be l, r, j, or c.')
366 text: str, *, width: int = 80, alignment: str = "c", indent_by: int = 0
368 """Justifies text with left, right, centered or justified alignment
369 and optionally with initial indentation.
372 text: the text to be justified
373 width: the width at which to justify text
374 alignment: a single character indicating the desired alignment:
375 * 'c' = centered within the width
376 * 'j' = justified at width
377 * 'l' = left alignment
378 * 'r' = right alignment
379 indent_by: if non-zero, adds n prefix spaces to indent the text.
384 See also :meth:`justify_text`.
386 >>> justify_text('This is a test of the emergency broadcast system. This is only a test.',
387 ... width=40, alignment='j') #doctest: +NORMALIZE_WHITESPACE
388 'This is a test of the emergency\\nbroadcast system. This is only a test.'
394 indent += " " * indent_by
397 for word in text.split():
399 len(string_utils.strip_ansi_sequences(line))
400 + len(string_utils.strip_ansi_sequences(word))
403 line = justify_string(line, width=width, alignment=alignment)
404 retval = retval + "\n" + line
406 line = line + " " + word
407 if len(string_utils.strip_ansi_sequences(line)) > 0:
409 retval += "\n" + justify_string(line[1:], width=width, alignment=alignment)
411 retval += "\n" + line[1:]
415 def generate_padded_columns(text: List[str]) -> Generator:
416 """Given a list of strings, break them into columns using :meth:`split`
417 and then compute the maximum width of each column. Finally,
418 distribute the columular chunks into the output padding each to
422 text: a list of strings to chunk into padded columns
425 padded columns based on text.split()
427 >>> for x in generate_padded_columns(
428 ... [ 'reading writing arithmetic',
429 ... 'mathematics psychology physics',
430 ... 'communications sociology anthropology' ]):
432 reading writing arithmetic
433 mathematics psychology physics
434 communications sociology anthropology
436 max_width: Dict[int, int] = defaultdict(int)
438 for pos, word in enumerate(line.split()):
439 max_width[pos] = max(
440 max_width[pos], len(string_utils.strip_ansi_sequences(word))
445 for pos, word in enumerate(line.split()):
446 width = max_width[pos]
447 word = justify_string(word, width=width, alignment="l")
452 def wrap_string(text: str, n: int) -> str:
455 text: the string to be wrapped
456 n: the width after which to wrap text
459 The wrapped form of text
461 chunks = text.split()
465 if width + len(string_utils.strip_ansi_sequences(chunk)) > n:
469 width += len(string_utils.strip_ansi_sequences(chunk)) + 1
473 class Indenter(contextlib.AbstractContextManager):
475 Context manager that indents stuff (even recursively). e.g.::
477 with Indenter(pad_count = 8) as i:
494 pad_prefix: Optional[str] = None,
498 """Construct an Indenter.
501 pad_prefix: an optional prefix to prepend to each line
502 pad_char: the character used to indent
503 pad_count: the number of pad_chars to use to indent
506 if pad_prefix is not None:
507 self.pad_prefix = pad_prefix
510 self.padding = pad_char * pad_count
516 def __exit__(self, exc_type, exc_value, exc_tb) -> Literal[False]:
522 def print(self, *arg, **kwargs):
523 text = string_utils._sprintf(*arg, **kwargs)
524 print(self.pad_prefix + self.padding * self.level + text, end="")
530 width: Optional[int] = None,
531 align: Optional[str] = None,
532 style: Optional[str] = "solid",
533 color: Optional[str] = None,
536 Creates a nice header line with a title.
540 width: how wide to make the header
541 align: "left" or "right"
542 style: "ascii", "solid" or "dashed"
543 color: what color to use, if any
546 The header as a string.
548 >>> header('title', width=60, style='ascii')
549 '----[ title ]-----------------------------------------------'
553 width = get_console_rows_columns().columns
561 text_len = len(string_utils.strip_ansi_sequences(title))
564 right = width - (left + text_len + 4)
565 elif align == "right":
567 left = width - (right + text_len + 4)
569 left = int((width - (text_len + 4)) / 2)
571 while left + text_len + 4 + right < width:
578 elif style == "dashed":
606 title: Optional[str] = None,
607 text: Optional[str] = None,
613 Make a nice unicode box (optionally with color) around some text.
616 title: the title of the box
617 text: the text in the box
618 width: the box's width
619 color: the box's color
624 See also :meth:`print_box`, :meth:`preformatted_box`.
626 >>> print(box('title', 'this is some text', width=20).strip())
636 text = justify_text(text, width=width - 4, alignment="l")
637 return preformatted_box(title, text, width=width, color=color)
640 def preformatted_box(
641 title: Optional[str] = None,
642 text: Optional[str] = None,
647 """Creates a nice box with rounded corners and returns it as a string.
650 title: the title of the box
651 text: the text inside the box
652 width: the width of the box
653 color: the box's color
658 See also :meth:`print_box`, :meth:`box`.
660 >>> print(preformatted_box('title', 'this\\nis\\nsome\\ntext', width=20).strip())
677 ret += color + "╭" + "─" * w + "╮" + rset + "\n"
678 if title is not None:
683 + justify_string(title, width=w, alignment="c")
689 ret += color + "│" + " " * w + "│" + rset + "\n"
691 for line in text.split("\n"):
692 tw = len(string_utils.strip_ansi_sequences(line))
705 ret += color + "╰" + "─" * w + "╯" + rset + "\n"
710 title: Optional[str] = None,
711 text: Optional[str] = None,
716 """Draws a box with nice rounded corners.
719 title: the title of the box
720 text: the text inside the box
721 width: the width of the box
722 color: the box's color
728 Prints a box with your text on the console to sys.stdout.
730 See also :meth:`preformatted_box`, :meth:`box`.
732 >>> print_box('Title', 'This is text', width=30)
733 ╭────────────────────────────╮
737 ╰────────────────────────────╯
739 >>> print_box(None, 'OK', width=6)
744 print(preformatted_box(title, text, width=width, color=color), end="")
747 if __name__ == "__main__":