DEPR: relocate exceptions in pandas.core.common

[jreback]

move these to pandas.api.exceptions

using pandas.util.depr_module this should be straightforward

[m-charlton]

I can do this, just looking at the _DeprecateModule class and its use.

[m-charlton]

I don't think using the existing pandas.util.depr_module._DeprecatedModule
class will work in this scenario.

_DeprecatedModule is currently used to deprecate a complete module, pandas.core.dateutils,
and in this respect it performs as expected.

This scenario involves selectively deprecating individual exceptions in one module
pandas.core.common and redirecting calls of exceptions in pandas.api.exceptions
to pandas.core.common.

So when I execute the following:

from pandas.core.common import PandasError

I should get:

FutureWarning: pandas.core.common.PandasError is deprecated. Please use 
`pandas.api.exceptions.PandasError` instead. 

If I import pandas.api.exceptions.PandasError then I should not see any
FutureWarning message.

This is how I'm using _DeprecatedModule, it could of course be incorrect:

# module: pandas.api.exceptions
from pandas.util.depr_module import _DeprecatedModule

exceptions = _DeprecatedModule('pandas.core.common')

PandasError = exceptions.PandasError

When I import pandas.api.exceptions.PandasError then I get the following:

FutureWarning: pandas.core.common.PandasError is deprecated. Please use pandas.core.common.PandasError instead.
  PandasError = exceptions.PandasError

Several problems with the above:

1. The warning message should not appear when I import pandas.api.exceptions.PandasError only when I import pandas.core.common.PandasError.
2. The warning message should say Please use pandas.api.exceptions.PandasError instead. not Please use pandas.core.common.PandasError instead.

The only way I could I could see fixing (2) is by passing in the name of the module where the
exceptions are being moved, in this case that would be pandas.api.exceptions.

I'm trying to think of solution which satisfies the following criteria:

1. Not break existing code which uses exceptions from pandas.common.core
2. Issues a warning message when an attempt is made to import an exception from pandas.common.core
3. Does not issue a warning message when importing an exception from pandas.api.exceptions
4. Avoids any code duplication between pandas.common.core and pandas.api.exceptions

[jorisvandenbossche]

We had quite a long discussion in #14479 about deprecating an Exception (and the conclusion was more or less that it is not possible), but not sure if it is fully similar situation, as there it was about renaming a warning, where here it is about moving it.

[jreback]

@m-charlton you might be able to easily do this by:

a) moving the exception definition to pandas.api.exceptions
b) in pandas.core.common put a similar wrapper to what we do for the function deprecations

[m-charlton]

Had a look at the way functions are deprecated in pandas.core.common and this
approach will not work for classes, I suspect that the function already exists
at import time and there is something to decorate.

The function deprecation warnings would appear every time an attempt to invoke
one of these functions was made, as expected.

When deprecating an exception you'd want the deprecation warning to appear on
each import, not each time the exception was raised.

If warnings were added at import time:

# module: pandas.core.common 

class PandasError(Exception):
  warnings.warn('...', DeprecationWarning)
  ...

Then you'd see a warning anytime anything from the enclosing module were
imported, which is not ideal.

Using the imported referenced exception in pandas.api.exceptions

#module: pandas.api.exceptions
import pandas.core.common
...
PandasError = pandas.core.common.PandasError

Will still result in a warning message being issued, if of course
DeprecationWarning is enabled.

I don't know if there is some decorator/metaclass magic which could be used.

Short of duplicating code in pandas.api.exceptions, which I think would create
more problems than it solves, I don't see an elegant solution to this problem.

[jreback]

@m-charlton maybe was not clear here.

I want to completely move all of the exceptions to pandas.api.exceptions, THEN,

we want to have a warning message printed when someone does
from pandas.core.common import ParserError (or whatever).

This is the purpose of the _DeprecateModule; it essentially puts a proxy behind the module to intercept getattr requests in the name space, which is exactly what we want. (the method I used to deprecate the functions like is_datetime64_dtype and such in pandas.core.common is 'easier' in that we can return a proxy function to provide the warning.

THEN

internaly in pandas we will always import from pandas.api.exceptions. so no duplication of code and no warnings from our internal code, ONLY if someone externally imports it.

This is almost exactly what we did with pandas.core.datetools (which in addition to functions & names inside the module, we also deprecated the actual module itself).

[m-charlton]

My bad, that makes more sense. Will start work now.