API/DEPR: DataFrame/Series.replace is too complex.

[simonjayhawkins]

in #17673 (comment) @jorisvandenbossche wrote

Underlying reason is that this function of course can do way too many things at the same time (or the same things in too many different ways) ... (orthogonal to this, we could maybe also think if certain functionality could be moved into its own function).

opened this issue to discuss.

[simonjayhawkins]

the current behaviour when value is None is surprising from an end-user point of view #19998, #33298

#19998 (comment) @reidy-p wrote

These are good suggestions. I think it would be good if the method parameter is only used when explicitly called rather than by default because it's quite easy to get unexpected behaviour at present as you have shown. If it doesn't break the API substantially I would prefer if the behaviour of s.replace('a', None) is the same as s.replace({'a': None}).

[simonjayhawkins]

could the regex parameter be deprecated and use str.replace instead? DataFrames don't have a str accessor, but this is a user request see #31850

[jbrockmendel]

+1 for simplifying

[jbrockmendel]

After #33279 the follow-up removes the filter kwarg from Block.replace, which lets us simplify the implementatin of NDFrame.replace. Doesnt affect the API, but pertinent.

[jbrockmendel]

I'm leaning towards deprecating the ffill/bfill behavior with value=None (in part bc it has hidden bugs bc Series._replace_single uses .values instead of ._values).

In my first attempt at deprecating I thought we could tell the user to do obj.replace(to_replace, np.nan).ffill(), but that actually messes up in cases where obj already has NAs that we dont want to fill.

[jbrockmendel]

I propose the following, which we can do any subset of:

1. deprecate the "method" keyword in replace
2. deprecate the value=lib.no_default case (possibly excepting dict-like to_replace)
3. deprecate the regex keyword and introduce a method for that. Or maybe there is something users can do with a string accessor to avoid the need for a new method?