text.py
828 lines
| 24.6 KiB
| text/x-python
|
PythonLexer
|
r2498 | """ | ||
Utilities for working with strings and text. | ||||
|
r8795 | |||
Inheritance diagram: | ||||
.. inheritance-diagram:: IPython.utils.text | ||||
:parts: 3 | ||||
|
r2498 | """ | ||
import os | ||||
import re | ||||
|
r26615 | import string | ||
|
r28778 | import sys | ||
|
r4020 | import textwrap | ||
|
r28434 | import warnings | ||
|
r4004 | from string import Formatter | ||
|
r24258 | from pathlib import Path | ||
|
r2498 | |||
|
r28778 | from typing import List, Dict, Tuple, Optional, cast, Sequence, Mapping, Any | ||
if sys.version_info < (3, 12): | ||||
from typing_extensions import Self | ||||
else: | ||||
from typing import Self | ||||
|
r28475 | |||
|
r2498 | |||
class LSString(str): | ||||
"""String derivative with a special access attributes. | ||||
These are normal strings, but with the special attributes: | ||||
.l (or .list) : value as list (split on newlines). | ||||
.n (or .nlstr): original value (the string itself). | ||||
.s (or .spstr): value as whitespace-separated string. | ||||
|
r20811 | .p (or .paths): list of path objects (requires path.py package) | ||
|
r2498 | |||
Any values which require transformations are computed only once and | ||||
cached. | ||||
Such strings are very useful to efficiently interact with the shell, which | ||||
typically only understands whitespace-separated options for commands.""" | ||||
|
r28778 | __list: List[str] | ||
__spstr: str | ||||
__paths: List[Path] | ||||
def get_list(self) -> List[str]: | ||||
|
r2498 | try: | ||
return self.__list | ||||
except AttributeError: | ||||
self.__list = self.split('\n') | ||||
return self.__list | ||||
l = list = property(get_list) | ||||
|
r28778 | def get_spstr(self) -> str: | ||
|
r2498 | try: | ||
return self.__spstr | ||||
except AttributeError: | ||||
self.__spstr = self.replace('\n',' ') | ||||
return self.__spstr | ||||
s = spstr = property(get_spstr) | ||||
|
r28778 | def get_nlstr(self) -> Self: | ||
|
r2498 | return self | ||
n = nlstr = property(get_nlstr) | ||||
|
r28778 | def get_paths(self) -> List[Path]: | ||
|
r2498 | try: | ||
return self.__paths | ||||
except AttributeError: | ||||
|
r22249 | self.__paths = [Path(p) for p in self.split('\n') if os.path.exists(p)] | ||
|
r2498 | return self.__paths | ||
p = paths = property(get_paths) | ||||
|
r2781 | # FIXME: We need to reimplement type specific displayhook and then add this | ||
# back as a custom printer. This should also be moved outside utils into the | ||||
# core. | ||||
|
r2498 | |||
|
r2781 | # def print_lsstring(arg): | ||
# """ Prettier (non-repr-like) and more informative printer for LSString """ | ||||
|
r28756 | # print("LSString (.p, .n, .l, .s available). Value:") | ||
# print(arg) | ||||
|
r4872 | # | ||
# | ||||
|
r24687 | # print_lsstring = result_display.register(LSString)(print_lsstring) | ||
|
r2498 | |||
class SList(list): | ||||
"""List derivative with a special access attributes. | ||||
These are normal lists, but with the special attributes: | ||||
|
r13592 | * .l (or .list) : value as list (the list itself). | ||
* .n (or .nlstr): value as a string, joined on newlines. | ||||
* .s (or .spstr): value as a string, joined on spaces. | ||||
|
r20811 | * .p (or .paths): list of path objects (requires path.py package) | ||
|
r2498 | |||
Any values which require transformations are computed only once and | ||||
cached.""" | ||||
|
r28778 | __spstr: str | ||
__nlstr: str | ||||
__paths: List[Path] | ||||
def get_list(self) -> Self: | ||||
|
r2498 | return self | ||
l = list = property(get_list) | ||||
|
r28778 | def get_spstr(self) -> str: | ||
|
r2498 | try: | ||
return self.__spstr | ||||
except AttributeError: | ||||
self.__spstr = ' '.join(self) | ||||
return self.__spstr | ||||
s = spstr = property(get_spstr) | ||||
|
r28778 | def get_nlstr(self) -> str: | ||
|
r2498 | try: | ||
return self.__nlstr | ||||
except AttributeError: | ||||
self.__nlstr = '\n'.join(self) | ||||
return self.__nlstr | ||||
n = nlstr = property(get_nlstr) | ||||
|
r28778 | def get_paths(self) -> List[Path]: | ||
|
r2498 | try: | ||
return self.__paths | ||||
except AttributeError: | ||||
|
r22249 | self.__paths = [Path(p) for p in self if os.path.exists(p)] | ||
|
r2498 | return self.__paths | ||
p = paths = property(get_paths) | ||||
def grep(self, pattern, prune = False, field = None): | ||||
""" Return all strings matching 'pattern' (a regex or callable) | ||||
This is case-insensitive. If prune is true, return all items | ||||
NOT matching the pattern. | ||||
If field is specified, the match must occur in the specified | ||||
whitespace-separated field. | ||||
Examples:: | ||||
a.grep( lambda x: x.startswith('C') ) | ||||
a.grep('Cha.*log', prune=1) | ||||
a.grep('chm', field=-1) | ||||
""" | ||||
def match_target(s): | ||||
if field is None: | ||||
return s | ||||
parts = s.split() | ||||
try: | ||||
tgt = parts[field] | ||||
return tgt | ||||
except IndexError: | ||||
return "" | ||||
|
r23037 | if isinstance(pattern, str): | ||
|
r2498 | pred = lambda x : re.search(pattern, x, re.IGNORECASE) | ||
else: | ||||
pred = pattern | ||||
if not prune: | ||||
return SList([el for el in self if pred(match_target(el))]) | ||||
else: | ||||
return SList([el for el in self if not pred(match_target(el))]) | ||||
def fields(self, *fields): | ||||
""" Collect whitespace-separated fields from string list | ||||
Allows quick awk-like usage of string lists. | ||||
Example data (in var a, created by 'a = !ls -l'):: | ||||
|
r13592 | |||
|
r2498 | -rwxrwxrwx 1 ville None 18 Dec 14 2006 ChangeLog | ||
drwxrwxrwx+ 6 ville None 0 Oct 24 18:05 IPython | ||||
|
r13592 | * ``a.fields(0)`` is ``['-rwxrwxrwx', 'drwxrwxrwx+']`` | ||
* ``a.fields(1,0)`` is ``['1 -rwxrwxrwx', '6 drwxrwxrwx+']`` | ||||
(note the joining by space). | ||||
* ``a.fields(-1)`` is ``['ChangeLog', 'IPython']`` | ||||
|
r2498 | |||
IndexErrors are ignored. | ||||
Without args, fields() just split()'s the strings. | ||||
""" | ||||
if len(fields) == 0: | ||||
return [el.split() for el in self] | ||||
res = SList() | ||||
for el in [f.split() for f in self]: | ||||
lineparts = [] | ||||
for fd in fields: | ||||
try: | ||||
lineparts.append(el[fd]) | ||||
except IndexError: | ||||
pass | ||||
if lineparts: | ||||
res.append(" ".join(lineparts)) | ||||
return res | ||||
def sort(self,field= None, nums = False): | ||||
""" sort by specified fields (see fields()) | ||||
Example:: | ||||
|
r13807 | |||
|
r2498 | a.sort(1, nums = True) | ||
Sorts a by second field, in numerical order (so that 21 > 3) | ||||
""" | ||||
#decorate, sort, undecorate | ||||
if field is not None: | ||||
dsu = [[SList([line]).fields(field), line] for line in self] | ||||
else: | ||||
dsu = [[line, line] for line in self] | ||||
if nums: | ||||
for i in range(len(dsu)): | ||||
numstr = "".join([ch for ch in dsu[i][0] if ch.isdigit()]) | ||||
try: | ||||
n = int(numstr) | ||||
except ValueError: | ||||
|
r21782 | n = 0 | ||
|
r2498 | dsu[i][0] = n | ||
dsu.sort() | ||||
return SList([t[1] for t in dsu]) | ||||
|
r2781 | # FIXME: We need to reimplement type specific displayhook and then add this | ||
# back as a custom printer. This should also be moved outside utils into the | ||||
# core. | ||||
# def print_slist(arg): | ||||
# """ Prettier (non-repr-like) and more informative printer for SList """ | ||||
|
r28756 | # print("SList (.p, .n, .l, .s, .grep(), .fields(), sort() available):") | ||
|
r2781 | # if hasattr(arg, 'hideonce') and arg.hideonce: | ||
# arg.hideonce = False | ||||
# return | ||||
|
r4872 | # | ||
|
r9474 | # nlprint(arg) # This was a nested list printer, now removed. | ||
|
r4872 | # | ||
|
r24687 | # print_slist = result_display.register(SList)(print_slist) | ||
|
r2498 | |||
|
r3943 | def indent(instr,nspaces=4, ntabs=0, flatten=False): | ||
|
r2498 | """Indent a string a given number of spaces or tabstops. | ||
indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces. | ||||
|
r4872 | |||
|
r3943 | Parameters | ||
---------- | ||||
instr : basestring | ||||
The string to be indented. | ||||
nspaces : int (default: 4) | ||||
The number of spaces to be indented. | ||||
ntabs : int (default: 0) | ||||
The number of tabs to be indented. | ||||
flatten : bool (default: False) | ||||
Whether to scrub existing indentation. If True, all lines will be | ||||
aligned to the same indentation. If False, existing indentation will | ||||
be strictly increased. | ||||
|
r4872 | |||
|
r3943 | Returns | ||
------- | ||||
str|unicode : string indented by ntabs and nspaces. | ||||
|
r4872 | |||
|
r2498 | """ | ||
|
r3943 | if instr is None: | ||
|
r2498 | return | ||
ind = '\t'*ntabs+' '*nspaces | ||||
|
r3943 | if flatten: | ||
pat = re.compile(r'^\s*', re.MULTILINE) | ||||
else: | ||||
pat = re.compile(r'^', re.MULTILINE) | ||||
outstr = re.sub(pat, ind, instr) | ||||
|
r2498 | if outstr.endswith(os.linesep+ind): | ||
return outstr[:-len(ind)] | ||||
else: | ||||
return outstr | ||||
def list_strings(arg): | ||||
"""Always return a list of strings, given a string or list of strings | ||||
as input. | ||||
|
r13914 | Examples | ||
-------- | ||||
|
r13807 | :: | ||
|
r2498 | |||
In [7]: list_strings('A single string') | ||||
Out[7]: ['A single string'] | ||||
In [8]: list_strings(['A single string in a list']) | ||||
Out[8]: ['A single string in a list'] | ||||
In [9]: list_strings(['A','list','of','strings']) | ||||
Out[9]: ['A', 'list', 'of', 'strings'] | ||||
""" | ||||
|
r23037 | if isinstance(arg, str): | ||
return [arg] | ||||
else: | ||||
return arg | ||||
|
r2498 | |||
def marquee(txt='',width=78,mark='*'): | ||||
"""Return the input string centered in a 'marquee'. | ||||
|
r13914 | Examples | ||
-------- | ||||
|
r13807 | :: | ||
|
r2498 | |||
In [16]: marquee('A test',40) | ||||
Out[16]: '**************** A test ****************' | ||||
In [17]: marquee('A test',40,'-') | ||||
Out[17]: '---------------- A test ----------------' | ||||
In [18]: marquee('A test',40,' ') | ||||
Out[18]: ' A test ' | ||||
""" | ||||
if not txt: | ||||
return (mark*width)[:width] | ||||
|
r4732 | nmark = (width-len(txt)-2)//len(mark)//2 | ||
|
r2498 | if nmark < 0: nmark =0 | ||
marks = mark*nmark | ||||
return '%s %s %s' % (marks,txt,marks) | ||||
|
r2761 | ini_spaces_re = re.compile(r'^(\s+)') | ||
def num_ini_spaces(strng): | ||||
"""Return the number of initial spaces in a string""" | ||||
|
r28434 | warnings.warn( | ||
"`num_ini_spaces` is Pending Deprecation since IPython 8.17." | ||||
"It is considered fro removal in in future version. " | ||||
"Please open an issue if you believe it should be kept.", | ||||
stacklevel=2, | ||||
category=PendingDeprecationWarning, | ||||
) | ||||
|
r2761 | ini_spaces = ini_spaces_re.match(strng) | ||
if ini_spaces: | ||||
return ini_spaces.end() | ||||
else: | ||||
return 0 | ||||
|
r2929 | |||
def format_screen(strng): | ||||
"""Format a string for screen printing. | ||||
This removes some latex-type format codes.""" | ||||
# Paragraph continue | ||||
par_re = re.compile(r'\\$',re.MULTILINE) | ||||
strng = par_re.sub('',strng) | ||||
return strng | ||||
|
r7713 | |||
|
r28563 | def dedent(text: str) -> str: | ||
|
r4020 | """Equivalent of textwrap.dedent that ignores unindented first line. | ||
|
r4872 | |||
|
r4020 | This means it will still dedent strings like: | ||
'''foo | ||||
is a bar | ||||
''' | ||||
|
r4872 | |||
|
r4020 | For use in wrap_paragraphs. | ||
""" | ||||
|
r4872 | |||
|
r4020 | if text.startswith('\n'): | ||
# text starts with blank line, don't ignore the first line | ||||
return textwrap.dedent(text) | ||||
|
r4872 | |||
|
r4020 | # split first line | ||
splits = text.split('\n',1) | ||||
if len(splits) == 1: | ||||
# only one line | ||||
return textwrap.dedent(text) | ||||
|
r4872 | |||
|
r4020 | first, rest = splits | ||
# dedent everything but the first line | ||||
rest = textwrap.dedent(rest) | ||||
return '\n'.join([first, rest]) | ||||
|
r7713 | |||
|
r4020 | def wrap_paragraphs(text, ncols=80): | ||
"""Wrap multiple paragraphs to fit a specified width. | ||||
|
r4872 | |||
|
r4020 | This is equivalent to textwrap.wrap, but with support for multiple | ||
paragraphs, as separated by empty lines. | ||||
|
r4872 | |||
|
r4020 | Returns | ||
------- | ||||
list of complete paragraphs, wrapped to fill `ncols` columns. | ||||
""" | ||||
|
r28434 | warnings.warn( | ||
"`wrap_paragraphs` is Pending Deprecation since IPython 8.17." | ||||
"It is considered fro removal in in future version. " | ||||
"Please open an issue if you believe it should be kept.", | ||||
stacklevel=2, | ||||
category=PendingDeprecationWarning, | ||||
) | ||||
|
r4020 | paragraph_re = re.compile(r'\n(\s*\n)+', re.MULTILINE) | ||
text = dedent(text).strip() | ||||
paragraphs = paragraph_re.split(text)[::2] # every other entry is space | ||||
out_ps = [] | ||||
indent_re = re.compile(r'\n\s+', re.MULTILINE) | ||||
for p in paragraphs: | ||||
|
r4872 | # presume indentation that survives dedent is meaningful formatting, | ||
|
r4020 | # so don't fill unless text is flush. | ||
if indent_re.search(p) is None: | ||||
# wrap paragraph | ||||
p = textwrap.fill(p, ncols) | ||||
out_ps.append(p) | ||||
return out_ps | ||||
|
r4872 | |||
|
r4020 | |||
|
r7713 | def strip_email_quotes(text): | ||
"""Strip leading email quotation characters ('>'). | ||||
|
r7719 | |||
Removes any combination of leading '>' interspersed with whitespace that | ||||
appears *identically* in all lines of the input text. | ||||
Parameters | ||||
---------- | ||||
text : str | ||||
Examples | ||||
-------- | ||||
Simple uses:: | ||||
In [2]: strip_email_quotes('> > text') | ||||
Out[2]: 'text' | ||||
|
r7720 | In [3]: strip_email_quotes('> > text\\n> > more') | ||
Out[3]: 'text\\nmore' | ||||
|
r7719 | |||
Note how only the common prefix that appears in all lines is stripped:: | ||||
|
r7720 | In [4]: strip_email_quotes('> > text\\n> > more\\n> more...') | ||
Out[4]: '> text\\n> more\\nmore...' | ||||
|
r7719 | |||
|
r26615 | So if any line has no quote marks ('>'), then none are stripped from any | ||
|
r7719 | of them :: | ||
|
r26615 | |||
|
r7720 | In [5]: strip_email_quotes('> > text\\n> > more\\nlast different') | ||
Out[5]: '> > text\\n> > more\\nlast different' | ||||
|
r7713 | """ | ||
lines = text.splitlines() | ||||
|
r26615 | strip_len = 0 | ||
for characters in zip(*lines): | ||||
# Check if all characters in this position are the same | ||||
if len(set(characters)) > 1: | ||||
break | ||||
|
r26619 | prefix_char = characters[0] | ||
|
r26615 | |||
if prefix_char in string.whitespace or prefix_char == ">": | ||||
strip_len += 1 | ||||
|
r7713 | else: | ||
break | ||||
|
r26615 | |||
text = "\n".join([ln[strip_len:] for ln in lines]) | ||||
|
r7713 | return text | ||
|
r26615 | |||
|
r16980 | def strip_ansi(source): | ||
""" | ||||
Remove ansi escape codes from text. | ||||
|
r26419 | |||
|
r16980 | Parameters | ||
---------- | ||||
source : str | ||||
Source to remove the ansi from | ||||
""" | ||||
|
r28434 | warnings.warn( | ||
"`strip_ansi` is Pending Deprecation since IPython 8.17." | ||||
"It is considered fro removal in in future version. " | ||||
"Please open an issue if you believe it should be kept.", | ||||
stacklevel=2, | ||||
category=PendingDeprecationWarning, | ||||
) | ||||
|
r16980 | return re.sub(r'\033\[(\d|;)+?m', '', source) | ||
|
r7713 | |||
|
r4004 | class EvalFormatter(Formatter): | ||
"""A String Formatter that allows evaluation of simple expressions. | ||||
|
r27639 | |||
|
r27531 | Note that this version interprets a `:` as specifying a format string (as per | ||
|
r5353 | standard string formatting), so if slicing is required, you must explicitly | ||
create a slice. | ||||
|
r27639 | |||
|
r4004 | This is to be used in templating cases, such as the parallel batch | ||
script templates, where simple arithmetic on arguments is useful. | ||||
|
r4872 | |||
|
r4004 | Examples | ||
-------- | ||||
|
r13807 | :: | ||
In [1]: f = EvalFormatter() | ||||
In [2]: f.format('{n//4}', n=8) | ||||
Out[2]: '2' | ||||
In [3]: f.format("{greeting[slice(2,4)]}", greeting="Hello") | ||||
Out[3]: 'll' | ||||
|
r5353 | """ | ||
def get_field(self, name, args, kwargs): | ||||
v = eval(name, kwargs) | ||||
return v, name | ||||
|
r4872 | |||
|
r14002 | #XXX: As of Python 3.4, the format string parsing no longer splits on a colon | ||
# inside [], so EvalFormatter can handle slicing. Once we only support 3.4 and | ||||
# above, it should be possible to remove FullEvalFormatter. | ||||
|
r7719 | |||
|
r5353 | class FullEvalFormatter(Formatter): | ||
"""A String Formatter that allows evaluation of simple expressions. | ||||
|
r21541 | |||
|
r5353 | Any time a format key is not found in the kwargs, | ||
it will be tried as an expression in the kwargs namespace. | ||||
|
r21541 | |||
|
r5353 | Note that this version allows slicing using [1:2], so you cannot specify | ||
a format string. Use :class:`EvalFormatter` to permit format strings. | ||||
|
r21541 | |||
|
r5353 | Examples | ||
-------- | ||||
|
r13807 | :: | ||
In [1]: f = FullEvalFormatter() | ||||
In [2]: f.format('{n//4}', n=8) | ||||
|
r22976 | Out[2]: '2' | ||
|
r13807 | |||
In [3]: f.format('{list(range(5))[2:4]}') | ||||
|
r22976 | Out[3]: '[2, 3]' | ||
|
r4004 | |||
|
r13807 | In [4]: f.format('{3*2}') | ||
|
r22976 | Out[4]: '6' | ||
|
r4004 | """ | ||
|
r4654 | # copied from Formatter._vformat with minor changes to allow eval | ||
# and replace the format_spec code with slicing | ||||
|
r28778 | def vformat( | ||
self, format_string: str, args: Sequence[Any], kwargs: Mapping[str, Any] | ||||
) -> str: | ||||
|
r4654 | result = [] | ||
|
r28626 | conversion: Optional[str] | ||
for literal_text, field_name, format_spec, conversion in self.parse( | ||||
format_string | ||||
): | ||||
|
r4654 | # output the literal text | ||
if literal_text: | ||||
result.append(literal_text) | ||||
# if there's a field, output it | ||||
if field_name is not None: | ||||
# this is some markup, find the object and do | ||||
|
r5353 | # the formatting | ||
|
r4654 | |||
|
r5353 | if format_spec: | ||
|
r4654 | # override format spec, to allow slicing: | ||
field_name = ':'.join([field_name, format_spec]) | ||||
# eval the contents of the field for the object | ||||
# to be formatted | ||||
|
r28778 | obj = eval(field_name, dict(kwargs)) | ||
|
r4654 | |||
# do any conversion on the resulting object | ||||
|
r28626 | # type issue in typeshed, fined in https://github.com/python/typeshed/pull/11377 | ||
obj = self.convert_field(obj, conversion) # type: ignore[arg-type] | ||||
|
r4654 | |||
# format the object and append to the result | ||||
|
r5353 | result.append(self.format_field(obj, '')) | ||
|
r4654 | |||
|
r25343 | return ''.join(result) | ||
|
r4654 | |||
|
r7719 | |||
|
r5354 | class DollarFormatter(FullEvalFormatter): | ||
"""Formatter allowing Itpl style $foo replacement, for names and attribute | ||||
access only. Standard {foo} replacement also works, and allows full | ||||
evaluation of its arguments. | ||||
Examples | ||||
-------- | ||||
|
r13807 | :: | ||
In [1]: f = DollarFormatter() | ||||
In [2]: f.format('{n//4}', n=8) | ||||
|
r22976 | Out[2]: '2' | ||
|
r13807 | |||
In [3]: f.format('23 * 76 is $result', result=23*76) | ||||
|
r22976 | Out[3]: '23 * 76 is 1748' | ||
|
r13807 | |||
In [4]: f.format('$a or {b}', a=1, b=2) | ||||
|
r22976 | Out[4]: '1 or 2' | ||
|
r5354 | """ | ||
|
r24451 | _dollar_pattern_ignore_single_quote = re.compile(r"(.*?)\$(\$?[\w\.]+)(?=([^']*'[^']*')*[^']*$)") | ||
|
r5354 | def parse(self, fmt_string): | ||
for literal_txt, field_name, format_spec, conversion \ | ||||
in Formatter.parse(self, fmt_string): | ||||
|
r21541 | |||
|
r5354 | # Find $foo patterns in the literal text. | ||
continue_from = 0 | ||||
|
r5365 | txt = "" | ||
|
r23620 | for m in self._dollar_pattern_ignore_single_quote.finditer(literal_txt): | ||
|
r5354 | new_txt, new_field = m.group(1,2) | ||
|
r5365 | # $$foo --> $foo | ||
if new_field.startswith("$"): | ||||
txt += new_txt + new_field | ||||
else: | ||||
yield (txt + new_txt, new_field, "", None) | ||||
txt = "" | ||||
|
r5354 | continue_from = m.end() | ||
|
r21541 | |||
|
r5354 | # Re-yield the {foo} style pattern | ||
|
r5365 | yield (txt + literal_txt[continue_from:], field_name, format_spec, conversion) | ||
|
r4004 | |||
|
r27136 | def __repr__(self): | ||
return "<DollarFormatter>" | ||||
|
r7387 | #----------------------------------------------------------------------------- | ||
# Utils to columnize a list of string | ||||
#----------------------------------------------------------------------------- | ||||
|
r7719 | |||
|
r21618 | def _col_chunks(l, max_rows, row_first=False): | ||
"""Yield successive max_rows-sized column chunks from l.""" | ||||
|
r21613 | if row_first: | ||
|
r21618 | ncols = (len(l) // max_rows) + (len(l) % max_rows > 0) | ||
|
r23036 | for i in range(ncols): | ||
yield [l[j] for j in range(i, len(l), ncols)] | ||||
|
r21613 | else: | ||
|
r23036 | for i in range(0, len(l), max_rows): | ||
|
r21618 | yield l[i:(i + max_rows)] | ||
|
r7387 | |||
|
r7719 | |||
|
r28778 | def _find_optimal( | ||
rlist: List[str], row_first: bool, separator_size: int, displaywidth: int | ||||
) -> Dict[str, Any]: | ||||
|
r7387 | """Calculate optimal info to columnize a list of string""" | ||
|
r21618 | for max_rows in range(1, len(rlist) + 1): | ||
col_widths = list(map(max, _col_chunks(rlist, max_rows, row_first))) | ||||
|
r21613 | sumlength = sum(col_widths) | ||
ncols = len(col_widths) | ||||
if sumlength + separator_size * (ncols - 1) <= displaywidth: | ||||
break | ||||
return {'num_columns': ncols, | ||||
|
r22980 | 'optimal_separator_width': (displaywidth - sumlength) // (ncols - 1) if (ncols - 1) else 0, | ||
|
r21618 | 'max_rows': max_rows, | ||
|
r21613 | 'column_widths': col_widths | ||
} | ||||
|
r7387 | |||
|
r7719 | |||
|
r7387 | def _get_or_default(mylist, i, default=None): | ||
"""return list item number, or default if don't exist""" | ||||
if i >= len(mylist): | ||||
return default | ||||
else : | ||||
return mylist[i] | ||||
|
r7719 | |||
|
r28480 | def compute_item_matrix( | ||
|
r28778 | items: List[str], | ||
row_first: bool = False, | ||||
empty: Optional[str] = None, | ||||
*, | ||||
separator_size: int = 2, | ||||
displaywidth: int = 80, | ||||
|
r28480 | ) -> Tuple[List[List[int]], Dict[str, int]]: | ||
|
r7388 | """Returns a nested list, and info to columnize items | ||
|
r9244 | Parameters | ||
---------- | ||||
|
r13807 | items | ||
|
r7388 | list of strings to columize | ||
|
r21613 | row_first : (default False) | ||
|
r21615 | Whether to compute columns for a row-first matrix instead of | ||
|
r21613 | column-first (default). | ||
|
r7393 | empty : (default None) | ||
default value to fill list if needed | ||||
|
r7388 | separator_size : int (default=2) | ||
|
r24322 | How much characters will be used as a separation between each columns. | ||
|
r7388 | displaywidth : int (default=80) | ||
|
r24084 | The width of the area onto which the columns should enter | ||
|
r7388 | |||
|
r9244 | Returns | ||
------- | ||||
|
r13807 | strings_matrix | ||
|
r7388 | nested list of string, the outer most list contains as many list as | ||
|
r24084 | rows, the innermost lists have each as many element as columns. If the | ||
|
r7388 | total number of elements in `items` does not equal the product of | ||
rows*columns, the last element of some lists are filled with `None`. | ||||
|
r13807 | dict_info | ||
|
r7388 | some info to make columnize easier: | ||
|
r21613 | num_columns | ||
|
r13807 | number of columns | ||
|
r21618 | max_rows | ||
maximum number of rows (final number may be less) | ||||
|
r21613 | column_widths | ||
|
r13807 | list of with of each columns | ||
optimal_separator_width | ||||
best separator width between columns | ||||
|
r7388 | |||
|
r9244 | Examples | ||
-------- | ||||
|
r13807 | :: | ||
In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l'] | ||||
|
r22980 | In [2]: list, info = compute_item_matrix(l, displaywidth=12) | ||
In [3]: list | ||||
Out[3]: [['aaa', 'f', 'k'], ['b', 'g', 'l'], ['cc', 'h', None], ['d', 'i', None], ['eeeee', 'j', None]] | ||||
In [4]: ideal = {'num_columns': 3, 'column_widths': [5, 1, 1], 'optimal_separator_width': 2, 'max_rows': 5} | ||||
In [5]: all((info[k] == ideal[k] for k in ideal.keys())) | ||||
Out[5]: True | ||||
|
r7387 | """ | ||
|
r28434 | warnings.warn( | ||
"`compute_item_matrix` is Pending Deprecation since IPython 8.17." | ||||
"It is considered fro removal in in future version. " | ||||
"Please open an issue if you believe it should be kept.", | ||||
stacklevel=2, | ||||
category=PendingDeprecationWarning, | ||||
) | ||||
|
r28480 | info = _find_optimal( | ||
|
r28778 | list(map(len, items)), # type: ignore[arg-type] | ||
|
r28480 | row_first, | ||
separator_size=separator_size, | ||||
displaywidth=displaywidth, | ||||
) | ||||
nrow, ncol = info["max_rows"], info["num_columns"] | ||||
|
r21613 | if row_first: | ||
|
r21617 | return ([[_get_or_default(items, r * ncol + c, default=empty) for c in range(ncol)] for r in range(nrow)], info) | ||
|
r21613 | else: | ||
return ([[_get_or_default(items, c * nrow + r, default=empty) for c in range(ncol)] for r in range(nrow)], info) | ||||
|
r4004 | |||
|
r7719 | |||
|
r28626 | def columnize( | ||
items: List[str], | ||||
row_first: bool = False, | ||||
separator: str = " ", | ||||
displaywidth: int = 80, | ||||
spread: bool = False, | ||||
|
r28778 | ) -> str: | ||
|
r27639 | """Transform a list of strings into a single string with columns. | ||
|
r4537 | |||
Parameters | ||||
---------- | ||||
items : sequence of strings | ||||
The strings to process. | ||||
|
r21613 | row_first : (default False) | ||
|
r21615 | Whether to compute columns for a row-first matrix instead of | ||
|
r21613 | column-first (default). | ||
|
r4537 | separator : str, optional [default is two spaces] | ||
The string that separates columns. | ||||
displaywidth : int, optional [default is 80] | ||||
Width of the display in number of characters. | ||||
|
r4872 | |||
|
r4537 | Returns | ||
------- | ||||
The formatted string. | ||||
""" | ||||
|
r28434 | warnings.warn( | ||
"`columnize` is Pending Deprecation since IPython 8.17." | ||||
|
r28626 | "It is considered for removal in future versions. " | ||
|
r28434 | "Please open an issue if you believe it should be kept.", | ||
stacklevel=2, | ||||
category=PendingDeprecationWarning, | ||||
) | ||||
|
r21613 | if not items: | ||
|
r28480 | return "\n" | ||
matrix: List[List[int]] | ||||
matrix, info = compute_item_matrix( | ||||
items, | ||||
row_first=row_first, | ||||
separator_size=len(separator), | ||||
displaywidth=displaywidth, | ||||
) | ||||
|
r21621 | if spread: | ||
|
r28480 | separator = separator.ljust(int(info["optimal_separator_width"])) | ||
fmatrix: List[filter[int]] = [filter(None, x) for x in matrix] | ||||
sjoin = lambda x: separator.join( | ||||
|
r28626 | [y.ljust(w, " ") for y, w in zip(x, cast(List[int], info["column_widths"]))] | ||
|
r28480 | ) | ||
return "\n".join(map(sjoin, fmatrix)) + "\n" | ||||
|
r12919 | |||
|
r12925 | def get_text_list(list_, last_sep=' and ', sep=", ", wrap_item_with=""): | ||
|
r12919 | """ | ||
Return a string with a natural enumeration of items | ||||
>>> get_text_list(['a', 'b', 'c', 'd']) | ||||
'a, b, c and d' | ||||
|
r12925 | >>> get_text_list(['a', 'b', 'c'], ' or ') | ||
|
r12919 | 'a, b or c' | ||
|
r12925 | >>> get_text_list(['a', 'b', 'c'], ', ') | ||
'a, b, c' | ||||
>>> get_text_list(['a', 'b'], ' or ') | ||||
|
r12919 | 'a or b' | ||
>>> get_text_list(['a']) | ||||
'a' | ||||
>>> get_text_list([]) | ||||
'' | ||||
>>> get_text_list(['a', 'b'], wrap_item_with="`") | ||||
'`a` and `b`' | ||||
|
r12925 | >>> get_text_list(['a', 'b', 'c', 'd'], " = ", sep=" + ") | ||
'a + b + c = d' | ||||
|
r12919 | """ | ||
if len(list_) == 0: | ||||
return '' | ||||
if wrap_item_with: | ||||
list_ = ['%s%s%s' % (wrap_item_with, item, wrap_item_with) for | ||||
item in list_] | ||||
if len(list_) == 1: | ||||
return list_[0] | ||||
|
r12925 | return '%s%s%s' % ( | ||
sep.join(i for i in list_[:-1]), | ||||
|
r21542 | last_sep, list_[-1]) | ||