This is the first time I've really looked at the io.ascii readers, but I can see how this is an improvement.

OT, but would it make sense to update the table readers to work in a similar way, i.e. to use classes with special attributes rather than free-floating functions?

@mdboom - yeah, I can imagine it might clean things up to have some sort of IO connector class that encapsulates the read, write, identifier functions, handles aliases, suffixes and whatnot.

Ok -- obviously not urgent, but I open #962 for that idea.

This looks like a good idea.
Two thoughts to your suggestion:

• It looks messy because there are many options. However, that's only an issue of documentation: Since the guessing mechanism works so well, the 90% use case for reading should be just the plain old ascii reader. All other formats are already special cases, thus (for the purposes of table reading), they can be hidden in a special page of the documentation. For writing, many of those formats are unsuitable (no writer implemented) or at least unusual, e.g. why write in ascii:basic? All functionality is available in plain ascii as well. Again, this can be hidden in a deeper layer of the documentation. I suggest to say "Reading tries all formats automatically, these are the most common cases for writing: ascii, aastex, fixed_width, latex, noheader and see THIS link for full listing".
• I think you can remove the aliases that are only there for backwards compatibility from the documentation (but keep them in the code). Old code will most likely "just work" and new code should use the new mechanism anyway. Astropy.version << 1, so I think that's acceptable.

@hamogu - I'm not comfortable with "hiding" some readers. I find the basic reader works for me at best ~50% of the time. A lot of tables in the wild (at least, in my sub-fields) seem to be imporoperly formatted with spaces mixed with tabs or headers with spaces, or the like. In that case I usually need one of the specialized ones.

But you are right that the basic one is still most common - so I guess mainly what I'm suggesting is instead "Reading tries all formats automatically, these are the most common cases for writing: ascii, aastex, fixed_width, latex, noheader and see the table below (but on this page) for the full listing".

@taldcroft - one of the concerns I have with this is that it makes it harder to find the appropriate reader/writer class, and hence the relevant specific documentation. That's one thing that was nice about Reader and Writer accepting classes. I'm sure there's some way to have our cake and eat it too, though (e.g., use strings and still make it clear how to get the Reader classes.) Perhaps putting some version of the string-to-class table actually in the docstrings? (see #1011 for a slightly more specific version of this).

One disadvantage of this scheme is that is is harder to subclass a Reader or Writer and use it. Before, I just make a Reader and pass it with Reader = .... In the new scheme, I would have to register it and to do so I might even have to wrap it in a special IOConnector class (see comments above).
I don't know if anyone except me subclasses ascii.Reader classes, but I find myself doing that quite frequently.
This is not a show-stopper, but we should make sure to document how to register new ascii Readers.

Ah, but you didn't read the fine print. :-) By use of metaclasses, whenever you inherit from BaseReader then your new class is automatically registered and connected to the Table reader. This happens at the time your derived class is defined. The only special thing you need to do is put _format_name and _format_description as class attributes so it knows how to register it.

That addresses my concern!
+1

I wonder whether in the long term, we should have a BaseReader class that lives in astropy.table and auto-connects to the Table I/O, and then have astropy.io.ascii define a BaseASCIIReader class that inherits from BaseReader and adds anything needed by default by ASCII readers? Then the BaseReader is the base class for #962?

I would go one level further and say that there should be a BaseConnector class that sits below the Table readers and the NDData readers and future Thingy readers. Then certainly each subclass can specialize as needed, but the basic registration would be in BaseConnector.

@taldcroft - ah yes of course, the I/O infrastructure is also there for NDData

Closes #385.

@hamogu @astrofrog @eteq @mdboom

This one got stuck for a while but I think it's ready now (at least from my perspective). I did a significant rework of what was there before and now have (nominally) written the required tests and done all the doc updates. Although not strictly part of the PR to add a format arg to ascii.read/write, I ended doing a bunch of reworking the unified interface documentation since I discovered big chunks that were redundant.

Preview of docs at: http://hea-www.harvard.edu/~aldcroft/tmp/astropy-format/html/index.html

I see now there is a merge conflict again, sigh. (Third time now that I have had to rebase this branch because of conflicts).

Rebased and fixed merge conflict in io/ascii/write.rst documentation.

Looks great, thanks for working on this!

The documentation is already much improved with this, though I think we can try and do even better once we work on #962 - I think that ideally, someone using only the unified I/O shouldn't really have to go to the docstring of the e.g. Daophot class to know what arguments to pass, but we should somehow be able to centralize all this information in one place. For example, if I am a user and follow the docs for Daophot, I end up here:

http://hea-www.harvard.edu/~aldcroft/tmp/astropy-format/html/_generated/astropy.io.ascii.daophot.Daophot.html#astropy.io.ascii.daophot.Daophot

and I have no idea what options can be passed for reading (I just noticed that the read method is missing from the API). Anyway, as I mentioned, this is more something for #962.

Before this can be merged:

Failed test due to the use of {} (which doesn't work in Python 2.6) - use {0} instead. It also looks like there's a docs error:

/home/travis/build/astropy/astropy/docs/table/io.rst:16: ERROR: Unknown target name: "built-in table readers/writers".

Yes, the online docs situation needs work, but as you said that's out of scope for this PR. I did just add explicit references to the io.ascii read and write sections that provide long descriptions of every parameter, so if anyone is reading the web docs they'll have a reasonably clear idea of what's available:

http://hea-www.harvard.edu/~aldcroft/tmp/astropy-format/html/io/unified.html#ascii-formats

OK, travis is passing now.

Ok - this looks good to me! Feel free to merge (unless you want to wait for someone else to review too)

@taldcroft - this looks great. I agree with @astrofrog's comments about clearing up the online and interactive docs, but that is indeed a separate issue.

FYI, I noticed a whitespace typo in the docs that was mucking up the format of the formats table, which I fixed directly in 374883d