GH-39149: [Python] Validate max_replacements in ReplaceSubstringOptions

[Asthenia0412]

Background

Issue #39149 reports that pc.replace_substring_regex() (and related APIs) hang
indefinitely when passed a negative max_replacements value (other than -1 which
means unlimited). The root cause is that the C++ kernel decrements
max_replacements until it reaches 0, but a value like -3 becomes -4, -5, ...
forever.

The original fix attempt (PR #39264) targeted the C++ side but was closed before
merge. Adding validation on the Python side is a simpler, more defensive approach:
catch invalid input early, before it reaches the C++ layer.

Problem

ReplaceSubstringOptions.__init__ accepted any integer for max_replacements,
including values < -1. The sentinel value -1 means unlimited replacements, but
-2, -3, etc. are nonsensical and trigger an infinite loop in the C++ kernel.

Solution

Add a guard in ReplaceSubstringOptions.__init__ that raises ValueError when
max_replacements < -1. This provides immediate, clear feedback to the caller
rather than hanging.

Also update the docstring to document the valid range explicitly (must be >= -1,
where -1 and None both mean unlimited).

Testing

Added test_replace_substring_negative_max_replacements in
python/pyarrow/tests/test_compute.py that verifies:

• max_replacements=-2 and max_replacements=-3 raise ValueError
• max_replacements=-1 and omitted (None) are still accepted as unlimited
• Non-negative values (0, 5, etc.) continue to work as before

The test covers both the rejection path and the unchanged acceptance paths.

Fixes #39149

• GitHub Issue: [C++][Python] replace_substring_regex hangs indefinitely for negative max_replacements #39149

[github-actions]

Thanks for opening a pull request!

This pull request has been automatically closed because you currently have 4 open pull requests, which is more than the limit of 3.

Due to the increase in pull requests opened by AI bots, and in order to keep the review queue manageable, Apache Arrow limits contributors without repository access to at most 3 concurrently open pull requests. This helps make sure each pull request gets the attention it needs and that work in progress does not go stale.

Once one of your other open pull requests has been merged or closed, you are welcome to reopen this one.

See also:

• Contribution Guidelines - Limit on concurrent pull requests
• Contribution Guidelines - Contributing Overview