OILS / opy / _regtest / src / string.py View on Github | oilshell.org

656 lines, 253 significant
1"""A collection of string operations (most are no longer used).
2
3Warning: most of the code you see here isn't normally used nowadays.
4Beginning with Python 1.6, many of these functions are implemented as
5methods on the standard string object. They used to be implemented by
6a built-in module called strop, but strop is now obsolete itself.
7
8Public module variables:
9
10whitespace -- a string containing all characters considered whitespace
11lowercase -- a string containing all characters considered lowercase letters
12uppercase -- a string containing all characters considered uppercase letters
13letters -- a string containing all characters considered letters
14digits -- a string containing all characters considered decimal digits
15hexdigits -- a string containing all characters considered hexadecimal digits
16octdigits -- a string containing all characters considered octal digits
17punctuation -- a string containing all characters considered punctuation
18printable -- a string containing all characters considered printable
19
20"""
21
22# Some strings for ctype-style character classification
23whitespace = ' \t\n\r\v\f'
24lowercase = 'abcdefghijklmnopqrstuvwxyz'
25uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
26letters = lowercase + uppercase
27ascii_lowercase = lowercase
28ascii_uppercase = uppercase
29ascii_letters = ascii_lowercase + ascii_uppercase
30digits = '0123456789'
31hexdigits = digits + 'abcdef' + 'ABCDEF'
32octdigits = '01234567'
33punctuation = """!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""
34printable = digits + letters + punctuation + whitespace
35
36# Case conversion helpers
37# Use str to convert Unicode literal in case of -U
38l = map(chr, xrange(256))
39_idmap = str('').join(l)
40del l
41
42# Functions which aren't available as string methods.
43
44# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
45def capwords(s, sep=None):
46 """capwords(s [,sep]) -> string
47
48 Split the argument into words using split, capitalize each
49 word using capitalize, and join the capitalized words using
50 join. If the optional second argument sep is absent or None,
51 runs of whitespace characters are replaced by a single space
52 and leading and trailing whitespace are removed, otherwise
53 sep is used to split and join the words.
54
55 """
56 return (sep or ' ').join(x.capitalize() for x in s.split(sep))
57
58
59# Construct a translation string
60_idmapL = None
61def maketrans(fromstr, tostr):
62 """maketrans(frm, to) -> string
63
64 Return a translation table (a string of 256 bytes long)
65 suitable for use in string.translate. The strings frm and to
66 must be of the same length.
67
68 """
69 if len(fromstr) != len(tostr):
70 raise ValueError, "maketrans arguments must have same length"
71 global _idmapL
72 if not _idmapL:
73 _idmapL = list(_idmap)
74 L = _idmapL[:]
75 fromstr = map(ord, fromstr)
76 for i in range(len(fromstr)):
77 L[fromstr[i]] = tostr[i]
78 return ''.join(L)
79
80
81
82####################################################################
83import re as _re
84
85class _multimap:
86 """Helper class for combining multiple mappings.
87
88 Used by .{safe_,}substitute() to combine the mapping and keyword
89 arguments.
90 """
91 def __init__(self, primary, secondary):
92 self._primary = primary
93 self._secondary = secondary
94
95 def __getitem__(self, key):
96 try:
97 return self._primary[key]
98 except KeyError:
99 return self._secondary[key]
100
101
102class _TemplateMetaclass(type):
103 pattern = r"""
104 %(delim)s(?:
105 (?P<escaped>%(delim)s) | # Escape sequence of two delimiters
106 (?P<named>%(id)s) | # delimiter and a Python identifier
107 {(?P<braced>%(id)s)} | # delimiter and a braced identifier
108 (?P<invalid>) # Other ill-formed delimiter exprs
109 )
110 """
111
112 def __init__(cls, name, bases, dct):
113 super(_TemplateMetaclass, cls).__init__(name, bases, dct)
114 if 'pattern' in dct:
115 pattern = cls.pattern
116 else:
117 pattern = _TemplateMetaclass.pattern % {
118 'delim' : _re.escape(cls.delimiter),
119 'id' : cls.idpattern,
120 }
121 cls.pattern = _re.compile(pattern, _re.IGNORECASE | _re.VERBOSE)
122
123
124class Template:
125 """A string class for supporting $-substitutions."""
126 __metaclass__ = _TemplateMetaclass
127
128 delimiter = '$'
129 idpattern = r'[_a-z][_a-z0-9]*'
130
131 def __init__(self, template):
132 self.template = template
133
134 # Search for $$, $identifier, ${identifier}, and any bare $'s
135
136 def _invalid(self, mo):
137 i = mo.start('invalid')
138 lines = self.template[:i].splitlines(True)
139 if not lines:
140 colno = 1
141 lineno = 1
142 else:
143 colno = i - len(''.join(lines[:-1]))
144 lineno = len(lines)
145 raise ValueError('Invalid placeholder in string: line %d, col %d' %
146 (lineno, colno))
147
148 def substitute(*args, **kws):
149 if not args:
150 raise TypeError("descriptor 'substitute' of 'Template' object "
151 "needs an argument")
152 self, args = args[0], args[1:] # allow the "self" keyword be passed
153 if len(args) > 1:
154 raise TypeError('Too many positional arguments')
155 if not args:
156 mapping = kws
157 elif kws:
158 mapping = _multimap(kws, args[0])
159 else:
160 mapping = args[0]
161 # Helper function for .sub()
162 def convert(mo):
163 # Check the most common path first.
164 named = mo.group('named') or mo.group('braced')
165 if named is not None:
166 val = mapping[named]
167 # We use this idiom instead of str() because the latter will
168 # fail if val is a Unicode containing non-ASCII characters.
169 return '%s' % (val,)
170 if mo.group('escaped') is not None:
171 return self.delimiter
172 if mo.group('invalid') is not None:
173 self._invalid(mo)
174 raise ValueError('Unrecognized named group in pattern',
175 self.pattern)
176 return self.pattern.sub(convert, self.template)
177
178 def safe_substitute(*args, **kws):
179 if not args:
180 raise TypeError("descriptor 'safe_substitute' of 'Template' object "
181 "needs an argument")
182 self, args = args[0], args[1:] # allow the "self" keyword be passed
183 if len(args) > 1:
184 raise TypeError('Too many positional arguments')
185 if not args:
186 mapping = kws
187 elif kws:
188 mapping = _multimap(kws, args[0])
189 else:
190 mapping = args[0]
191 # Helper function for .sub()
192 def convert(mo):
193 named = mo.group('named') or mo.group('braced')
194 if named is not None:
195 try:
196 # We use this idiom instead of str() because the latter
197 # will fail if val is a Unicode containing non-ASCII
198 return '%s' % (mapping[named],)
199 except KeyError:
200 return mo.group()
201 if mo.group('escaped') is not None:
202 return self.delimiter
203 if mo.group('invalid') is not None:
204 return mo.group()
205 raise ValueError('Unrecognized named group in pattern',
206 self.pattern)
207 return self.pattern.sub(convert, self.template)
208
209
210
211####################################################################
212# NOTE: Everything below here is deprecated. Use string methods instead.
213# This stuff will go away in Python 3.0.
214
215# Backward compatible names for exceptions
216index_error = ValueError
217atoi_error = ValueError
218atof_error = ValueError
219atol_error = ValueError
220
221# convert UPPER CASE letters to lower case
222def lower(s):
223 """lower(s) -> string
224
225 Return a copy of the string s converted to lowercase.
226
227 """
228 return s.lower()
229
230# Convert lower case letters to UPPER CASE
231def upper(s):
232 """upper(s) -> string
233
234 Return a copy of the string s converted to uppercase.
235
236 """
237 return s.upper()
238
239# Swap lower case letters and UPPER CASE
240def swapcase(s):
241 """swapcase(s) -> string
242
243 Return a copy of the string s with upper case characters
244 converted to lowercase and vice versa.
245
246 """
247 return s.swapcase()
248
249# Strip leading and trailing tabs and spaces
250def strip(s, chars=None):
251 """strip(s [,chars]) -> string
252
253 Return a copy of the string s with leading and trailing
254 whitespace removed.
255 If chars is given and not None, remove characters in chars instead.
256 If chars is unicode, S will be converted to unicode before stripping.
257
258 """
259 return s.strip(chars)
260
261# Strip leading tabs and spaces
262def lstrip(s, chars=None):
263 """lstrip(s [,chars]) -> string
264
265 Return a copy of the string s with leading whitespace removed.
266 If chars is given and not None, remove characters in chars instead.
267
268 """
269 return s.lstrip(chars)
270
271# Strip trailing tabs and spaces
272def rstrip(s, chars=None):
273 """rstrip(s [,chars]) -> string
274
275 Return a copy of the string s with trailing whitespace removed.
276 If chars is given and not None, remove characters in chars instead.
277
278 """
279 return s.rstrip(chars)
280
281
282# Split a string into a list of space/tab-separated words
283def split(s, sep=None, maxsplit=-1):
284 """split(s [,sep [,maxsplit]]) -> list of strings
285
286 Return a list of the words in the string s, using sep as the
287 delimiter string. If maxsplit is given, splits at no more than
288 maxsplit places (resulting in at most maxsplit+1 words). If sep
289 is not specified or is None, any whitespace string is a separator.
290
291 (split and splitfields are synonymous)
292
293 """
294 return s.split(sep, maxsplit)
295splitfields = split
296
297# Split a string into a list of space/tab-separated words
298def rsplit(s, sep=None, maxsplit=-1):
299 """rsplit(s [,sep [,maxsplit]]) -> list of strings
300
301 Return a list of the words in the string s, using sep as the
302 delimiter string, starting at the end of the string and working
303 to the front. If maxsplit is given, at most maxsplit splits are
304 done. If sep is not specified or is None, any whitespace string
305 is a separator.
306 """
307 return s.rsplit(sep, maxsplit)
308
309# Join fields with optional separator
310def join(words, sep = ' '):
311 """join(list [,sep]) -> string
312
313 Return a string composed of the words in list, with
314 intervening occurrences of sep. The default separator is a
315 single space.
316
317 (joinfields and join are synonymous)
318
319 """
320 return sep.join(words)
321joinfields = join
322
323# Find substring, raise exception if not found
324def index(s, *args):
325 """index(s, sub [,start [,end]]) -> int
326
327 Like find but raises ValueError when the substring is not found.
328
329 """
330 return s.index(*args)
331
332# Find last substring, raise exception if not found
333def rindex(s, *args):
334 """rindex(s, sub [,start [,end]]) -> int
335
336 Like rfind but raises ValueError when the substring is not found.
337
338 """
339 return s.rindex(*args)
340
341# Count non-overlapping occurrences of substring
342def count(s, *args):
343 """count(s, sub[, start[,end]]) -> int
344
345 Return the number of occurrences of substring sub in string
346 s[start:end]. Optional arguments start and end are
347 interpreted as in slice notation.
348
349 """
350 return s.count(*args)
351
352# Find substring, return -1 if not found
353def find(s, *args):
354 """find(s, sub [,start [,end]]) -> in
355
356 Return the lowest index in s where substring sub is found,
357 such that sub is contained within s[start,end]. Optional
358 arguments start and end are interpreted as in slice notation.
359
360 Return -1 on failure.
361
362 """
363 return s.find(*args)
364
365# Find last substring, return -1 if not found
366def rfind(s, *args):
367 """rfind(s, sub [,start [,end]]) -> int
368
369 Return the highest index in s where substring sub is found,
370 such that sub is contained within s[start,end]. Optional
371 arguments start and end are interpreted as in slice notation.
372
373 Return -1 on failure.
374
375 """
376 return s.rfind(*args)
377
378# for a bit of speed
379_float = float
380_int = int
381_long = long
382
383# Convert string to float
384def atof(s):
385 """atof(s) -> float
386
387 Return the floating point number represented by the string s.
388
389 """
390 return _float(s)
391
392
393# Convert string to integer
394def atoi(s , base=10):
395 """atoi(s [,base]) -> int
396
397 Return the integer represented by the string s in the given
398 base, which defaults to 10. The string s must consist of one
399 or more digits, possibly preceded by a sign. If base is 0, it
400 is chosen from the leading characters of s, 0 for octal, 0x or
401 0X for hexadecimal. If base is 16, a preceding 0x or 0X is
402 accepted.
403
404 """
405 return _int(s, base)
406
407
408# Convert string to long integer
409def atol(s, base=10):
410 """atol(s [,base]) -> long
411
412 Return the long integer represented by the string s in the
413 given base, which defaults to 10. The string s must consist
414 of one or more digits, possibly preceded by a sign. If base
415 is 0, it is chosen from the leading characters of s, 0 for
416 octal, 0x or 0X for hexadecimal. If base is 16, a preceding
417 0x or 0X is accepted. A trailing L or l is not accepted,
418 unless base is 0.
419
420 """
421 return _long(s, base)
422
423
424# Left-justify a string
425def ljust(s, width, *args):
426 """ljust(s, width[, fillchar]) -> string
427
428 Return a left-justified version of s, in a field of the
429 specified width, padded with spaces as needed. The string is
430 never truncated. If specified the fillchar is used instead of spaces.
431
432 """
433 return s.ljust(width, *args)
434
435# Right-justify a string
436def rjust(s, width, *args):
437 """rjust(s, width[, fillchar]) -> string
438
439 Return a right-justified version of s, in a field of the
440 specified width, padded with spaces as needed. The string is
441 never truncated. If specified the fillchar is used instead of spaces.
442
443 """
444 return s.rjust(width, *args)
445
446# Center a string
447def center(s, width, *args):
448 """center(s, width[, fillchar]) -> string
449
450 Return a center version of s, in a field of the specified
451 width. padded with spaces as needed. The string is never
452 truncated. If specified the fillchar is used instead of spaces.
453
454 """
455 return s.center(width, *args)
456
457# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
458# Decadent feature: the argument may be a string or a number
459# (Use of this is deprecated; it should be a string as with ljust c.s.)
460def zfill(x, width):
461 """zfill(x, width) -> string
462
463 Pad a numeric string x with zeros on the left, to fill a field
464 of the specified width. The string x is never truncated.
465
466 """
467 if not isinstance(x, basestring):
468 x = repr(x)
469 return x.zfill(width)
470
471# Expand tabs in a string.
472# Doesn't take non-printing chars into account, but does understand \n.
473def expandtabs(s, tabsize=8):
474 """expandtabs(s [,tabsize]) -> string
475
476 Return a copy of the string s with all tab characters replaced
477 by the appropriate number of spaces, depending on the current
478 column, and the tabsize (default 8).
479
480 """
481 return s.expandtabs(tabsize)
482
483# Character translation through look-up table.
484def translate(s, table, deletions=""):
485 """translate(s,table [,deletions]) -> string
486
487 Return a copy of the string s, where all characters occurring
488 in the optional argument deletions are removed, and the
489 remaining characters have been mapped through the given
490 translation table, which must be a string of length 256. The
491 deletions argument is not allowed for Unicode strings.
492
493 """
494 if deletions or table is None:
495 return s.translate(table, deletions)
496 else:
497 # Add s[:0] so that if s is Unicode and table is an 8-bit string,
498 # table is converted to Unicode. This means that table *cannot*
499 # be a dictionary -- for that feature, use u.translate() directly.
500 return s.translate(table + s[:0])
501
502# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
503def capitalize(s):
504 """capitalize(s) -> string
505
506 Return a copy of the string s with only its first character
507 capitalized.
508
509 """
510 return s.capitalize()
511
512# Substring replacement (global)
513def replace(s, old, new, maxreplace=-1):
514 """replace (str, old, new[, maxreplace]) -> string
515
516 Return a copy of string str with all occurrences of substring
517 old replaced by new. If the optional argument maxreplace is
518 given, only the first maxreplace occurrences are replaced.
519
520 """
521 return s.replace(old, new, maxreplace)
522
523
524# Try importing optional built-in module "strop" -- if it exists,
525# it redefines some string operations that are 100-1000 times faster.
526# It also defines values for whitespace, lowercase and uppercase
527# that match <ctype.h>'s definitions.
528
529try:
530 from strop import maketrans, lowercase, uppercase, whitespace
531 letters = lowercase + uppercase
532except ImportError:
533 pass # Use the original versions
534
535########################################################################
536# the Formatter class
537# see PEP 3101 for details and purpose of this class
538
539# The hard parts are reused from the C implementation. They're exposed as "_"
540# prefixed methods of str and unicode.
541
542# The overall parser is implemented in str._formatter_parser.
543# The field name parser is implemented in str._formatter_field_name_split
544
545class Formatter(object):
546 def format(*args, **kwargs):
547 if not args:
548 raise TypeError("descriptor 'format' of 'Formatter' object "
549 "needs an argument")
550 self, args = args[0], args[1:] # allow the "self" keyword be passed
551 try:
552 format_string, args = args[0], args[1:] # allow the "format_string" keyword be passed
553 except IndexError:
554 if 'format_string' in kwargs:
555 format_string = kwargs.pop('format_string')
556 else:
557 raise TypeError("format() missing 1 required positional "
558 "argument: 'format_string'")
559 return self.vformat(format_string, args, kwargs)
560
561 def vformat(self, format_string, args, kwargs):
562 used_args = set()
563 result = self._vformat(format_string, args, kwargs, used_args, 2)
564 self.check_unused_args(used_args, args, kwargs)
565 return result
566
567 def _vformat(self, format_string, args, kwargs, used_args, recursion_depth):
568 if recursion_depth < 0:
569 raise ValueError('Max string recursion exceeded')
570 result = []
571 for literal_text, field_name, format_spec, conversion in \
572 self.parse(format_string):
573
574 # output the literal text
575 if literal_text:
576 result.append(literal_text)
577
578 # if there's a field, output it
579 if field_name is not None:
580 # this is some markup, find the object and do
581 # the formatting
582
583 # given the field_name, find the object it references
584 # and the argument it came from
585 obj, arg_used = self.get_field(field_name, args, kwargs)
586 used_args.add(arg_used)
587
588 # do any conversion on the resulting object
589 obj = self.convert_field(obj, conversion)
590
591 # expand the format spec, if needed
592 format_spec = self._vformat(format_spec, args, kwargs,
593 used_args, recursion_depth-1)
594
595 # format the object and append to the result
596 result.append(self.format_field(obj, format_spec))
597
598 return ''.join(result)
599
600
601 def get_value(self, key, args, kwargs):
602 if isinstance(key, (int, long)):
603 return args[key]
604 else:
605 return kwargs[key]
606
607
608 def check_unused_args(self, used_args, args, kwargs):
609 pass
610
611
612 def format_field(self, value, format_spec):
613 return format(value, format_spec)
614
615
616 def convert_field(self, value, conversion):
617 # do any conversion on the resulting object
618 if conversion is None:
619 return value
620 elif conversion == 's':
621 return str(value)
622 elif conversion == 'r':
623 return repr(value)
624 raise ValueError("Unknown conversion specifier {0!s}".format(conversion))
625
626
627 # returns an iterable that contains tuples of the form:
628 # (literal_text, field_name, format_spec, conversion)
629 # literal_text can be zero length
630 # field_name can be None, in which case there's no
631 # object to format and output
632 # if field_name is not None, it is looked up, formatted
633 # with format_spec and conversion and then used
634 def parse(self, format_string):
635 return format_string._formatter_parser()
636
637
638 # given a field_name, find the object it references.
639 # field_name: the field being looked up, e.g. "0.name"
640 # or "lookup[3]"
641 # used_args: a set of which args have been used
642 # args, kwargs: as passed in to vformat
643 def get_field(self, field_name, args, kwargs):
644 first, rest = field_name._formatter_field_name_split()
645
646 obj = self.get_value(first, args, kwargs)
647
648 # loop through the rest of the field_name, doing
649 # getattr or getitem as needed
650 for is_attr, i in rest:
651 if is_attr:
652 obj = getattr(obj, i)
653 else:
654 obj = obj[i]
655
656 return obj, first