Skip to content

Commit 899d70c

Browse files
committed
Update guess func docs and improve/expand code comments [skip ci]
1 parent 6c3b35c commit 899d70c

1 file changed

Lines changed: 58 additions & 9 deletions

File tree

‎astropy/io/ascii/ui.py‎

Lines changed: 58 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,10 @@ def read(table, guess=None, **kwargs):
214214
except:
215215
pass
216216

217+
# Get the table from guess in ``dat`` along with an update to the
218+
# ``guess`` value. If ``guess`` comes back as False then there is just
219+
# one set of kwargs in the guess list so fall through below to the
220+
# non-guess way so that any problems result in a more useful traceback.
217221
dat, guess = _guess(table, new_kwargs, format, fast_reader_param)
218222

219223
if not guess:
@@ -238,27 +242,45 @@ def read(table, guess=None, **kwargs):
238242

239243

240244
def _guess(table, read_kwargs, format, fast_reader):
241-
"""Try to read the table using various sets of keyword args. First try the
242-
original args supplied in the read() call. Then try the standard guess
243-
keyword args. For each key/val pair specified explicitly in the read()
244-
call make sure that if there is a corresponding definition in the guess
245-
then it must have the same val. If not then skip this guess."""
245+
"""
246+
Try to read the table using various sets of keyword args. Start with the
247+
standard guess list and filter to make it unique and consistent with
248+
user-suppled read keyword args.
249+
250+
Parameters
251+
----------
252+
table : str, file-like, list
253+
Input table as a file name, file-like object, list of strings, or
254+
single newline-separated string.
255+
read_kwargs : dict
256+
Keyword arguments from user to be supplied to reader
257+
format : str
258+
Table format
259+
fast_reader : bool
260+
Whether to use the C engine, can also be a dict with options which
261+
default to ``False`` (default= ``True``)
262+
"""
246263

247264
# Keep a trace of all failed guesses kwarg
248265
failed_kwargs = []
266+
267+
# Get an ordered list of read() keyword arg dicts that will be cycled
268+
# through in order to guess the format.
249269
full_list_guess = _get_guess_kwargs_list(read_kwargs)
250270

271+
# If a fast version of the reader is available, try that before the slow version
251272
if fast_reader and format is not None and 'fast_{0}'.format(format) in \
252273
core.FAST_CLASSES:
253-
# If a fast version of the reader is available, try that before the slow version
254274
fast_kwargs = read_kwargs.copy()
255275
fast_kwargs['Reader'] = core.FAST_CLASSES['fast_{0}'.format(format)]
256276
full_list_guess = [fast_kwargs] + full_list_guess
257277
else:
258278
fast_kwargs = None
259279

260-
# Filter the full guess list based on user kwarg inputs
280+
# Filter the full guess list so that each entry is consistent with user kwarg inputs.
281+
# This also removes any duplicates from the list.
261282
filtered_guess_kwargs = []
283+
262284
for guess_kwargs in full_list_guess:
263285
guess_kwargs_ok = True # guess_kwargs are consistent with user_kwargs?
264286
for key, val in read_kwargs.items():
@@ -276,14 +298,19 @@ def _guess(table, read_kwargs, format, fast_reader):
276298
# so skip the guess entirely.
277299
continue
278300

301+
# Add the guess_kwargs to filtered list only if it is not already there.
279302
if guess_kwargs not in filtered_guess_kwargs:
280303
filtered_guess_kwargs.append(guess_kwargs)
281304

282305
# If there are not at least two formats to guess then return no table and
283-
# indicate that guessing did not occur.
306+
# indicate that guessing did not occur. In that case the non-guess read()
307+
# will occur and any problems will result in a more useful traceback.
284308
if len(filtered_guess_kwargs) <= 1:
285309
return None, False # dat, guess
286310

311+
# Now cycle through each possible reader and associated keyword arguments.
312+
# Try to read the table using those args, and if an exception occurs then
313+
# keep track of the failed guess and move on.
287314
for guess_kwargs in filtered_guess_kwargs:
288315
try:
289316
# If guessing will try all Readers then use strict req'ts on column names
@@ -298,7 +325,7 @@ def _guess(table, read_kwargs, format, fast_reader):
298325
core.OptionalTableImportError, core.ParameterError, cparser.CParserError):
299326
failed_kwargs.append(guess_kwargs)
300327
else:
301-
# failed all guesses, try the original read_kwargs without column requirements
328+
# Failed all guesses, try the original read_kwargs without column requirements
302329
try:
303330
reader = get_reader(**read_kwargs)
304331
return reader.read(table), True
@@ -327,6 +354,26 @@ def _guess(table, read_kwargs, format, fast_reader):
327354
raise core.InconsistentTableError('\n'.join(lines))
328355

329356
def _get_guess_kwargs_list(read_kwargs):
357+
"""
358+
Get the full list of reader keyword argument dicts that are the basis
359+
for the format guessing process. The returned full list will then be:
360+
361+
- Filtered to be consistent with user-supplied kwargs
362+
- Cleaned to have only unique entries
363+
- Used one by one to try reading the input table
364+
365+
Note that the order of the guess list has been tuned over years of usage.
366+
Maintainers need to be very careful about any adjustments as the
367+
reasoning may not be immediately evident in all cases.
368+
369+
This list can (and usually does) include duplicates. This is a result
370+
of the order tuning, but these duplicates get removed later.
371+
372+
Parameters
373+
----------
374+
read_kwargs : dict
375+
User-supplied read keyword args
376+
"""
330377
guess_kwargs_list = []
331378

332379
# Start with ECSV because an ECSV file will be read by Basic. This format
@@ -360,6 +407,8 @@ def _get_guess_kwargs_list(read_kwargs):
360407
dict(Reader=html.HTML)
361408
])
362409

410+
# Cycle through the basic-style readers using all combinations of delimiter
411+
# and quotechar.
363412
for Reader in (basic.CommentedHeader, fastbasic.FastBasic, basic.Basic,
364413
fastbasic.FastNoHeader, basic.NoHeader):
365414
for delimiter in ("|", ",", " ", "\s"):

0 commit comments

Comments
 (0)