Repository navigation
Table.read and Table.write should provide useful docstrings #1011
Description
Right now, if I do Table.read? in ipython, I get:
Definition: Table.read(cls, *args, **kwargs)
Docstring:
Read in data
The arguments passed to this method depend on the format
Which doesn't really help a user at all. Ideally, there would be at least a list of formatters (perhaps auto-generate from the registry like what is done in #961 ?) that I can then import and look at the docstrings of to figure out what the valid arguments are.
(cc @taldcroft - maybe you're already thinking about this as part of #961?)
Activity
eteq commentedon Apr 23, 2013
I just saw #962 - so if that goes through, I guess it makes more sense to link to the reader/writer classes, rather than functions, but the idea is still the same.
astrofrog commentedon Sep 29, 2015
Removing milestone since not 1.1-critical (I will pick up the work I've been doing on this next week)
bsipocz commentedon Feb 17, 2017
This bite me again today, and looking at the chain of issues and PRs, it still seems to be unsolved (latest attempt was #3090)
My current fastest solution is kind of unsustainable, going to the source code and figure out the kwargs from there.
taldcroft commentedon Mar 9, 2017
Unless someone is ready to step up and take over #3090 then we should consider a short term solution to this issue (which I have just marked as priority-high because I think it really is a big problem).
One thing we discussed which is not perfect but would work is to add a
helpkeyword arg toreadandwritewhich, ifTrue, prints a docstring for the specified format instead of performing the read or write. Then the I/O connectorregister_readerandwriterfuncs could take adocstringargument. An alternative is to pass an ordered dict of keyword/description pairs that would be auto-formatted and printed for a call withhelp=True.There may be better implementation ideas, but the basic idea is to manually have each class provide the I/O connector with appropriate docs. For
io.asciithis won't be completely trivial, but do-able.bsipocz commentedon Apr 5, 2018
This came up again here (indirectly): #7352
bsipocz commentedon Apr 5, 2018
Given that 3.1 is about performance and docs enhancements, can we have this as high priority for that release?
pllim commentedon Apr 17, 2018
I thought, oh, maybe it will be fun distraction to take a crack at this, but then looking at #962, #3090, etc. There appears to have been plenty of effort but no solution. Now I am scared... I'll think about how to solve the doc problem without touching the
io"enchilada".bsipocz commentedon Jun 18, 2019
#8255 has addressed this long standing issue, I'm closing it now.
Feel free to reopen, or to open a new follow-up one if you think more is needed.