feat(python): Allow mapping as syntactic sugar in str.replace_many

[henryharbeck]

Closes #17220

Functionality and implementation is most similar to Expr.replace, but avoids the issue raised in #18185

Also makes a few other minor changes in support:

• Expand docstring examples, including showcasing new behaviour
• Capitalise "Aho-Corasick"
• Address str.replace_many to take a dictionary that defines a replacement mapping.  #17220 (comment)

  .str.replace_many does not work with regular expressions. (perhaps a note could be added to the docs?)

As a heads up, this feature does now result in a different error message (but the same type) when replace_many is called with a single (non-mapping) argument.

df = pl.DataFrame({"a": ["a", "b", "c"]})
df.select(pl.col("a").str.replace_many(["b"]))
# Before: TypeError: ExprStringNameSpace.replace_many() missing 1 required positional argument: 'replace_with'
# After:  TypeError: `replace_with` argument is required if `patterns` argument is not a Mapping type

[henryharbeck]

Drive by: Returns section is not consistent with other DataFrame methods and LazyFrame.join docstring. Is also already covered by type hint.

[henryharbeck]

It is not clear what is being compared against "this version". Also updated to be a bit more explicit.

[henryharbeck]

This could alternatively be moved to py-polars/tests/unit/test_errors.py if so desired.

[henryharbeck]

Drive by: intent is clearer IMO and removes the need for two imports

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 79.84%. Comparing base (4157e92) to head (a46f63f).
Report is 83 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #18214      +/-   ##
==========================================
- Coverage   80.30%   79.84%   -0.47%     
==========================================
  Files        1498     1496       -2     
  Lines      198751   200345    +1594     
  Branches     2833     2844      +11     
==========================================
+ Hits       159598   159956     +358     
- Misses      38626    39864    +1238     
+ Partials      527      525       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[henryharbeck]

Hi @ritchie46 @alexander-beedie @MarcoGorelli
May I please request a review on this PR

Cheers