aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/python/ipython-genutils/py2/ipython_genutils/text.py
blob: e196a70ad6a4536dce14b722f7ac51e905bceb84 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# encoding: utf-8
"""
Utilities for working with strings and text.

Inheritance diagram:

.. inheritance-diagram:: IPython.utils.text
   :parts: 3
"""

import os
import re
import sys
import textwrap
from string import Formatter

# datetime.strftime date format for ipython
if sys.platform == 'win32':
    date_format = "%B %d, %Y"
else:
    date_format = "%B %-d, %Y"


def indent(instr,nspaces=4, ntabs=0, flatten=False):
    """Indent a string a given number of spaces or tabstops.

    indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.

    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.

    Returns
    -------

    str|unicode : string indented by ntabs and nspaces.

    """
    if instr is None:
        return
    ind = '\t'*ntabs+' '*nspaces
    if flatten:
        pat = re.compile(r'^\s*', re.MULTILINE)
    else:
        pat = re.compile(r'^', re.MULTILINE)
    outstr = re.sub(pat, ind, instr)
    if outstr.endswith(os.linesep+ind):
        return outstr[:-len(ind)]
    else:
        return outstr


def dedent(text):
    """Equivalent of textwrap.dedent that ignores unindented first line.

    This means it will still dedent strings like:
    '''foo
    is a bar
    '''

    For use in wrap_paragraphs.
    """

    if text.startswith('\n'):
        # text starts with blank line, don't ignore the first line
        return textwrap.dedent(text)

    # split first line
    splits = text.split('\n',1)
    if len(splits) == 1:
        # only one line
        return textwrap.dedent(text)

    first, rest = splits
    # dedent everything but the first line
    rest = textwrap.dedent(rest)
    return '\n'.join([first, rest])


def wrap_paragraphs(text, ncols=80):
    """Wrap multiple paragraphs to fit a specified width.

    This is equivalent to textwrap.wrap, but with support for multiple
    paragraphs, as separated by empty lines.

    Returns
    -------

    list of complete paragraphs, wrapped to fill `ncols` columns.
    """
    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:
        # presume indentation that survives dedent is meaningful formatting,
        # 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


def strip_ansi(source):
    """
    Remove ansi escape codes from text.
    
    Parameters
    ----------
    source : str
        Source to remove the ansi from
    """
    return re.sub(r'\033\[(\d|;)+?m', '', source)


#-----------------------------------------------------------------------------
# Utils to columnize a list of string
#-----------------------------------------------------------------------------

def _chunks(l, n):
    """Yield successive n-sized chunks from l."""
    for i in range(0, len(l), n):
        yield l[i:i+n]


def _find_optimal(rlist , separator_size=2 , displaywidth=80):
    """Calculate optimal info to columnize a list of string"""
    for nrow in range(1, len(rlist)+1) :
        chk = list(map(max,_chunks(rlist, nrow)))
        sumlength = sum(chk)
        ncols = len(chk)
        if sumlength+separator_size*(ncols-1) <= displaywidth :
            break;
    return {'columns_numbers' : ncols,
            'optimal_separator_width':(displaywidth - sumlength)/(ncols-1) if (ncols -1) else 0,
            'rows_numbers' : nrow,
            'columns_width' : chk
           }


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]


def compute_item_matrix(items, empty=None, *args, **kwargs) :
    """Returns a nested list, and info to columnize items

    Parameters
    ----------

    items
        list of strings to columize
    empty : (default None)
        default value to fill list if needed
    separator_size : int (default=2)
        How much caracters will be used as a separation between each columns.
    displaywidth : int (default=80)
        The width of the area onto wich the columns should enter

    Returns
    -------

    strings_matrix

        nested list of string, the outer most list contains as many list as
        rows, the innermost lists have each as many element as colums. If the
        total number of elements in `items` does not equal the product of
        rows*columns, the last element of some lists are filled with `None`.

    dict_info
        some info to make columnize easier:

        columns_numbers
          number of columns
        rows_numbers
          number of rows
        columns_width
          list of with of each columns
        optimal_separator_width
          best separator width between columns

    Examples
    --------
    ::

        In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l']
           ...: compute_item_matrix(l,displaywidth=12)
        Out[1]:
            ([['aaa', 'f', 'k'],
            ['b', 'g', 'l'],
            ['cc', 'h', None],
            ['d', 'i', None],
            ['eeeee', 'j', None]],
            {'columns_numbers': 3,
            'columns_width': [5, 1, 1],
            'optimal_separator_width': 2,
            'rows_numbers': 5})
    """
    info = _find_optimal(list(map(len, items)), *args, **kwargs)
    nrow, ncol = info['rows_numbers'], info['columns_numbers']
    return ([[ _get_or_default(items, c*nrow+i, default=empty) for c in range(ncol) ] for i in range(nrow) ], info)


def columnize(items, separator='  ', displaywidth=80):
    """ Transform a list of strings into a single string with columns.

    Parameters
    ----------
    items : sequence of strings
        The strings to process.

    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.

    Returns
    -------
    The formatted string.
    """
    if not items :
        return '\n'
    matrix, info = compute_item_matrix(items, separator_size=len(separator), displaywidth=displaywidth)
    fmatrix = [filter(None, x) for x in matrix]
    sjoin = lambda x : separator.join([ y.ljust(w, ' ') for y, w in zip(x, info['columns_width'])])
    return '\n'.join(map(sjoin, fmatrix))+'\n'