Python code coverage for Lib/formatter.py

#	count	content
1	n/a	"""Generic output formatting.
2	n/a
3	n/a	Formatter objects transform an abstract flow of formatting events into
4	n/a	specific output events on writer objects. Formatters manage several stack
5	n/a	structures to allow various properties of a writer object to be changed and
6	n/a	restored; writers need not be able to handle relative changes nor any sort
7	n/a	of ``change back'' operation. Specific writer properties which may be
8	n/a	controlled via formatter objects are horizontal alignment, font, and left
9	n/a	margin indentations. A mechanism is provided which supports providing
10	n/a	arbitrary, non-exclusive style settings to a writer as well. Additional
11	n/a	interfaces facilitate formatting events which are not reversible, such as
12	n/a	paragraph separation.
13	n/a
14	n/a	Writer objects encapsulate device interfaces. Abstract devices, such as
15	n/a	file formats, are supported as well as physical devices. The provided
16	n/a	implementations all work with abstract devices. The interface makes
17	n/a	available mechanisms for setting the properties which formatter objects
18	n/a	manage and inserting data into the output.
19	n/a	"""
20	n/a
21	n/a	import sys
22	n/a	import warnings
23	n/a	warnings.warn('the formatter module is deprecated', DeprecationWarning,
24	n/a	stacklevel=2)
25	n/a
26	n/a
27	n/a	AS_IS = None
28	n/a
29	n/a
30	n/a	class NullFormatter:
31	n/a	"""A formatter which does nothing.
32	n/a
33	n/a	If the writer parameter is omitted, a NullWriter instance is created.
34	n/a	No methods of the writer are called by NullFormatter instances.
35	n/a
36	n/a	Implementations should inherit from this class if implementing a writer
37	n/a	interface but don't need to inherit any implementation.
38	n/a
39	n/a	"""
40	n/a
41	n/a	def __init__(self, writer=None):
42	n/a	if writer is None:
43	n/a	writer = NullWriter()
44	n/a	self.writer = writer
45	n/a	def end_paragraph(self, blankline): pass
46	n/a	def add_line_break(self): pass
47	n/a	def add_hor_rule(self, args, *kw): pass
48	n/a	def add_label_data(self, format, counter, blankline=None): pass
49	n/a	def add_flowing_data(self, data): pass
50	n/a	def add_literal_data(self, data): pass
51	n/a	def flush_softspace(self): pass
52	n/a	def push_alignment(self, align): pass
53	n/a	def pop_alignment(self): pass
54	n/a	def push_font(self, x): pass
55	n/a	def pop_font(self): pass
56	n/a	def push_margin(self, margin): pass
57	n/a	def pop_margin(self): pass
58	n/a	def set_spacing(self, spacing): pass
59	n/a	def push_style(self, *styles): pass
60	n/a	def pop_style(self, n=1): pass
61	n/a	def assert_line_data(self, flag=1): pass
62	n/a
63	n/a
64	n/a	class AbstractFormatter:
65	n/a	"""The standard formatter.
66	n/a
67	n/a	This implementation has demonstrated wide applicability to many writers,
68	n/a	and may be used directly in most circumstances. It has been used to
69	n/a	implement a full-featured World Wide Web browser.
70	n/a
71	n/a	"""
72	n/a
73	n/a	# Space handling policy: blank spaces at the boundary between elements
74	n/a	# are handled by the outermost context. "Literal" data is not checked
75	n/a	# to determine context, so spaces in literal data are handled directly
76	n/a	# in all circumstances.
77	n/a
78	n/a	def __init__(self, writer):
79	n/a	self.writer = writer # Output device
80	n/a	self.align = None # Current alignment
81	n/a	self.align_stack = [] # Alignment stack
82	n/a	self.font_stack = [] # Font state
83	n/a	self.margin_stack = [] # Margin state
84	n/a	self.spacing = None # Vertical spacing state
85	n/a	self.style_stack = [] # Other state, e.g. color
86	n/a	self.nospace = 1 # Should leading space be suppressed
87	n/a	self.softspace = 0 # Should a space be inserted
88	n/a	self.para_end = 1 # Just ended a paragraph
89	n/a	self.parskip = 0 # Skipped space between paragraphs?
90	n/a	self.hard_break = 1 # Have a hard break
91	n/a	self.have_label = 0
92	n/a
93	n/a	def end_paragraph(self, blankline):
94	n/a	if not self.hard_break:
95	n/a	self.writer.send_line_break()
96	n/a	self.have_label = 0
97	n/a	if self.parskip < blankline and not self.have_label:
98	n/a	self.writer.send_paragraph(blankline - self.parskip)
99	n/a	self.parskip = blankline
100	n/a	self.have_label = 0
101	n/a	self.hard_break = self.nospace = self.para_end = 1
102	n/a	self.softspace = 0
103	n/a
104	n/a	def add_line_break(self):
105	n/a	if not (self.hard_break or self.para_end):
106	n/a	self.writer.send_line_break()
107	n/a	self.have_label = self.parskip = 0
108	n/a	self.hard_break = self.nospace = 1
109	n/a	self.softspace = 0
110	n/a
111	n/a	def add_hor_rule(self, args, *kw):
112	n/a	if not self.hard_break:
113	n/a	self.writer.send_line_break()
114	n/a	self.writer.send_hor_rule(args, *kw)
115	n/a	self.hard_break = self.nospace = 1
116	n/a	self.have_label = self.para_end = self.softspace = self.parskip = 0
117	n/a
118	n/a	def add_label_data(self, format, counter, blankline = None):
119	n/a	if self.have_label or not self.hard_break:
120	n/a	self.writer.send_line_break()
121	n/a	if not self.para_end:
122	n/a	self.writer.send_paragraph((blankline and 1) or 0)
123	n/a	if isinstance(format, str):
124	n/a	self.writer.send_label_data(self.format_counter(format, counter))
125	n/a	else:
126	n/a	self.writer.send_label_data(format)
127	n/a	self.nospace = self.have_label = self.hard_break = self.para_end = 1
128	n/a	self.softspace = self.parskip = 0
129	n/a
130	n/a	def format_counter(self, format, counter):
131	n/a	label = ''
132	n/a	for c in format:
133	n/a	if c == '1':
134	n/a	label = label + ('%d' % counter)
135	n/a	elif c in 'aA':
136	n/a	if counter > 0:
137	n/a	label = label + self.format_letter(c, counter)
138	n/a	elif c in 'iI':
139	n/a	if counter > 0:
140	n/a	label = label + self.format_roman(c, counter)
141	n/a	else:
142	n/a	label = label + c
143	n/a	return label
144	n/a
145	n/a	def format_letter(self, case, counter):
146	n/a	label = ''
147	n/a	while counter > 0:
148	n/a	counter, x = divmod(counter-1, 26)
149	n/a	# This makes a strong assumption that lowercase letters
150	n/a	# and uppercase letters form two contiguous blocks, with
151	n/a	# letters in order!
152	n/a	s = chr(ord(case) + x)
153	n/a	label = s + label
154	n/a	return label
155	n/a
156	n/a	def format_roman(self, case, counter):
157	n/a	ones = ['i', 'x', 'c', 'm']
158	n/a	fives = ['v', 'l', 'd']
159	n/a	label, index = '', 0
160	n/a	# This will die of IndexError when counter is too big
161	n/a	while counter > 0:
162	n/a	counter, x = divmod(counter, 10)
163	n/a	if x == 9:
164	n/a	label = ones[index] + ones[index+1] + label
165	n/a	elif x == 4:
166	n/a	label = ones[index] + fives[index] + label
167	n/a	else:
168	n/a	if x >= 5:
169	n/a	s = fives[index]
170	n/a	x = x-5
171	n/a	else:
172	n/a	s = ''
173	n/a	s = s + ones[index]*x
174	n/a	label = s + label
175	n/a	index = index + 1
176	n/a	if case == 'I':
177	n/a	return label.upper()
178	n/a	return label
179	n/a
180	n/a	def add_flowing_data(self, data):
181	n/a	if not data: return
182	n/a	prespace = data[:1].isspace()
183	n/a	postspace = data[-1:].isspace()
184	n/a	data = " ".join(data.split())
185	n/a	if self.nospace and not data:
186	n/a	return
187	n/a	elif prespace or self.softspace:
188	n/a	if not data:
189	n/a	if not self.nospace:
190	n/a	self.softspace = 1
191	n/a	self.parskip = 0
192	n/a	return
193	n/a	if not self.nospace:
194	n/a	data = ' ' + data
195	n/a	self.hard_break = self.nospace = self.para_end = \
196	n/a	self.parskip = self.have_label = 0
197	n/a	self.softspace = postspace
198	n/a	self.writer.send_flowing_data(data)
199	n/a
200	n/a	def add_literal_data(self, data):
201	n/a	if not data: return
202	n/a	if self.softspace:
203	n/a	self.writer.send_flowing_data(" ")
204	n/a	self.hard_break = data[-1:] == '\n'
205	n/a	self.nospace = self.para_end = self.softspace = \
206	n/a	self.parskip = self.have_label = 0
207	n/a	self.writer.send_literal_data(data)
208	n/a
209	n/a	def flush_softspace(self):
210	n/a	if self.softspace:
211	n/a	self.hard_break = self.para_end = self.parskip = \
212	n/a	self.have_label = self.softspace = 0
213	n/a	self.nospace = 1
214	n/a	self.writer.send_flowing_data(' ')
215	n/a
216	n/a	def push_alignment(self, align):
217	n/a	if align and align != self.align:
218	n/a	self.writer.new_alignment(align)
219	n/a	self.align = align
220	n/a	self.align_stack.append(align)
221	n/a	else:
222	n/a	self.align_stack.append(self.align)
223	n/a
224	n/a	def pop_alignment(self):
225	n/a	if self.align_stack:
226	n/a	del self.align_stack[-1]
227	n/a	if self.align_stack:
228	n/a	self.align = align = self.align_stack[-1]
229	n/a	self.writer.new_alignment(align)
230	n/a	else:
231	n/a	self.align = None
232	n/a	self.writer.new_alignment(None)
233	n/a
234	n/a	def push_font(self, font):
235	n/a	size, i, b, tt = font
236	n/a	if self.softspace:
237	n/a	self.hard_break = self.para_end = self.softspace = 0
238	n/a	self.nospace = 1
239	n/a	self.writer.send_flowing_data(' ')
240	n/a	if self.font_stack:
241	n/a	csize, ci, cb, ctt = self.font_stack[-1]
242	n/a	if size is AS_IS: size = csize
243	n/a	if i is AS_IS: i = ci
244	n/a	if b is AS_IS: b = cb
245	n/a	if tt is AS_IS: tt = ctt
246	n/a	font = (size, i, b, tt)
247	n/a	self.font_stack.append(font)
248	n/a	self.writer.new_font(font)
249	n/a
250	n/a	def pop_font(self):
251	n/a	if self.font_stack:
252	n/a	del self.font_stack[-1]
253	n/a	if self.font_stack:
254	n/a	font = self.font_stack[-1]
255	n/a	else:
256	n/a	font = None
257	n/a	self.writer.new_font(font)
258	n/a
259	n/a	def push_margin(self, margin):
260	n/a	self.margin_stack.append(margin)
261	n/a	fstack = [m for m in self.margin_stack if m]
262	n/a	if not margin and fstack:
263	n/a	margin = fstack[-1]
264	n/a	self.writer.new_margin(margin, len(fstack))
265	n/a
266	n/a	def pop_margin(self):
267	n/a	if self.margin_stack:
268	n/a	del self.margin_stack[-1]
269	n/a	fstack = [m for m in self.margin_stack if m]
270	n/a	if fstack:
271	n/a	margin = fstack[-1]
272	n/a	else:
273	n/a	margin = None
274	n/a	self.writer.new_margin(margin, len(fstack))
275	n/a
276	n/a	def set_spacing(self, spacing):
277	n/a	self.spacing = spacing
278	n/a	self.writer.new_spacing(spacing)
279	n/a
280	n/a	def push_style(self, *styles):
281	n/a	if self.softspace:
282	n/a	self.hard_break = self.para_end = self.softspace = 0
283	n/a	self.nospace = 1
284	n/a	self.writer.send_flowing_data(' ')
285	n/a	for style in styles:
286	n/a	self.style_stack.append(style)
287	n/a	self.writer.new_styles(tuple(self.style_stack))
288	n/a
289	n/a	def pop_style(self, n=1):
290	n/a	del self.style_stack[-n:]
291	n/a	self.writer.new_styles(tuple(self.style_stack))
292	n/a
293	n/a	def assert_line_data(self, flag=1):
294	n/a	self.nospace = self.hard_break = not flag
295	n/a	self.para_end = self.parskip = self.have_label = 0
296	n/a
297	n/a
298	n/a	class NullWriter:
299	n/a	"""Minimal writer interface to use in testing & inheritance.
300	n/a
301	n/a	A writer which only provides the interface definition; no actions are
302	n/a	taken on any methods. This should be the base class for all writers
303	n/a	which do not need to inherit any implementation methods.
304	n/a
305	n/a	"""
306	n/a	def __init__(self): pass
307	n/a	def flush(self): pass
308	n/a	def new_alignment(self, align): pass
309	n/a	def new_font(self, font): pass
310	n/a	def new_margin(self, margin, level): pass
311	n/a	def new_spacing(self, spacing): pass
312	n/a	def new_styles(self, styles): pass
313	n/a	def send_paragraph(self, blankline): pass
314	n/a	def send_line_break(self): pass
315	n/a	def send_hor_rule(self, args, *kw): pass
316	n/a	def send_label_data(self, data): pass
317	n/a	def send_flowing_data(self, data): pass
318	n/a	def send_literal_data(self, data): pass
319	n/a
320	n/a
321	n/a	class AbstractWriter(NullWriter):
322	n/a	"""A writer which can be used in debugging formatters, but not much else.
323	n/a
324	n/a	Each method simply announces itself by printing its name and
325	n/a	arguments on standard output.
326	n/a
327	n/a	"""
328	n/a
329	n/a	def new_alignment(self, align):
330	n/a	print("new_alignment(%r)" % (align,))
331	n/a
332	n/a	def new_font(self, font):
333	n/a	print("new_font(%r)" % (font,))
334	n/a
335	n/a	def new_margin(self, margin, level):
336	n/a	print("new_margin(%r, %d)" % (margin, level))
337	n/a
338	n/a	def new_spacing(self, spacing):
339	n/a	print("new_spacing(%r)" % (spacing,))
340	n/a
341	n/a	def new_styles(self, styles):
342	n/a	print("new_styles(%r)" % (styles,))
343	n/a
344	n/a	def send_paragraph(self, blankline):
345	n/a	print("send_paragraph(%r)" % (blankline,))
346	n/a
347	n/a	def send_line_break(self):
348	n/a	print("send_line_break()")
349	n/a
350	n/a	def send_hor_rule(self, args, *kw):
351	n/a	print("send_hor_rule()")
352	n/a
353	n/a	def send_label_data(self, data):
354	n/a	print("send_label_data(%r)" % (data,))
355	n/a
356	n/a	def send_flowing_data(self, data):
357	n/a	print("send_flowing_data(%r)" % (data,))
358	n/a
359	n/a	def send_literal_data(self, data):
360	n/a	print("send_literal_data(%r)" % (data,))
361	n/a
362	n/a
363	n/a	class DumbWriter(NullWriter):
364	n/a	"""Simple writer class which writes output on the file object passed in
365	n/a	as the file parameter or, if file is omitted, on standard output. The
366	n/a	output is simply word-wrapped to the number of columns specified by
367	n/a	the maxcol parameter. This class is suitable for reflowing a sequence
368	n/a	of paragraphs.
369	n/a
370	n/a	"""
371	n/a
372	n/a	def __init__(self, file=None, maxcol=72):
373	n/a	self.file = file or sys.stdout
374	n/a	self.maxcol = maxcol
375	n/a	NullWriter.__init__(self)
376	n/a	self.reset()
377	n/a
378	n/a	def reset(self):
379	n/a	self.col = 0
380	n/a	self.atbreak = 0
381	n/a
382	n/a	def send_paragraph(self, blankline):
383	n/a	self.file.write('\n'*blankline)
384	n/a	self.col = 0
385	n/a	self.atbreak = 0
386	n/a
387	n/a	def send_line_break(self):
388	n/a	self.file.write('\n')
389	n/a	self.col = 0
390	n/a	self.atbreak = 0
391	n/a
392	n/a	def send_hor_rule(self, args, *kw):
393	n/a	self.file.write('\n')
394	n/a	self.file.write('-'*self.maxcol)
395	n/a	self.file.write('\n')
396	n/a	self.col = 0
397	n/a	self.atbreak = 0
398	n/a
399	n/a	def send_literal_data(self, data):
400	n/a	self.file.write(data)
401	n/a	i = data.rfind('\n')
402	n/a	if i >= 0:
403	n/a	self.col = 0
404	n/a	data = data[i+1:]
405	n/a	data = data.expandtabs()
406	n/a	self.col = self.col + len(data)
407	n/a	self.atbreak = 0
408	n/a
409	n/a	def send_flowing_data(self, data):
410	n/a	if not data: return
411	n/a	atbreak = self.atbreak or data[0].isspace()
412	n/a	col = self.col
413	n/a	maxcol = self.maxcol
414	n/a	write = self.file.write
415	n/a	for word in data.split():
416	n/a	if atbreak:
417	n/a	if col + len(word) >= maxcol:
418	n/a	write('\n')
419	n/a	col = 0
420	n/a	else:
421	n/a	write(' ')
422	n/a	col = col + 1
423	n/a	write(word)
424	n/a	col = col + len(word)
425	n/a	atbreak = 1
426	n/a	self.col = col
427	n/a	self.atbreak = data[-1].isspace()
428	n/a
429	n/a
430	n/a	def test(file = None):
431	n/a	w = DumbWriter()
432	n/a	f = AbstractFormatter(w)
433	n/a	if file is not None:
434	n/a	fp = open(file)
435	n/a	elif sys.argv[1:]:
436	n/a	fp = open(sys.argv[1])
437	n/a	else:
438	n/a	fp = sys.stdin
439	n/a	try:
440	n/a	for line in fp:
441	n/a	if line == '\n':
442	n/a	f.end_paragraph(1)
443	n/a	else:
444	n/a	f.add_flowing_data(line)
445	n/a	finally:
446	n/a	if fp is not sys.stdin:
447	n/a	fp.close()
448	n/a	f.end_paragraph(0)
449	n/a
450	n/a
451	n/a	if __name__ == '__main__':
452	n/a	test()