DOC: specify regex=True in str.replace

[rhshadrach]

• Ensure all linting tests pass, see here for how to run them

ref #36695

When passing a callable repl, str.replace will raise if regex is False. So it seems to me that in the future, when the default is changed, we should be ignoring the regex argument completely (and update the documentation to that effect). This is slightly magical, but I think better than having a default that raises.

If this is the correct way forward, then we don't need to warn when repl is callable.

cc @dsaxton @jorisvandenbossche

[dsaxton]

@rhshadrach If I'm understanding correctly, I think we would not want to skip this warning when a callable is passed, because that behavior will go from not raising to raising in the future. That way users who are implicitly relying on this won't be surprised when suddenly their code starts failing. It almost feels like the warning message could even be more verbose in this case.

Not sure if we'd want to update this here too, but I just noticed the docstring for this method is grammatically a bit odd:

pandas/pandas/core/strings/accessor.py

Line 1234 in 67c9385

Determines if assumes the passed-in pattern is a regular expression:

[rhshadrach]

Thanks @dsaxton - I think that would not be the case if we followed my suggested way forward in the OP (and comment in the code, but perhaps that comment is too terse). Thoughts on this approach, where we would be ignoring the regex keyword when repl is callable?

Not sure if we'd want to update this here too, but I just noticed the docstring for this method is grammatically a bit odd

I think this would be okay to address here, will do so.

[dsaxton]

I think that would not be the case if we followed my suggested way forward in the OP (and comment in the code, but perhaps that comment is too terse). Thoughts on this approach, where we would be ignoring the regex keyword when repl is callable?

Ah, I misunderstood. Personally I like the idea of being consistent in how regex is handled and breaking loudly if a callable is passed along with False for regex (either implicitly or not). I think it'd make the method easier to reason about, and forces end users to be explicit about what they want to do.

[rhshadrach]

Makes sense @dsaxton - updated this PR to only fix documentation.

[dsaxton]

Thanks @rhshadrach, looks like an improvement to me

[jreback]

yep this lgtm. thanks @rhshadrach