Python code coverage for Lib/string.py

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