search

pandas-dev / pandas

Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
https://pandas.pydata.org
BSD 3-Clause "New" or "Revised" License
42.58k stars 17.57k forks source link

DEPR: pandas.io #52994

Open rhshadrach opened 1 year ago

rhshadrach commented 1 year ago

Similar to https://github.com/pandas-dev/pandas/issues/27522.

Currently we document pandas.io as:

In addition, public functions in pandas.io and pandas.tseries submodules are mentioned in the documentation.

Some submodules of pandas.io have a clear delineation of whats public vs private, e.g. pandas.io.excel where all submodules are prefixed with an underscore. Others, such as pandas.io.formats, are not.

One possible way to clean this up is to do add pandas.api.io and make various objects public by exposing them there.

Pinging people who helped introduce pandas.api.typing: cc @simonjayhawkins @Dr-Irv @mroeschke @jorisvandenbossche @topper-123 @bashtage

Dr-Irv commented 1 year ago

I think we are inconsistent on what we document from pandas.io between the user guide and reference guide. I support the idea of moving them all to a pandas.api.io package. But this should also be done by looking at the doc references and making sure that whatever is mentioned in the user guide has a corresponding reference manual page.

rhshadrach commented 1 year ago

I think we are inconsistent on what we document from pandas.io between the user guide and reference guide.

Can you provide details here? The way I read the reference guide is "anything that appears in our documentation is public, otherwise it's private".

Dr-Irv commented 1 year ago

Can you provide details here? The way I read the reference guide is "anything that appears in our documentation is public, otherwise it's private".

Here is one example. There may be more. In https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#sql-queries, we say "The pandas.io.sql module provides a collection of query wrappers ...", but pandas.io.sql is not in the reference manual.