Keep (un-deprecate) `read_table()` for API stability

[st-bender]

Problem description

read_table() got deprecated in favour of using read_csv().

Using read_csv() to read tab/space delimited files is counter-intuitive. According to the docs and the related issues, both share the same code and it is not clear why the one function should be preferred over the other, and that change may even break existing code.

In my point of view read_table() is the more general function and read_csv() is a special case. Why would you deprecate (and then remove) the more useful function? It is already annoying to use to_csv() to write space/tab delimited files. And as I can see it, it comes down to two lines of code.

Proposed solution

Keep both functions as they are (un-deprecate read_table()) or rename the function to have a more general name like read_txt() (as in numpy.genfromtxt()) or similar.

[jreback]

pls reference the issue where this was deprecated

also you might want to highlite and rebut some arguments there

[st-bender]

Thanks,
relevant issues are: #18262, #21948 and PR #21954
Tried to add some discussion there, but so far no reaction that's why I opened a new issue.

[jreback]

my point is to summarize the arguments in this issue (for and against)

[st-bender]

Hi,
Thank you for your input and setting the labels and sorry for getting back to you so late.
I am not really sure that I understood correctly, my point is that #18262 only lists a number of API functions to be deprecated, i.e. to be removed in the future, without further reasoning. In my opinion any change to the official and documented API should be justified. After all, pandas calls itself stable.

Note that I am not really opposed to keeping both functions, so the title may be a little provocative and could be adjusted.

My points pro keeping read_table():

• First of all to keep the API stable and to not break existing code.
• Keep the function with the more general name (IMHO) over the special case, i.e. read_table() to read ascii files with any delimiter/separator over read_csv() with the connotation of a fixed delimiter, the comma. Renaming that function to read_txt() may be worthwhile considering, although it contradicts the first point above.
• Two lines of additional code, please correct me if I am mistaken.

Contra (as far as I can see):

• Two lines of extra code.

[tpall]

Using read_csv() to import files with any delimiter seems confusing. Regarding naming, read_delim() (as in R readr package) is good alternative to read_table() or read_txt().

[TomAugspurger]

Keep the function with the more general name (IMHO) over the special case

Keep in mind that the stdlib provides this under the csv module. Shouldn't we be consistent with the stdlib? If you're coming from a Python backgound, wouldn't you look there first?

Two lines of extra code.

All else equal, we prefer not to keep around aliases. They tend to make the library harder to learn and use.

[st-bender]

Keep the function with the more general name (IMHO) over the special case

Keep in mind that the stdlib provides this under the csv module. Shouldn't we be consistent with the stdlib? If you're coming from a Python backgound, wouldn't you look there first?

Good point, I was actually used to numpy's genfromtxt(), so I was looking for something like that. I am not used to csv (files and module) that much. So in my case that's probably why I missed that connection.

Two lines of extra code.

All else equal, we prefer not to keep around aliases. They tend to make the library harder to learn and use.

Fair enough, and I would agree as a developer. However, you could still refer one to the other and state that they are kept for backwards compatibility. Keep in mind that any part of a stable API that is removed will break code. Not everybody may keep track of changes in the underlying libraries and modules. Imaging someone updates his or her setup at some point in the future for bugfixes and new or improved features. Then he or she notices that one or more of the packages in the setup uses that function (or any other that you are going to remove) which then breaks that package and in turn his own code. Those bugs are nasty to track down, and may lead to people not updating packages or rolling back updates.

[TomAugspurger]

This is just deprecated right now, and will be for some time, to give the community time to catch up. Pandas is still evolving rapidly enough that I'd be pleasantly surprised if `read_table` being dropped was the hardest part of upgrading between two distant versions.

…

On Wed, Mar 6, 2019 at 3:12 PM Stefan Bender ***@***.***> wrote: Keep the function with the more general name (IMHO) over the special case Keep in mind that the stdlib provides this under the csv module. Shouldn't we be consistent with the stdlib? If you're coming from a Python backgound, wouldn't you look there first? Good point, I was actually used to numpy's genfromtxt(), so I was looking for something like that. I am not used to csv (files and module) that much. So in my case that's probably why I missed that connection. Two lines of extra code. All else equal, we prefer not to keep around aliases. They tend to make the library harder to learn and use. Fair enough, and I would agree as a developer. However, you could still refer one to the other and state that they are kept for backwards compatibility. Keep in mind that any part of a *stable* API that is removed will break code. Not everybody may keep track of changes in the underlying libraries and modules. Imaging someone updates his or her setup at some point in the future for bugfixes and new or improved features. Then he or she notices that one or more of the packages in the setup uses that function (or any other that you are going to remove) which then breaks that package and in turn his own code. Those bugs are nasty to track down, and may lead to people not updating packages or rolling back updates. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#25220 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABQHInsAqlRmYxqEv8mLZ9jr11yxUBn-ks5vUC8_gaJpZM4aqRXG> .

[WillAyd]

I know we've had some discussions around read_table which is fine to keep ongoing, but I would be a HUGE -1 on this. I would be inclined to believe that the VAST majority of users use read_csv instead of read_table so doing this would be a nightmare for the sake of semantics.

Here's the top 5 search results for me for "pandas tutorial" excluding pandas own documentation (this is by no means an endorsement of any of these just sharing as reference):

1. https://www.dataquest.io/blog/pandas-python-tutorial/
2. https://www.datacamp.com/community/tutorials/pandas-tutorial-dataframe-python
3. https://data36.com/pandas-tutorial-1-basics-reading-data-files-dataframes-data-selection/
4. https://data-flair.training/blogs/pandas-tutorial/
5. https://www.learnpython.org/en/Pandas_Basics

All use read_csv, none use read_table. Again I understand the merits of cleaning up semantics here, but from a pure usage analysis and effort trade-off I would be very against doing this

[st-bender]

This is just deprecated right now, and will be for some time, to give the community time to catch up.

Isn't the whole point to remove it in the future? Unless I misunderstood the point of deprecating something. So anybody who missed the deprecation warning for whatever reason will be surprised.

Pandas is still evolving rapidly enough that I'd be pleasantly surprised if read_table being dropped was the hardest part of upgrading between two distant versions.

I understand that, but I am tempted to take that bet. I was actually not talking only about read_table() but also about all those other functions that got deprecated recently.
Apparently we have different opinions on 'Development Status :: 5 - Production/Stable'
For me it means that it's save to use and will be compatible for a long time into the future without breaking things. I am thinking about 10 to 20 years or even more.

[st-bender]

I know we've had some discussions around read_table which is fine to keep ongoing, but I would be a HUGE -1 on this. I would be inclined to believe that the VAST majority of users use read_csv instead of read_table so doing this would be a nightmare for the sake of semantics.

Here's the top 5 search results for me for "pandas tutorial" excluding pandas own documentation (this is by no means an endorsement of any of these just sharing as reference):

1. https://www.dataquest.io/blog/pandas-python-tutorial/
2. https://www.datacamp.com/community/tutorials/pandas-tutorial-dataframe-python
3. https://data36.com/pandas-tutorial-1-basics-reading-data-files-dataframes-data-selection/
4. https://data-flair.training/blogs/pandas-tutorial/
5. https://www.learnpython.org/en/Pandas_Basics

All use read_csv, none use read_table. Again I understand the merits of cleaning up semantics here, but from a pure usage analysis and effort trade-off I would be very against doing this

They use read_csv for reading .csv which is what it is designed for and named after. I am talking about reading space/tab delimited files, for which read_csv() is misnamed and not the first place I would look for (and didn't look). The title was meant to provoke discussion, otherwise you may not have stepped in. ;)
The only issue I actually have is changing the API in a backwards-incompatible way, i.e. removing an actually used function from it, which will break other people's code. Granted it may not be the vast majority but it's not negligible either. Yet on the other hand you introduce new interfaces like read_fmf() which does essentially the same, all three cases are handled by numpy's genfromtxt().

But I realize that we are fighting over two lines of code instead of fixing the almost 3000 real bugs. And I can't help you with that unless you really keep your API stable and backwards compatible.

[TomAugspurger]

Thanks for the feedback. I think we have different opinions on this, which is fine.

…

On Thu, Mar 7, 2019 at 3:41 AM Stefan Bender ***@***.***> wrote: I know we've had some discussions around read_table which is fine to keep ongoing, but I would be a HUGE -1 on this. I would be inclined to believe that the VAST majority of users use read_csv instead of read_table so doing this would be a nightmare for the sake of semantics. Here's the top 5 search results for me for "pandas tutorial" excluding pandas own documentation (this is by no means an endorsement of any of these just sharing as reference): 1. https://www.dataquest.io/blog/pandas-python-tutorial/ 2. https://www.datacamp.com/community/tutorials/pandas-tutorial-dataframe-python 3. https://data36.com/pandas-tutorial-1-basics-reading-data-files-dataframes-data-selection/ 4. https://data-flair.training/blogs/pandas-tutorial/ 5. https://www.learnpython.org/en/Pandas_Basics All use read_csv, none use read_table. Again I understand the merits of cleaning up semantics here, but from a pure usage analysis and effort trade-off I would be very against doing this They use read_csv for reading .csv which is what it is designed for and named after. I am talking about reading space/tab delimited files, for which read_csv() is misnamed and not the first place I would look for (and didn't look). The title was meant to provoke discussion, otherwise you may not have stepped in. ;) The only issue I actually have is changing the API in a backwards-incompatible way, i.e. removing an actually used function from it, which will break other people's code. Granted it may not be the vast majority but it's not negligible either. Yet on the other hand you introduce new interfaces like read_fmf() which does essentially the same, all three cases are handled by numpy's genfromtxt(). But I realize that we are fighting over two lines of code instead of fixing the almost 3000 real bugs. And I can't help you with that unless you really keep your API stable and backwards compatible. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#25220 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABQHItOvF37K6ZXbwSjbKjUTsOBpoPQ2ks5vUN7egaJpZM4aqRXG> .