Python code coverage for Lib/distutils/text_file.py

#	count	content
1	n/a	"""text_file
2	n/a
3	n/a	provides the TextFile class, which gives an interface to text files
4	n/a	that (optionally) takes care of stripping comments, ignoring blank
5	n/a	lines, and joining lines with backslashes."""
6	n/a
7	n/a	import sys, io
8	n/a
9	n/a
10	n/a	class TextFile:
11	n/a	"""Provides a file-like object that takes care of all the things you
12	n/a	commonly want to do when processing a text file that has some
13	n/a	line-by-line syntax: strip comments (as long as "#" is your
14	n/a	comment character), skip blank lines, join adjacent lines by
15	n/a	escaping the newline (ie. backslash at end of line), strip
16	n/a	leading and/or trailing whitespace. All of these are optional
17	n/a	and independently controllable.
18	n/a
19	n/a	Provides a 'warn()' method so you can generate warning messages that
20	n/a	report physical line number, even if the logical line in question
21	n/a	spans multiple physical lines. Also provides 'unreadline()' for
22	n/a	implementing line-at-a-time lookahead.
23	n/a
24	n/a	Constructor is called as:
25	n/a
26	n/a	TextFile (filename=None, file=None, **options)
27	n/a
28	n/a	It bombs (RuntimeError) if both 'filename' and 'file' are None;
29	n/a	'filename' should be a string, and 'file' a file object (or
30	n/a	something that provides 'readline()' and 'close()' methods). It is
31	n/a	recommended that you supply at least 'filename', so that TextFile
32	n/a	can include it in warning messages. If 'file' is not supplied,
33	n/a	TextFile creates its own using 'io.open()'.
34	n/a
35	n/a	The options are all boolean, and affect the value returned by
36	n/a	'readline()':
37	n/a	strip_comments [default: true]
38	n/a	strip from "#" to end-of-line, as well as any whitespace
39	n/a	leading up to the "#" -- unless it is escaped by a backslash
40	n/a	lstrip_ws [default: false]
41	n/a	strip leading whitespace from each line before returning it
42	n/a	rstrip_ws [default: true]
43	n/a	strip trailing whitespace (including line terminator!) from
44	n/a	each line before returning it
45	n/a	skip_blanks [default: true}
46	n/a	skip lines that are empty after stripping comments and
47	n/a	whitespace. (If both lstrip_ws and rstrip_ws are false,
48	n/a	then some lines may consist of solely whitespace: these will
49	n/a	not be skipped, even if 'skip_blanks' is true.)
50	n/a	join_lines [default: false]
51	n/a	if a backslash is the last non-newline character on a line
52	n/a	after stripping comments and whitespace, join the following line
53	n/a	to it to form one "logical line"; if N consecutive lines end
54	n/a	with a backslash, then N+1 physical lines will be joined to
55	n/a	form one logical line.
56	n/a	collapse_join [default: false]
57	n/a	strip leading whitespace from lines that are joined to their
58	n/a	predecessor; only matters if (join_lines and not lstrip_ws)
59	n/a	errors [default: 'strict']
60	n/a	error handler used to decode the file content
61	n/a
62	n/a	Note that since 'rstrip_ws' can strip the trailing newline, the
63	n/a	semantics of 'readline()' must differ from those of the builtin file
64	n/a	object's 'readline()' method! In particular, 'readline()' returns
65	n/a	None for end-of-file: an empty string might just be a blank line (or
66	n/a	an all-whitespace line), if 'rstrip_ws' is true but 'skip_blanks' is
67	n/a	not."""
68	n/a
69	n/a	default_options = { 'strip_comments': 1,
70	n/a	'skip_blanks': 1,
71	n/a	'lstrip_ws': 0,
72	n/a	'rstrip_ws': 1,
73	n/a	'join_lines': 0,
74	n/a	'collapse_join': 0,
75	n/a	'errors': 'strict',
76	n/a	}
77	n/a
78	n/a	def __init__(self, filename=None, file=None, **options):
79	n/a	"""Construct a new TextFile object. At least one of 'filename'
80	n/a	(a string) and 'file' (a file-like object) must be supplied.
81	n/a	They keyword argument options are described above and affect
82	n/a	the values returned by 'readline()'."""
83	n/a	if filename is None and file is None:
84	n/a	raise RuntimeError("you must supply either or both of 'filename' and 'file'")
85	n/a
86	n/a	# set values for all options -- either from client option hash
87	n/a	# or fallback to default_options
88	n/a	for opt in self.default_options.keys():
89	n/a	if opt in options:
90	n/a	setattr(self, opt, options[opt])
91	n/a	else:
92	n/a	setattr(self, opt, self.default_options[opt])
93	n/a
94	n/a	# sanity check client option hash
95	n/a	for opt in options.keys():
96	n/a	if opt not in self.default_options:
97	n/a	raise KeyError("invalid TextFile option '%s'" % opt)
98	n/a
99	n/a	if file is None:
100	n/a	self.open(filename)
101	n/a	else:
102	n/a	self.filename = filename
103	n/a	self.file = file
104	n/a	self.current_line = 0 # assuming that file is at BOF!
105	n/a
106	n/a	# 'linebuf' is a stack of lines that will be emptied before we
107	n/a	# actually read from the file; it's only populated by an
108	n/a	# 'unreadline()' operation
109	n/a	self.linebuf = []
110	n/a
111	n/a	def open(self, filename):
112	n/a	"""Open a new file named 'filename'. This overrides both the
113	n/a	'filename' and 'file' arguments to the constructor."""
114	n/a	self.filename = filename
115	n/a	self.file = io.open(self.filename, 'r', errors=self.errors)
116	n/a	self.current_line = 0
117	n/a
118	n/a	def close(self):
119	n/a	"""Close the current file and forget everything we know about it
120	n/a	(filename, current line number)."""
121	n/a	file = self.file
122	n/a	self.file = None
123	n/a	self.filename = None
124	n/a	self.current_line = None
125	n/a	file.close()
126	n/a
127	n/a	def gen_error(self, msg, line=None):
128	n/a	outmsg = []
129	n/a	if line is None:
130	n/a	line = self.current_line
131	n/a	outmsg.append(self.filename + ", ")
132	n/a	if isinstance(line, (list, tuple)):
133	n/a	outmsg.append("lines %d-%d: " % tuple(line))
134	n/a	else:
135	n/a	outmsg.append("line %d: " % line)
136	n/a	outmsg.append(str(msg))
137	n/a	return "".join(outmsg)
138	n/a
139	n/a	def error(self, msg, line=None):
140	n/a	raise ValueError("error: " + self.gen_error(msg, line))
141	n/a
142	n/a	def warn(self, msg, line=None):
143	n/a	"""Print (to stderr) a warning message tied to the current logical
144	n/a	line in the current file. If the current logical line in the
145	n/a	file spans multiple physical lines, the warning refers to the
146	n/a	whole range, eg. "lines 3-5". If 'line' supplied, it overrides
147	n/a	the current line number; it may be a list or tuple to indicate a
148	n/a	range of physical lines, or an integer for a single physical
149	n/a	line."""
150	n/a	sys.stderr.write("warning: " + self.gen_error(msg, line) + "\n")
151	n/a
152	n/a	def readline(self):
153	n/a	"""Read and return a single logical line from the current file (or
154	n/a	from an internal buffer if lines have previously been "unread"
155	n/a	with 'unreadline()'). If the 'join_lines' option is true, this
156	n/a	may involve reading multiple physical lines concatenated into a
157	n/a	single string. Updates the current line number, so calling
158	n/a	'warn()' after 'readline()' emits a warning about the physical
159	n/a	line(s) just read. Returns None on end-of-file, since the empty
160	n/a	string can occur if 'rstrip_ws' is true but 'strip_blanks' is
161	n/a	not."""
162	n/a	# If any "unread" lines waiting in 'linebuf', return the top
163	n/a	# one. (We don't actually buffer read-ahead data -- lines only
164	n/a	# get put in 'linebuf' if the client explicitly does an
165	n/a	# 'unreadline()'.
166	n/a	if self.linebuf:
167	n/a	line = self.linebuf[-1]
168	n/a	del self.linebuf[-1]
169	n/a	return line
170	n/a
171	n/a	buildup_line = ''
172	n/a
173	n/a	while True:
174	n/a	# read the line, make it None if EOF
175	n/a	line = self.file.readline()
176	n/a	if line == '':
177	n/a	line = None
178	n/a
179	n/a	if self.strip_comments and line:
180	n/a
181	n/a	# Look for the first "#" in the line. If none, never
182	n/a	# mind. If we find one and it's the first character, or
183	n/a	# is not preceded by "\", then it starts a comment --
184	n/a	# strip the comment, strip whitespace before it, and
185	n/a	# carry on. Otherwise, it's just an escaped "#", so
186	n/a	# unescape it (and any other escaped "#"'s that might be
187	n/a	# lurking in there) and otherwise leave the line alone.
188	n/a
189	n/a	pos = line.find("#")
190	n/a	if pos == -1: # no "#" -- no comments
191	n/a	pass
192	n/a
193	n/a	# It's definitely a comment -- either "#" is the first
194	n/a	# character, or it's elsewhere and unescaped.
195	n/a	elif pos == 0 or line[pos-1] != "\\":
196	n/a	# Have to preserve the trailing newline, because it's
197	n/a	# the job of a later step (rstrip_ws) to remove it --
198	n/a	# and if rstrip_ws is false, we'd better preserve it!
199	n/a	# (NB. this means that if the final line is all comment
200	n/a	# and has no trailing newline, we will think that it's
201	n/a	# EOF; I think that's OK.)
202	n/a	eol = (line[-1] == '\n') and '\n' or ''
203	n/a	line = line[0:pos] + eol
204	n/a
205	n/a	# If all that's left is whitespace, then skip line
206	n/a	# now, before we try to join it to 'buildup_line' --
207	n/a	# that way constructs like
208	n/a	# hello \\
209	n/a	# # comment that should be ignored
210	n/a	# there
211	n/a	# result in "hello there".
212	n/a	if line.strip() == "":
213	n/a	continue
214	n/a	else: # it's an escaped "#"
215	n/a	line = line.replace("\\#", "#")
216	n/a
217	n/a	# did previous line end with a backslash? then accumulate
218	n/a	if self.join_lines and buildup_line:
219	n/a	# oops: end of file
220	n/a	if line is None:
221	n/a	self.warn("continuation line immediately precedes "
222	n/a	"end-of-file")
223	n/a	return buildup_line
224	n/a
225	n/a	if self.collapse_join:
226	n/a	line = line.lstrip()
227	n/a	line = buildup_line + line
228	n/a
229	n/a	# careful: pay attention to line number when incrementing it
230	n/a	if isinstance(self.current_line, list):
231	n/a	self.current_line[1] = self.current_line[1] + 1
232	n/a	else:
233	n/a	self.current_line = [self.current_line,
234	n/a	self.current_line + 1]
235	n/a	# just an ordinary line, read it as usual
236	n/a	else:
237	n/a	if line is None: # eof
238	n/a	return None
239	n/a
240	n/a	# still have to be careful about incrementing the line number!
241	n/a	if isinstance(self.current_line, list):
242	n/a	self.current_line = self.current_line[1] + 1
243	n/a	else:
244	n/a	self.current_line = self.current_line + 1
245	n/a
246	n/a	# strip whitespace however the client wants (leading and
247	n/a	# trailing, or one or the other, or neither)
248	n/a	if self.lstrip_ws and self.rstrip_ws:
249	n/a	line = line.strip()
250	n/a	elif self.lstrip_ws:
251	n/a	line = line.lstrip()
252	n/a	elif self.rstrip_ws:
253	n/a	line = line.rstrip()
254	n/a
255	n/a	# blank line (whether we rstrip'ed or not)? skip to next line
256	n/a	# if appropriate
257	n/a	if (line == '' or line == '\n') and self.skip_blanks:
258	n/a	continue
259	n/a
260	n/a	if self.join_lines:
261	n/a	if line[-1] == '\\':
262	n/a	buildup_line = line[:-1]
263	n/a	continue
264	n/a
265	n/a	if line[-2:] == '\\\n':
266	n/a	buildup_line = line[0:-2] + '\n'
267	n/a	continue
268	n/a
269	n/a	# well, I guess there's some actual content there: return it
270	n/a	return line
271	n/a
272	n/a	def readlines(self):
273	n/a	"""Read and return the list of all logical lines remaining in the
274	n/a	current file."""
275	n/a	lines = []
276	n/a	while True:
277	n/a	line = self.readline()
278	n/a	if line is None:
279	n/a	return lines
280	n/a	lines.append(line)
281	n/a
282	n/a	def unreadline(self, line):
283	n/a	"""Push 'line' (a string) onto an internal buffer that will be
284	n/a	checked by future 'readline()' calls. Handy for implementing
285	n/a	a parser with line-at-a-time lookahead."""
286	n/a	self.linebuf.append(line)