Neal Norwitz | 9d72bb4 | 2007-04-17 08:48:32 +0000 | [diff] [blame] | 1 | """A collection of string constants. |
Guido van Rossum | 2003204 | 1997-12-29 19:26:28 +0000 | [diff] [blame] | 2 | |
| 3 | Public module variables: |
| 4 | |
Georg Brandl | 5076740 | 2008-11-22 08:31:09 +0000 | [diff] [blame] | 5 | whitespace -- a string containing all ASCII whitespace |
| 6 | ascii_lowercase -- a string containing all ASCII lowercase letters |
| 7 | ascii_uppercase -- a string containing all ASCII uppercase letters |
| 8 | ascii_letters -- a string containing all ASCII letters |
| 9 | digits -- a string containing all ASCII decimal digits |
| 10 | hexdigits -- a string containing all ASCII hexadecimal digits |
| 11 | octdigits -- a string containing all ASCII octal digits |
| 12 | punctuation -- a string containing all ASCII punctuation characters |
| 13 | printable -- a string containing all ASCII characters considered printable |
Guido van Rossum | 2003204 | 1997-12-29 19:26:28 +0000 | [diff] [blame] | 14 | |
| 15 | """ |
| 16 | |
Georg Brandl | 66c221e | 2010-10-14 07:04:07 +0000 | [diff] [blame^] | 17 | import _string |
| 18 | |
Guido van Rossum | c636014 | 1990-10-13 19:23:40 +0000 | [diff] [blame] | 19 | # Some strings for ctype-style character classification |
Guido van Rossum | 8e2ec56 | 1993-07-29 09:37:38 +0000 | [diff] [blame] | 20 | whitespace = ' \t\n\r\v\f' |
Martin v. Löwis | 967f1e3 | 2007-08-14 09:23:10 +0000 | [diff] [blame] | 21 | ascii_lowercase = 'abcdefghijklmnopqrstuvwxyz' |
| 22 | ascii_uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' |
Fred Drake | 960fdf9 | 2001-07-20 18:38:26 +0000 | [diff] [blame] | 23 | ascii_letters = ascii_lowercase + ascii_uppercase |
Guido van Rossum | c636014 | 1990-10-13 19:23:40 +0000 | [diff] [blame] | 24 | digits = '0123456789' |
| 25 | hexdigits = digits + 'abcdef' + 'ABCDEF' |
| 26 | octdigits = '01234567' |
Tim Peters | 495ad3c | 2001-01-15 01:36:40 +0000 | [diff] [blame] | 27 | punctuation = """!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~""" |
Martin v. Löwis | 967f1e3 | 2007-08-14 09:23:10 +0000 | [diff] [blame] | 28 | printable = digits + ascii_letters + punctuation + whitespace |
Guido van Rossum | c636014 | 1990-10-13 19:23:40 +0000 | [diff] [blame] | 29 | |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 30 | # Functions which aren't available as string methods. |
| 31 | |
| 32 | # Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def". |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 33 | def capwords(s, sep=None): |
Ezio Melotti | a40bdda | 2009-09-26 12:33:22 +0000 | [diff] [blame] | 34 | """capwords(s [,sep]) -> string |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 35 | |
| 36 | Split the argument into words using split, capitalize each |
| 37 | word using capitalize, and join the capitalized words using |
Ezio Melotti | a40bdda | 2009-09-26 12:33:22 +0000 | [diff] [blame] | 38 | join. If the optional second argument sep is absent or None, |
| 39 | runs of whitespace characters are replaced by a single space |
| 40 | and leading and trailing whitespace are removed, otherwise |
| 41 | sep is used to split and join the words. |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 42 | |
| 43 | """ |
Ezio Melotti | a40bdda | 2009-09-26 12:33:22 +0000 | [diff] [blame] | 44 | return (sep or ' ').join(x.capitalize() for x in s.split(sep)) |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 45 | |
| 46 | |
Raymond Hettinger | 0d58e2b | 2004-08-26 00:21:13 +0000 | [diff] [blame] | 47 | #################################################################### |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 48 | import re as _re |
| 49 | |
Barry Warsaw | 46b629c | 2004-09-13 14:35:04 +0000 | [diff] [blame] | 50 | class _multimap: |
| 51 | """Helper class for combining multiple mappings. |
| 52 | |
| 53 | Used by .{safe_,}substitute() to combine the mapping and keyword |
| 54 | arguments. |
| 55 | """ |
| 56 | def __init__(self, primary, secondary): |
| 57 | self._primary = primary |
| 58 | self._secondary = secondary |
| 59 | |
| 60 | def __getitem__(self, key): |
| 61 | try: |
| 62 | return self._primary[key] |
| 63 | except KeyError: |
| 64 | return self._secondary[key] |
| 65 | |
| 66 | |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 67 | class _TemplateMetaclass(type): |
| 68 | pattern = r""" |
Raymond Hettinger | 55593c3 | 2004-09-26 18:56:44 +0000 | [diff] [blame] | 69 | %(delim)s(?: |
| 70 | (?P<escaped>%(delim)s) | # Escape sequence of two delimiters |
| 71 | (?P<named>%(id)s) | # delimiter and a Python identifier |
| 72 | {(?P<braced>%(id)s)} | # delimiter and a braced identifier |
| 73 | (?P<invalid>) # Other ill-formed delimiter exprs |
| 74 | ) |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 75 | """ |
| 76 | |
| 77 | def __init__(cls, name, bases, dct): |
| 78 | super(_TemplateMetaclass, cls).__init__(name, bases, dct) |
| 79 | if 'pattern' in dct: |
| 80 | pattern = cls.pattern |
| 81 | else: |
| 82 | pattern = _TemplateMetaclass.pattern % { |
Barry Warsaw | 17cb600 | 2004-09-18 00:06:34 +0000 | [diff] [blame] | 83 | 'delim' : _re.escape(cls.delimiter), |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 84 | 'id' : cls.idpattern, |
| 85 | } |
Georg Brandl | 056cb93 | 2010-07-29 17:16:10 +0000 | [diff] [blame] | 86 | cls.pattern = _re.compile(pattern, cls.flags | _re.VERBOSE) |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 87 | |
| 88 | |
Guido van Rossum | 52cc1d8 | 2007-03-18 15:41:51 +0000 | [diff] [blame] | 89 | class Template(metaclass=_TemplateMetaclass): |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 90 | """A string class for supporting $-substitutions.""" |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 91 | |
Barry Warsaw | 17cb600 | 2004-09-18 00:06:34 +0000 | [diff] [blame] | 92 | delimiter = '$' |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 93 | idpattern = r'[_a-z][_a-z0-9]*' |
Georg Brandl | 056cb93 | 2010-07-29 17:16:10 +0000 | [diff] [blame] | 94 | flags = _re.IGNORECASE |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 95 | |
| 96 | def __init__(self, template): |
| 97 | self.template = template |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 98 | |
| 99 | # Search for $$, $identifier, ${identifier}, and any bare $'s |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 100 | |
Barry Warsaw | b5c6b5b | 2004-09-13 20:52:50 +0000 | [diff] [blame] | 101 | def _invalid(self, mo): |
| 102 | i = mo.start('invalid') |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 103 | lines = self.template[:i].splitlines(True) |
| 104 | if not lines: |
| 105 | colno = 1 |
| 106 | lineno = 1 |
| 107 | else: |
| 108 | colno = i - len(''.join(lines[:-1])) |
| 109 | lineno = len(lines) |
| 110 | raise ValueError('Invalid placeholder in string: line %d, col %d' % |
| 111 | (lineno, colno)) |
| 112 | |
Barry Warsaw | b6234a9 | 2004-09-13 15:25:15 +0000 | [diff] [blame] | 113 | def substitute(self, *args, **kws): |
| 114 | if len(args) > 1: |
| 115 | raise TypeError('Too many positional arguments') |
| 116 | if not args: |
| 117 | mapping = kws |
Barry Warsaw | 46b629c | 2004-09-13 14:35:04 +0000 | [diff] [blame] | 118 | elif kws: |
Barry Warsaw | b6234a9 | 2004-09-13 15:25:15 +0000 | [diff] [blame] | 119 | mapping = _multimap(kws, args[0]) |
| 120 | else: |
| 121 | mapping = args[0] |
Barry Warsaw | 46b629c | 2004-09-13 14:35:04 +0000 | [diff] [blame] | 122 | # Helper function for .sub() |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 123 | def convert(mo): |
Barry Warsaw | b5c6b5b | 2004-09-13 20:52:50 +0000 | [diff] [blame] | 124 | # Check the most common path first. |
| 125 | named = mo.group('named') or mo.group('braced') |
| 126 | if named is not None: |
| 127 | val = mapping[named] |
| 128 | # We use this idiom instead of str() because the latter will |
| 129 | # fail if val is a Unicode containing non-ASCII characters. |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 130 | return '%s' % (val,) |
Raymond Hettinger | 0d58e2b | 2004-08-26 00:21:13 +0000 | [diff] [blame] | 131 | if mo.group('escaped') is not None: |
Barry Warsaw | 17cb600 | 2004-09-18 00:06:34 +0000 | [diff] [blame] | 132 | return self.delimiter |
Barry Warsaw | b5c6b5b | 2004-09-13 20:52:50 +0000 | [diff] [blame] | 133 | if mo.group('invalid') is not None: |
| 134 | self._invalid(mo) |
Neal Norwitz | 6627a96 | 2004-10-17 16:27:18 +0000 | [diff] [blame] | 135 | raise ValueError('Unrecognized named group in pattern', |
| 136 | self.pattern) |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 137 | return self.pattern.sub(convert, self.template) |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 138 | |
Barry Warsaw | b6234a9 | 2004-09-13 15:25:15 +0000 | [diff] [blame] | 139 | def safe_substitute(self, *args, **kws): |
| 140 | if len(args) > 1: |
| 141 | raise TypeError('Too many positional arguments') |
| 142 | if not args: |
| 143 | mapping = kws |
Barry Warsaw | 46b629c | 2004-09-13 14:35:04 +0000 | [diff] [blame] | 144 | elif kws: |
Barry Warsaw | b6234a9 | 2004-09-13 15:25:15 +0000 | [diff] [blame] | 145 | mapping = _multimap(kws, args[0]) |
| 146 | else: |
| 147 | mapping = args[0] |
Barry Warsaw | 46b629c | 2004-09-13 14:35:04 +0000 | [diff] [blame] | 148 | # Helper function for .sub() |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 149 | def convert(mo): |
Florent Xicluna | eb19dce | 2010-09-18 23:34:07 +0000 | [diff] [blame] | 150 | named = mo.group('named') or mo.group('braced') |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 151 | if named is not None: |
| 152 | try: |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 153 | # We use this idiom instead of str() because the latter |
| 154 | # will fail if val is a Unicode containing non-ASCII |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 155 | return '%s' % (mapping[named],) |
Barry Warsaw | 8bee761 | 2004-08-25 02:22:30 +0000 | [diff] [blame] | 156 | except KeyError: |
Florent Xicluna | eb19dce | 2010-09-18 23:34:07 +0000 | [diff] [blame] | 157 | return mo.group() |
Barry Warsaw | b5c6b5b | 2004-09-13 20:52:50 +0000 | [diff] [blame] | 158 | if mo.group('escaped') is not None: |
Barry Warsaw | 17cb600 | 2004-09-18 00:06:34 +0000 | [diff] [blame] | 159 | return self.delimiter |
Barry Warsaw | b5c6b5b | 2004-09-13 20:52:50 +0000 | [diff] [blame] | 160 | if mo.group('invalid') is not None: |
Florent Xicluna | eb19dce | 2010-09-18 23:34:07 +0000 | [diff] [blame] | 161 | return mo.group() |
Neal Norwitz | 6627a96 | 2004-10-17 16:27:18 +0000 | [diff] [blame] | 162 | raise ValueError('Unrecognized named group in pattern', |
| 163 | self.pattern) |
Barry Warsaw | 12827c1 | 2004-09-10 03:08:08 +0000 | [diff] [blame] | 164 | return self.pattern.sub(convert, self.template) |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 165 | |
| 166 | |
| 167 | |
| 168 | ######################################################################## |
| 169 | # the Formatter class |
| 170 | # see PEP 3101 for details and purpose of this class |
| 171 | |
Benjamin Peterson | f608c61 | 2008-11-16 18:33:53 +0000 | [diff] [blame] | 172 | # The hard parts are reused from the C implementation. They're exposed as "_" |
Florent Xicluna | 7b2a771 | 2010-09-06 20:27:55 +0000 | [diff] [blame] | 173 | # prefixed methods of str. |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 174 | |
Georg Brandl | 66c221e | 2010-10-14 07:04:07 +0000 | [diff] [blame^] | 175 | # The overall parser is implemented in _string.formatter_parser. |
| 176 | # The field name parser is implemented in _string.formatter_field_name_split |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 177 | |
| 178 | class Formatter: |
| 179 | def format(self, format_string, *args, **kwargs): |
| 180 | return self.vformat(format_string, args, kwargs) |
| 181 | |
| 182 | def vformat(self, format_string, args, kwargs): |
Eric Smith | 3bcc42a | 2007-08-31 02:26:31 +0000 | [diff] [blame] | 183 | used_args = set() |
Eric Smith | 1152919 | 2007-09-04 23:04:22 +0000 | [diff] [blame] | 184 | result = self._vformat(format_string, args, kwargs, used_args, 2) |
| 185 | self.check_unused_args(used_args, args, kwargs) |
| 186 | return result |
| 187 | |
| 188 | def _vformat(self, format_string, args, kwargs, used_args, recursion_depth): |
| 189 | if recursion_depth < 0: |
| 190 | raise ValueError('Max string recursion exceeded') |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 191 | result = [] |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 192 | for literal_text, field_name, format_spec, conversion in \ |
| 193 | self.parse(format_string): |
Eric Smith | 625cbf2 | 2007-08-29 03:22:59 +0000 | [diff] [blame] | 194 | |
| 195 | # output the literal text |
| 196 | if literal_text: |
| 197 | result.append(literal_text) |
| 198 | |
| 199 | # if there's a field, output it |
| 200 | if field_name is not None: |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 201 | # this is some markup, find the object and do |
| 202 | # the formatting |
| 203 | |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 204 | # given the field_name, find the object it references |
Eric Smith | 3bcc42a | 2007-08-31 02:26:31 +0000 | [diff] [blame] | 205 | # and the argument it came from |
Eric Smith | 9d4ba39 | 2007-09-02 15:33:26 +0000 | [diff] [blame] | 206 | obj, arg_used = self.get_field(field_name, args, kwargs) |
Eric Smith | 3bcc42a | 2007-08-31 02:26:31 +0000 | [diff] [blame] | 207 | used_args.add(arg_used) |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 208 | |
| 209 | # do any conversion on the resulting object |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 210 | obj = self.convert_field(obj, conversion) |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 211 | |
Eric Smith | 1152919 | 2007-09-04 23:04:22 +0000 | [diff] [blame] | 212 | # expand the format spec, if needed |
| 213 | format_spec = self._vformat(format_spec, args, kwargs, |
| 214 | used_args, recursion_depth-1) |
| 215 | |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 216 | # format the object and append to the result |
| 217 | result.append(self.format_field(obj, format_spec)) |
Eric Smith | 625cbf2 | 2007-08-29 03:22:59 +0000 | [diff] [blame] | 218 | |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 219 | return ''.join(result) |
| 220 | |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 221 | |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 222 | def get_value(self, key, args, kwargs): |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 223 | if isinstance(key, int): |
| 224 | return args[key] |
| 225 | else: |
| 226 | return kwargs[key] |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 227 | |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 228 | |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 229 | def check_unused_args(self, used_args, args, kwargs): |
| 230 | pass |
| 231 | |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 232 | |
Eric Smith | 8c66326 | 2007-08-25 02:26:07 +0000 | [diff] [blame] | 233 | def format_field(self, value, format_spec): |
Eric Smith | 7ade648 | 2007-08-26 22:27:13 +0000 | [diff] [blame] | 234 | return format(value, format_spec) |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 235 | |
| 236 | |
| 237 | def convert_field(self, value, conversion): |
| 238 | # do any conversion on the resulting object |
| 239 | if conversion == 'r': |
| 240 | return repr(value) |
| 241 | elif conversion == 's': |
| 242 | return str(value) |
Eric Smith | 1152919 | 2007-09-04 23:04:22 +0000 | [diff] [blame] | 243 | elif conversion is None: |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 244 | return value |
Florent Xicluna | 7b2a771 | 2010-09-06 20:27:55 +0000 | [diff] [blame] | 245 | raise ValueError("Unknown conversion specifier {0!s}".format(conversion)) |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 246 | |
| 247 | |
| 248 | # returns an iterable that contains tuples of the form: |
| 249 | # (literal_text, field_name, format_spec, conversion) |
Eric Smith | 625cbf2 | 2007-08-29 03:22:59 +0000 | [diff] [blame] | 250 | # literal_text can be zero length |
| 251 | # field_name can be None, in which case there's no |
| 252 | # object to format and output |
| 253 | # if field_name is not None, it is looked up, formatted |
| 254 | # with format_spec and conversion and then used |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 255 | def parse(self, format_string): |
Georg Brandl | 66c221e | 2010-10-14 07:04:07 +0000 | [diff] [blame^] | 256 | return _string.formatter_parser(format_string) |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 257 | |
| 258 | |
| 259 | # given a field_name, find the object it references. |
| 260 | # field_name: the field being looked up, e.g. "0.name" |
| 261 | # or "lookup[3]" |
| 262 | # used_args: a set of which args have been used |
| 263 | # args, kwargs: as passed in to vformat |
Eric Smith | 9d4ba39 | 2007-09-02 15:33:26 +0000 | [diff] [blame] | 264 | def get_field(self, field_name, args, kwargs): |
Georg Brandl | 66c221e | 2010-10-14 07:04:07 +0000 | [diff] [blame^] | 265 | first, rest = _string.formatter_field_name_split(field_name) |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 266 | |
Eric Smith | 9e7c8da | 2007-08-28 11:15:20 +0000 | [diff] [blame] | 267 | obj = self.get_value(first, args, kwargs) |
| 268 | |
| 269 | # loop through the rest of the field_name, doing |
| 270 | # getattr or getitem as needed |
| 271 | for is_attr, i in rest: |
| 272 | if is_attr: |
| 273 | obj = getattr(obj, i) |
| 274 | else: |
| 275 | obj = obj[i] |
| 276 | |
Eric Smith | 3bcc42a | 2007-08-31 02:26:31 +0000 | [diff] [blame] | 277 | return obj, first |