This is a top-level issue to keep track of refactoring/rethinking of the Table (and by extension NDData) I/O and to have a discussion about these things since several of them overlap.

At the moment, the Table class can be used to read/write to a number of formats, but there are several issues we need to address for 0.3:

• Refactor Table readers and writers to use classes rather than free functions (Refactor Table readers and writers to use classes rather than free functions... #962)

• Table.read and Table.write should provide useful docstrings (Table.read and Table.write should provide useful docstrings #1011). At the moment, this is one of the biggest annoyances of Table.read and Table.write for users, so I'm hoping we can somehow integrate this with the issue above (using classes) which could have some kind of docstring method that can be used to dynamically add information to the Table.read and Table.write docstrings. Similarly, we need to figure out where this should go in the docs.

• @taldcroft suggested that the overwrite option for writers should only get rid of the old file at the last minute in case an exception is raised in the writer before the writing part.

• We need to decide whether we want to make meta into a more complex object. An issue that was raised in table.write FITS writer? #591 is that currently the meta ordered dictionary cannot correctly store a FITS header, which requires support for duplicate keywords that have a certain order, e.g.:

  CTYPE1 = "RA---TAN"
  COMMENT some comment here
  CTYPE2 = "DEC--TAN"
  COMMENT another comment here
  

  and if users read this in via Table.read and write out with Table.write (using the simple reader/writer in table.write FITS writer? #591) this ordering won't be preserved. Furthermore, keyword comments are currently dropped. So the question is, should tables from FITS files have a special meta object, for example a Header instance? How would that play with other formats when writing out in those formats? More generally, should we have the option to store format-specific constructs in Table? Or should we make it so that meta is more complex and can handle e.g. the peculiarities of FITS and other formats?

  Now @iguananaut is also working on making FITS tables be Astropy Table objects by default, so then the question is, how does this fit in? Presumably the FITS tables will be a sub-class of the Table class, so should some of these format-specific issues go in there, and we just tell users that if they want round-tripping for a specific format, they can use that sub-class instead? Alternatively, Table.read could be a factory method that could return e.g. a FITSTable, etc.

  So more generally, when do users use Table, and when do they use sub-classes?

• Along these lines, we need to make it clearer to users when they should use Table, and when they should directly use e.g. io.ascii or votable for instance.

This is a bit of a brain dump, but I just wanted to start the conversation/thinking about this. For now, I'm just putting this here on GitHub since I think it's quite a technical discussion, but if we reach a point where we have fundamental disagreements, we can always take it to the list?

cc @taldcroft @mdboom @iguananaut @eteq