DEPR: pandas/core

[jreback]

we have a documentation note that pandas.core is private but we need an actual deprecation

see discussion starting here: #27471 (comment)

[Edit by rhshadrach] Current outline (will update as this evolves):

• Prior to 2.2
  • Fix redirects due to moving doc pages from DOC: Change core paths to api.typing in URLs #55626 (ref: DOC: Change core paths to api.typing in URLs #55626 (comment)) Update: The linked PR has been reverted, no fix is needed.
• After 2.2 and prior to 3.0
  • Possibly add new locations for object in pandas.api.typing (DOC: Provide a public place for users to link to our documentation #55632)
  • Add __module__ to all pandas objects pointing to the public location (ENH: set __module__ on top-level public objects #55178)
• 1-2 weeks before 3.0 RC is released
  • Move pandas.core to pandas._core and add in stub files for backwards compatibility
• Anytime after
  • Add PendingDeprecationWarning to pandas.core
  • Change PendingDeprecationWarning to DeprecationWarning
  • Change DeprecationWarning to FutureWarning
  • Remove pandas.core

[WillAyd]

Is there anything outside of the top level pandas namespace that is public? I know we have some usages of pandas.io.json.json_normalize and IIRC something with Categorical but I wonder if we should just move them to pandas and provide a generic warning for anything not coming from pandas to end users

[jbrockmendel]

I share Will's sentiment, though from looking at the history it seems like there was an intentional move away from that before I got here.

If there is a shuffling of core files, I'd like to separate out Index/Series/DataFrame/internals from lower-level code that doesn't need to be "aware" of these classes

[jreback]

nothing should be public except pd namespace
but historically we had a lot (like everything) was

we moved everything a few years ago to create _libs and consolidate under core & io
but i think we need to be explicitly private

moving things around is much much easier after

[WillAyd]

So sounds like we need to:

1. Audit external usage of anything not in the top level (json_normalize, etc...) and make available in pandas.init.py
2. Document / throw FutureWarning when accessing other namespaces

Then actually prefix those namespaces with an underscore to privatize?

[huandzh]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

Use case: aliyun/aliyun-odps-python-sdk#99

[simonjayhawkins]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

[jreback]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

these are already mostly in pandas.exceptions which are public

[simonjayhawkins]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

these are already mostly in pandas.exceptions which are public

is this an exception (sorry for the pun) to the "nothing should be public except pd namespace" rule?

[jreback]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

these are already mostly in pandas.exceptions which are public

is this an exception (sorry for the pun) to the "nothing should be public except pd namespace" rule?

yes

[jreback]

pandas.api as well; the other top level packages should be private (though may be tricky / take a while to fully remove)

[TomAugspurger]

Since we're re-having this discussion, I'll note that if we're disciplined about making private modules private with a leading underscore, there's no need for a `.api` namespace. Everything not starting with an underscore is public. pandas.arrays pandas.exceptions pandas.extensions pandas.types ... Tom

…

On Tue, Jul 23, 2019 at 6:05 AM Jeff Reback ***@***.***> wrote: pandas.api as well; the other top level packages should be private (though may be tricky / take a while to fully remove) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#27522?email_source=notifications&email_token=AAKAOIWYVSQLPXERGTM4CYDQA3QZLA5CNFSM4IFZ7I52YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD2SYILY#issuecomment-514163759>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAKAOIUKLCDVQIM2YQCLMYTQA3QZLANCNFSM4IFZ7I5Q> .

[huandzh]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

these are already mostly in pandas.exceptions which are public

is this an exception (sorry for the pun) to the "nothing should be public except pd namespace" rule?

yes

Then, OptionError raised by pandas.set_option will be available in pandas.exceptions afterwards, and so do other custom exceptions raised by top-level functions, am i right?

Anyway, it's better to have them in one and fixed place.

[simonjayhawkins]

Hi, it will be nice to also expose exceptions raised by top level functions, since downstream may want to handle them in their own code.

this may warrant a separate issue for discussion. @jorisvandenbossche what's you current feeling regarding custom exceptions exposed to users? #25569 (comment)

these are already mostly in pandas.exceptions which are public

is this an exception (sorry for the pun) to the "nothing should be public except pd namespace" rule?

yes

Then, OptionError raised by pandas.set_option will be available in pandas.exceptions afterwards, and so do other custom exceptions raised by top-level functions, am i right?

Anyway, it's better to have them in one and fixed place.

it looks like this was added in #19790 and intended to be user facing. so it probably should be in the public api. can you raise an issue for this.