@@ -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
240244def _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
329356def _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