Debian Codegraph @

Lib/string/__init__.py

raw
1 """A collection of string constants.
2
3 Public module variables:
4
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
14
15 """
16
17 __all__ = ["ascii_letters", "ascii_lowercase", "ascii_uppercase", "capwords",
18 "digits", "hexdigits", "octdigits", "printable", "punctuation",
19 "whitespace", "Formatter", "Template"]
20
21 import _string
22
23 # Some strings for ctype-style character classification
24 whitespace = ' \t\n\r\v\f'
25 ascii_lowercase = 'abcdefghijklmnopqrstuvwxyz'
26 ascii_uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
27 ascii_letters = ascii_lowercase + ascii_uppercase
28 digits = '0123456789'
29 hexdigits = digits + 'abcdef' + 'ABCDEF'
30 octdigits = '01234567'
31 punctuation = r"""!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""
32 printable = digits + ascii_letters + punctuation + whitespace
33
34 # Functions which aren't available as string methods.
35
36 # Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
37 def capwords(s, sep=None):
38 """capwords(s [,sep]) -> string
39
40 Split the argument into words using split, capitalize each
41 word using capitalize, and join the capitalized words using
42 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.
46
47 """
48 return (sep or ' ').join(map(str.capitalize, s.split(sep)))
49
50
51 ####################################################################
52 _sentinel_dict = {}
53
54
55 class _TemplatePattern:
56 # This descriptor is overwritten in ``Template._compile_pattern()``.
57 def __get__(self, instance, cls=None):
58 if cls is None:
59 return self
60 return cls._compile_pattern()
61 _TemplatePattern = _TemplatePattern()
62
63
64 class Template:
65 """A string class for supporting $-substitutions."""
66
67 delimiter = '$'
68 # r'[a-z]' matches to non-ASCII letters when used with IGNORECASE, but
69 # without the ASCII flag. We can't add re.ASCII to flags because of
70 # backward compatibility. So we use the ?a local flag and [a-z] pattern.
71 # See https://bugs.python.org/issue31672
72 idpattern = r'(?a:[_a-z][_a-z0-9]*)'
73 braceidpattern = None
74 flags = None # default: re.IGNORECASE
75
76 pattern = _TemplatePattern # use a descriptor to compile the pattern
77
78 def __init_subclass__(cls):
79 super().__init_subclass__()
80 cls._compile_pattern()
81
82 @classmethod
83 def _compile_pattern(cls):
84 import re # deferred import, for performance
85
86 pattern = cls.__dict__.get('pattern', _TemplatePattern)
87 if pattern is _TemplatePattern:
88 delim = re.escape(cls.delimiter)
89 id = cls.idpattern
90 bid = cls.braceidpattern or cls.idpattern
91 pattern = fr"""
92 {delim}(?:
93 (?P<escaped>{delim}) | # Escape sequence of two delimiters
94 (?P<named>{id}) | # delimiter and a Python identifier
95 {{(?P<braced>{bid})}} | # delimiter and a braced identifier
96 (?P<invalid>) # Other ill-formed delimiter exprs
97 )
98 """
99 if cls.flags is None:
100 cls.flags = re.IGNORECASE
101 pat = cls.pattern = re.compile(pattern, cls.flags | re.VERBOSE)
102 return pat
103
104 def __init__(self, template):
105 self.template = template
106
107 # Search for $$, $identifier, ${identifier}, and any bare $'s
108
109 def _invalid(self, mo):
110 i = mo.start('invalid')
111 lines = self.template[:i].splitlines(keepends=True)
112 if not lines:
113 colno = 1
114 lineno = 1
115 else:
116 colno = i - len(''.join(lines[:-1]))
117 lineno = len(lines)
118 raise ValueError('Invalid placeholder in string: line %d, col %d' %
119 (lineno, colno))
120
121 def substitute(self, mapping=_sentinel_dict, /, **kws):
122 if mapping is _sentinel_dict:
123 mapping = kws
124 elif kws:
125 from collections import ChainMap
126 mapping = ChainMap(kws, mapping)
127 # Helper function for .sub()
128 def convert(mo):
129 # Check the most common path first.
130 named = mo.group('named') or mo.group('braced')
131 if named is not None:
132 return str(mapping[named])
133 if mo.group('escaped') is not None:
134 return self.delimiter
135 if mo.group('invalid') is not None:
136 self._invalid(mo)
137 raise ValueError('Unrecognized named group in pattern',
138 self.pattern)
139 return self.pattern.sub(convert, self.template)
140
141 def safe_substitute(self, mapping=_sentinel_dict, /, **kws):
142 if mapping is _sentinel_dict:
143 mapping = kws
144 elif kws:
145 from collections import ChainMap
146 mapping = ChainMap(kws, mapping)
147 # Helper function for .sub()
148 def convert(mo):
149 named = mo.group('named') or mo.group('braced')
150 if named is not None:
151 try:
152 return str(mapping[named])
153 except KeyError:
154 return mo.group()
155 if mo.group('escaped') is not None:
156 return self.delimiter
157 if mo.group('invalid') is not None:
158 return mo.group()
159 raise ValueError('Unrecognized named group in pattern',
160 self.pattern)
161 return self.pattern.sub(convert, self.template)
162
163 def is_valid(self):
164 for mo in self.pattern.finditer(self.template):
165 if mo.group('invalid') is not None:
166 return False
167 if (mo.group('named') is None
168 and mo.group('braced') is None
169 and mo.group('escaped') is None):
170 # If all the groups are None, there must be
171 # another group we're not expecting
172 raise ValueError('Unrecognized named group in pattern',
173 self.pattern)
174 return True
175
176 def get_identifiers(self):
177 ids = []
178 for mo in self.pattern.finditer(self.template):
179 named = mo.group('named') or mo.group('braced')
180 if named is not None and named not in ids:
181 # add a named group only the first time it appears
182 ids.append(named)
183 elif (named is None
184 and mo.group('invalid') is None
185 and mo.group('escaped') is None):
186 # If all the groups are None, there must be
187 # another group we're not expecting
188 raise ValueError('Unrecognized named group in pattern',
189 self.pattern)
190 return ids
191
192
193 ########################################################################
194 # the Formatter class
195 # see PEP 3101 for details and purpose of this class
196
197 # The hard parts are reused from the C implementation. They're exposed as "_"
198 # prefixed methods of str.
199
200 # The overall parser is implemented in _string.formatter_parser.
201 # The field name parser is implemented in _string.formatter_field_name_split
202
203 class Formatter:
204 def format(self, format_string, /, *args, **kwargs):
205 return self.vformat(format_string, args, kwargs)
206
207 def vformat(self, format_string, args, kwargs):
208 used_args = set()
209 result, _ = self._vformat(format_string, args, kwargs, used_args, 2)
210 self.check_unused_args(used_args, args, kwargs)
211 return result
212
213 def _vformat(self, format_string, args, kwargs, used_args, recursion_depth,
214 auto_arg_index=0):
215 if recursion_depth < 0:
216 raise ValueError('Max string recursion exceeded')
217 result = []
218 for literal_text, field_name, format_spec, conversion in \
219 self.parse(format_string):
220
221 # output the literal text
222 if literal_text:
223 result.append(literal_text)
224
225 # if there's a field, output it
226 if field_name is not None:
227 # this is some markup, find the object and do
228 # the formatting
229
230 # handle arg indexing when empty field first parts are given.
231 field_first, _ = _string.formatter_field_name_split(field_name)
232 if field_first == '':
233 if auto_arg_index is False:
234 raise ValueError('cannot switch from manual field '
235 'specification to automatic field '
236 'numbering')
237 field_name = str(auto_arg_index) + field_name
238 auto_arg_index += 1
239 elif isinstance(field_first, int):
240 if auto_arg_index:
241 raise ValueError('cannot switch from automatic field '
242 'numbering to manual field '
243 'specification')
244 # disable auto arg incrementing, if it gets
245 # used later on, then an exception will be raised
246 auto_arg_index = False
247
248 # given the field_name, find the object it references
249 # and the argument it came from
250 obj, arg_used = self.get_field(field_name, args, kwargs)
251 used_args.add(arg_used)
252
253 # do any conversion on the resulting object
254 obj = self.convert_field(obj, conversion)
255
256 # expand the format spec, if needed
257 format_spec, auto_arg_index = self._vformat(
258 format_spec, args, kwargs,
259 used_args, recursion_depth-1,
260 auto_arg_index=auto_arg_index)
261
262 # format the object and append to the result
263 result.append(self.format_field(obj, format_spec))
264
265 return ''.join(result), auto_arg_index
266
267
268 def get_value(self, key, args, kwargs):
269 if isinstance(key, int):
270 return args[key]
271 else:
272 return kwargs[key]
273
274
275 def check_unused_args(self, used_args, args, kwargs):
276 pass
277
278
279 def format_field(self, value, format_spec):
280 return format(value, format_spec)
281
282
283 def convert_field(self, value, conversion):
284 # do any conversion on the resulting object
285 if conversion is None:
286 return value
287 elif conversion == 's':
288 return str(value)
289 elif conversion == 'r':
290 return repr(value)
291 elif conversion == 'a':
292 return ascii(value)
293 raise ValueError("Unknown conversion specifier {0!s}".format(conversion))
294
295
296 # returns an iterable that contains tuples of the form:
297 # (literal_text, field_name, format_spec, conversion)
298 # literal_text can be zero length
299 # field_name can be None, in which case there's no
300 # object to format and output
301 # if field_name is not None, it is looked up, formatted
302 # with format_spec and conversion and then used
303 def parse(self, format_string):
304 return _string.formatter_parser(format_string)
305
306
307 # given a field_name, find the object it references.
308 # field_name: the field being looked up, e.g. "0.name"
309 # or "lookup[3]"
310 # used_args: a set of which args have been used
311 # args, kwargs: as passed in to vformat
312 def get_field(self, field_name, args, kwargs):
313 first, rest = _string.formatter_field_name_split(field_name)
314
315 obj = self.get_value(first, args, kwargs)
316
317 # loop through the rest of the field_name, doing
318 # getattr or getitem as needed
319 for is_attr, i in rest:
320 if is_attr:
321 obj = getattr(obj, i)
322 else:
323 obj = obj[i]
324
325 return obj, first