blob: b46e60c38f49280a993a1cc82d19e62901e1bb17 [file] [log] [blame]
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001"""A collection of string constants.
Guido van Rossum20032041997-12-29 19:26:28 +00002
3Public module variables:
4
Georg Brandl50767402008-11-22 08:31:09 +00005whitespace -- a string containing all ASCII whitespace
6ascii_lowercase -- a string containing all ASCII lowercase letters
7ascii_uppercase -- a string containing all ASCII uppercase letters
8ascii_letters -- a string containing all ASCII letters
9digits -- a string containing all ASCII decimal digits
10hexdigits -- a string containing all ASCII hexadecimal digits
11octdigits -- a string containing all ASCII octal digits
12punctuation -- a string containing all ASCII punctuation characters
13printable -- a string containing all ASCII characters considered printable
Guido van Rossum20032041997-12-29 19:26:28 +000014
15"""
16
Zachary Warec17a0b82016-06-04 14:35:05 -050017__all__ = ["ascii_letters", "ascii_lowercase", "ascii_uppercase", "capwords",
18 "digits", "hexdigits", "octdigits", "printable", "punctuation",
19 "whitespace", "Formatter", "Template"]
20
Georg Brandl66c221e2010-10-14 07:04:07 +000021import _string
22
Guido van Rossumc6360141990-10-13 19:23:40 +000023# Some strings for ctype-style character classification
Guido van Rossum8e2ec561993-07-29 09:37:38 +000024whitespace = ' \t\n\r\v\f'
Martin v. Löwis967f1e32007-08-14 09:23:10 +000025ascii_lowercase = 'abcdefghijklmnopqrstuvwxyz'
26ascii_uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
Fred Drake960fdf92001-07-20 18:38:26 +000027ascii_letters = ascii_lowercase + ascii_uppercase
Guido van Rossumc6360141990-10-13 19:23:40 +000028digits = '0123456789'
29hexdigits = digits + 'abcdef' + 'ABCDEF'
30octdigits = '01234567'
R David Murray44b548d2016-09-08 13:59:53 -040031punctuation = r"""!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""
Martin v. Löwis967f1e32007-08-14 09:23:10 +000032printable = digits + ascii_letters + punctuation + whitespace
Guido van Rossumc6360141990-10-13 19:23:40 +000033
Barry Warsaw8bee7612004-08-25 02:22:30 +000034# Functions which aren't available as string methods.
35
36# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
Barry Warsaw8bee7612004-08-25 02:22:30 +000037def capwords(s, sep=None):
Ezio Melottia40bdda2009-09-26 12:33:22 +000038 """capwords(s [,sep]) -> string
Barry Warsaw8bee7612004-08-25 02:22:30 +000039
40 Split the argument into words using split, capitalize each
41 word using capitalize, and join the capitalized words using
Ezio Melottia40bdda2009-09-26 12:33:22 +000042 join. If the optional second argument sep is absent or None,
43 runs of whitespace characters are replaced by a single space
44 and leading and trailing whitespace are removed, otherwise
45 sep is used to split and join the words.
Barry Warsaw8bee7612004-08-25 02:22:30 +000046
47 """
Ezio Melottia40bdda2009-09-26 12:33:22 +000048 return (sep or ' ').join(x.capitalize() for x in s.split(sep))
Barry Warsaw8bee7612004-08-25 02:22:30 +000049
50
Raymond Hettinger0d58e2b2004-08-26 00:21:13 +000051####################################################################
Barry Warsaw8bee7612004-08-25 02:22:30 +000052import re as _re
Zachary Warec17a0b82016-06-04 14:35:05 -050053from collections import ChainMap as _ChainMap
Barry Warsaw46b629c2004-09-13 14:35:04 +000054
Barry Warsaw12827c12004-09-10 03:08:08 +000055class _TemplateMetaclass(type):
56 pattern = r"""
Raymond Hettinger55593c32004-09-26 18:56:44 +000057 %(delim)s(?:
58 (?P<escaped>%(delim)s) | # Escape sequence of two delimiters
59 (?P<named>%(id)s) | # delimiter and a Python identifier
Barry Warsawba427962017-09-04 16:32:10 -040060 {(?P<braced>%(bid)s)} | # delimiter and a braced identifier
Raymond Hettinger55593c32004-09-26 18:56:44 +000061 (?P<invalid>) # Other ill-formed delimiter exprs
62 )
Barry Warsaw12827c12004-09-10 03:08:08 +000063 """
64
65 def __init__(cls, name, bases, dct):
66 super(_TemplateMetaclass, cls).__init__(name, bases, dct)
67 if 'pattern' in dct:
68 pattern = cls.pattern
69 else:
70 pattern = _TemplateMetaclass.pattern % {
Barry Warsaw17cb6002004-09-18 00:06:34 +000071 'delim' : _re.escape(cls.delimiter),
Barry Warsaw12827c12004-09-10 03:08:08 +000072 'id' : cls.idpattern,
Barry Warsawba427962017-09-04 16:32:10 -040073 'bid' : cls.braceidpattern or cls.idpattern,
Barry Warsaw12827c12004-09-10 03:08:08 +000074 }
Georg Brandl056cb932010-07-29 17:16:10 +000075 cls.pattern = _re.compile(pattern, cls.flags | _re.VERBOSE)
Barry Warsaw12827c12004-09-10 03:08:08 +000076
77
Guido van Rossum52cc1d82007-03-18 15:41:51 +000078class Template(metaclass=_TemplateMetaclass):
Barry Warsaw8bee7612004-08-25 02:22:30 +000079 """A string class for supporting $-substitutions."""
Barry Warsaw12827c12004-09-10 03:08:08 +000080
Barry Warsaw17cb6002004-09-18 00:06:34 +000081 delimiter = '$'
Barry Warsaw12827c12004-09-10 03:08:08 +000082 idpattern = r'[_a-z][_a-z0-9]*'
Barry Warsawba427962017-09-04 16:32:10 -040083 braceidpattern = None
Georg Brandl056cb932010-07-29 17:16:10 +000084 flags = _re.IGNORECASE
Barry Warsaw12827c12004-09-10 03:08:08 +000085
86 def __init__(self, template):
87 self.template = template
Barry Warsaw8bee7612004-08-25 02:22:30 +000088
89 # Search for $$, $identifier, ${identifier}, and any bare $'s
Barry Warsaw8bee7612004-08-25 02:22:30 +000090
Barry Warsawb5c6b5b2004-09-13 20:52:50 +000091 def _invalid(self, mo):
92 i = mo.start('invalid')
Ezio Melottid8b509b2011-09-28 17:37:55 +030093 lines = self.template[:i].splitlines(keepends=True)
Barry Warsaw12827c12004-09-10 03:08:08 +000094 if not lines:
95 colno = 1
96 lineno = 1
97 else:
98 colno = i - len(''.join(lines[:-1]))
99 lineno = len(lines)
100 raise ValueError('Invalid placeholder in string: line %d, col %d' %
101 (lineno, colno))
102
Serhiy Storchaka8ffe9172015-03-24 22:28:43 +0200103 def substitute(*args, **kws):
104 if not args:
105 raise TypeError("descriptor 'substitute' of 'Template' object "
106 "needs an argument")
107 self, *args = args # allow the "self" keyword be passed
Barry Warsawb6234a92004-09-13 15:25:15 +0000108 if len(args) > 1:
109 raise TypeError('Too many positional arguments')
110 if not args:
111 mapping = kws
Barry Warsaw46b629c2004-09-13 14:35:04 +0000112 elif kws:
Zachary Warec17a0b82016-06-04 14:35:05 -0500113 mapping = _ChainMap(kws, args[0])
Barry Warsawb6234a92004-09-13 15:25:15 +0000114 else:
115 mapping = args[0]
Barry Warsaw46b629c2004-09-13 14:35:04 +0000116 # Helper function for .sub()
Barry Warsaw8bee7612004-08-25 02:22:30 +0000117 def convert(mo):
Barry Warsawb5c6b5b2004-09-13 20:52:50 +0000118 # Check the most common path first.
119 named = mo.group('named') or mo.group('braced')
120 if named is not None:
Serhiy Storchaka6e6883f2015-05-28 20:45:29 +0300121 return str(mapping[named])
Raymond Hettinger0d58e2b2004-08-26 00:21:13 +0000122 if mo.group('escaped') is not None:
Barry Warsaw17cb6002004-09-18 00:06:34 +0000123 return self.delimiter
Barry Warsawb5c6b5b2004-09-13 20:52:50 +0000124 if mo.group('invalid') is not None:
125 self._invalid(mo)
Neal Norwitz6627a962004-10-17 16:27:18 +0000126 raise ValueError('Unrecognized named group in pattern',
127 self.pattern)
Barry Warsaw12827c12004-09-10 03:08:08 +0000128 return self.pattern.sub(convert, self.template)
Barry Warsaw8bee7612004-08-25 02:22:30 +0000129
Serhiy Storchaka8ffe9172015-03-24 22:28:43 +0200130 def safe_substitute(*args, **kws):
131 if not args:
132 raise TypeError("descriptor 'safe_substitute' of 'Template' object "
133 "needs an argument")
134 self, *args = args # allow the "self" keyword be passed
Barry Warsawb6234a92004-09-13 15:25:15 +0000135 if len(args) > 1:
136 raise TypeError('Too many positional arguments')
137 if not args:
138 mapping = kws
Barry Warsaw46b629c2004-09-13 14:35:04 +0000139 elif kws:
Zachary Warec17a0b82016-06-04 14:35:05 -0500140 mapping = _ChainMap(kws, args[0])
Barry Warsawb6234a92004-09-13 15:25:15 +0000141 else:
142 mapping = args[0]
Barry Warsaw46b629c2004-09-13 14:35:04 +0000143 # Helper function for .sub()
Barry Warsaw8bee7612004-08-25 02:22:30 +0000144 def convert(mo):
Florent Xiclunaeb19dce2010-09-18 23:34:07 +0000145 named = mo.group('named') or mo.group('braced')
Barry Warsaw8bee7612004-08-25 02:22:30 +0000146 if named is not None:
147 try:
Serhiy Storchaka6e6883f2015-05-28 20:45:29 +0300148 return str(mapping[named])
Barry Warsaw8bee7612004-08-25 02:22:30 +0000149 except KeyError:
Florent Xiclunaeb19dce2010-09-18 23:34:07 +0000150 return mo.group()
Barry Warsawb5c6b5b2004-09-13 20:52:50 +0000151 if mo.group('escaped') is not None:
Barry Warsaw17cb6002004-09-18 00:06:34 +0000152 return self.delimiter
Barry Warsawb5c6b5b2004-09-13 20:52:50 +0000153 if mo.group('invalid') is not None:
Florent Xiclunaeb19dce2010-09-18 23:34:07 +0000154 return mo.group()
Neal Norwitz6627a962004-10-17 16:27:18 +0000155 raise ValueError('Unrecognized named group in pattern',
156 self.pattern)
Barry Warsaw12827c12004-09-10 03:08:08 +0000157 return self.pattern.sub(convert, self.template)
Eric Smith8c663262007-08-25 02:26:07 +0000158
159
160
161########################################################################
162# the Formatter class
163# see PEP 3101 for details and purpose of this class
164
Benjamin Petersonf608c612008-11-16 18:33:53 +0000165# The hard parts are reused from the C implementation. They're exposed as "_"
Florent Xicluna7b2a7712010-09-06 20:27:55 +0000166# prefixed methods of str.
Eric Smith8c663262007-08-25 02:26:07 +0000167
Georg Brandl66c221e2010-10-14 07:04:07 +0000168# The overall parser is implemented in _string.formatter_parser.
169# The field name parser is implemented in _string.formatter_field_name_split
Eric Smith8c663262007-08-25 02:26:07 +0000170
171class Formatter:
Serhiy Storchaka8ffe9172015-03-24 22:28:43 +0200172 def format(*args, **kwargs):
173 if not args:
174 raise TypeError("descriptor 'format' of 'Formatter' object "
175 "needs an argument")
176 self, *args = args # allow the "self" keyword be passed
177 try:
178 format_string, *args = args # allow the "format_string" keyword be passed
179 except ValueError:
Serhiy Storchaka009b0a12017-01-13 09:10:51 +0200180 raise TypeError("format() missing 1 required positional "
181 "argument: 'format_string'") from None
Eric Smith8c663262007-08-25 02:26:07 +0000182 return self.vformat(format_string, args, kwargs)
183
184 def vformat(self, format_string, args, kwargs):
Eric Smith3bcc42a2007-08-31 02:26:31 +0000185 used_args = set()
Eric V. Smith85976b12015-09-29 10:27:38 -0400186 result, _ = self._vformat(format_string, args, kwargs, used_args, 2)
Eric Smith11529192007-09-04 23:04:22 +0000187 self.check_unused_args(used_args, args, kwargs)
188 return result
189
Eric V. Smith7ce90742014-04-14 16:43:50 -0400190 def _vformat(self, format_string, args, kwargs, used_args, recursion_depth,
191 auto_arg_index=0):
Eric Smith11529192007-09-04 23:04:22 +0000192 if recursion_depth < 0:
193 raise ValueError('Max string recursion exceeded')
Eric Smith8c663262007-08-25 02:26:07 +0000194 result = []
Eric Smith9e7c8da2007-08-28 11:15:20 +0000195 for literal_text, field_name, format_spec, conversion in \
196 self.parse(format_string):
Eric Smith625cbf22007-08-29 03:22:59 +0000197
198 # output the literal text
199 if literal_text:
200 result.append(literal_text)
201
202 # if there's a field, output it
203 if field_name is not None:
Eric Smith9e7c8da2007-08-28 11:15:20 +0000204 # this is some markup, find the object and do
205 # the formatting
206
Eric V. Smith7ce90742014-04-14 16:43:50 -0400207 # handle arg indexing when empty field_names are given.
208 if field_name == '':
209 if auto_arg_index is False:
210 raise ValueError('cannot switch from manual field '
211 'specification to automatic field '
212 'numbering')
213 field_name = str(auto_arg_index)
214 auto_arg_index += 1
215 elif field_name.isdigit():
216 if auto_arg_index:
217 raise ValueError('cannot switch from manual field '
218 'specification to automatic field '
219 'numbering')
220 # disable auto arg incrementing, if it gets
221 # used later on, then an exception will be raised
222 auto_arg_index = False
223
Eric Smith7ade6482007-08-26 22:27:13 +0000224 # given the field_name, find the object it references
Eric Smith3bcc42a2007-08-31 02:26:31 +0000225 # and the argument it came from
Eric Smith9d4ba392007-09-02 15:33:26 +0000226 obj, arg_used = self.get_field(field_name, args, kwargs)
Eric Smith3bcc42a2007-08-31 02:26:31 +0000227 used_args.add(arg_used)
Eric Smith7ade6482007-08-26 22:27:13 +0000228
229 # do any conversion on the resulting object
Eric Smith9e7c8da2007-08-28 11:15:20 +0000230 obj = self.convert_field(obj, conversion)
Eric Smith7ade6482007-08-26 22:27:13 +0000231
Eric Smith11529192007-09-04 23:04:22 +0000232 # expand the format spec, if needed
Eric V. Smith85976b12015-09-29 10:27:38 -0400233 format_spec, auto_arg_index = self._vformat(
234 format_spec, args, kwargs,
235 used_args, recursion_depth-1,
236 auto_arg_index=auto_arg_index)
Eric Smith11529192007-09-04 23:04:22 +0000237
Eric Smith7ade6482007-08-26 22:27:13 +0000238 # format the object and append to the result
239 result.append(self.format_field(obj, format_spec))
Eric Smith625cbf22007-08-29 03:22:59 +0000240
Eric V. Smith85976b12015-09-29 10:27:38 -0400241 return ''.join(result), auto_arg_index
Eric Smith8c663262007-08-25 02:26:07 +0000242
Eric Smith9e7c8da2007-08-28 11:15:20 +0000243
Eric Smith8c663262007-08-25 02:26:07 +0000244 def get_value(self, key, args, kwargs):
Eric Smith7ade6482007-08-26 22:27:13 +0000245 if isinstance(key, int):
246 return args[key]
247 else:
248 return kwargs[key]
Eric Smith8c663262007-08-25 02:26:07 +0000249
Eric Smith9e7c8da2007-08-28 11:15:20 +0000250
Eric Smith8c663262007-08-25 02:26:07 +0000251 def check_unused_args(self, used_args, args, kwargs):
252 pass
253
Eric Smith9e7c8da2007-08-28 11:15:20 +0000254
Eric Smith8c663262007-08-25 02:26:07 +0000255 def format_field(self, value, format_spec):
Eric Smith7ade6482007-08-26 22:27:13 +0000256 return format(value, format_spec)
Eric Smith9e7c8da2007-08-28 11:15:20 +0000257
258
259 def convert_field(self, value, conversion):
260 # do any conversion on the resulting object
R David Murraye56bf972012-08-19 17:26:34 -0400261 if conversion is None:
262 return value
Eric Smith9e7c8da2007-08-28 11:15:20 +0000263 elif conversion == 's':
264 return str(value)
R David Murraye56bf972012-08-19 17:26:34 -0400265 elif conversion == 'r':
266 return repr(value)
267 elif conversion == 'a':
268 return ascii(value)
Florent Xicluna7b2a7712010-09-06 20:27:55 +0000269 raise ValueError("Unknown conversion specifier {0!s}".format(conversion))
Eric Smith9e7c8da2007-08-28 11:15:20 +0000270
271
272 # returns an iterable that contains tuples of the form:
273 # (literal_text, field_name, format_spec, conversion)
Eric Smith625cbf22007-08-29 03:22:59 +0000274 # literal_text can be zero length
275 # field_name can be None, in which case there's no
276 # object to format and output
277 # if field_name is not None, it is looked up, formatted
278 # with format_spec and conversion and then used
Eric Smith9e7c8da2007-08-28 11:15:20 +0000279 def parse(self, format_string):
Georg Brandl66c221e2010-10-14 07:04:07 +0000280 return _string.formatter_parser(format_string)
Eric Smith9e7c8da2007-08-28 11:15:20 +0000281
282
283 # given a field_name, find the object it references.
284 # field_name: the field being looked up, e.g. "0.name"
285 # or "lookup[3]"
286 # used_args: a set of which args have been used
287 # args, kwargs: as passed in to vformat
Eric Smith9d4ba392007-09-02 15:33:26 +0000288 def get_field(self, field_name, args, kwargs):
Georg Brandl66c221e2010-10-14 07:04:07 +0000289 first, rest = _string.formatter_field_name_split(field_name)
Eric Smith9e7c8da2007-08-28 11:15:20 +0000290
Eric Smith9e7c8da2007-08-28 11:15:20 +0000291 obj = self.get_value(first, args, kwargs)
292
293 # loop through the rest of the field_name, doing
294 # getattr or getitem as needed
295 for is_attr, i in rest:
296 if is_attr:
297 obj = getattr(obj, i)
298 else:
299 obj = obj[i]
300
Eric Smith3bcc42a2007-08-31 02:26:31 +0000301 return obj, first