Documentation

The Python documentation for re.sub() states:

Empty matches for the pattern are replaced only when not adjacent to a previous empty match.

However, after some testing, I have been unable to construct a regular expression pattern that produces adjacent empty matches. This leads to the following questions:

Is it actually possible to create a regular expression pattern that results in adjacent empty matches in Python's re module?
If not, should we consider updating the documentation to avoid potential confusion among developers?

My Investigation

I've tried various patterns that might theoretically produce adjacent empty matches, such as:

import re

def find_all_matches(pattern, string):
    return [m.start() for m in re.finditer(pattern, string)]

test_string = "abcd"
patterns = [
    r'\b|\b',  # Word boundaries
    r'^|$',    # Start or end of string
    r'(?=.)|(?<=.)',  # Positive lookahead or lookbehind
    r'.*?',    # Non-greedy any character
]

for pattern in patterns:
    matches = find_all_matches(pattern, test_string)
    print(f"Pattern {pattern}: {matches}")

None of these patterns produce adjacent empty matches. The regex engine seems to always move forward after finding a match, even an empty one.

Request for Clarification

This issue sincerely requests clarification on this matter:

1. If adjacent empty matches are indeed possible as the documentation suggests, could you provide some examples that demonstrate this behavior?

2. Are there specific scenarios or edge cases where adjacent empty matches can occur?

3. If possible, could you share a minimal working example that shows how re.sub() handles adjacent empty matches differently from non-adjacent ones?

These examples would greatly help in understanding the documentation and the behavior of the re module in such cases.

Thank you for your time and attention to this matter. Any insights or examples you can provide would be greatly appreciated.

Linked PRs

• gh-122055: Clarify documentation for empty matches in RE #133169
• [3.14] gh-122055: Clarify documentation for empty matches in RE (GH-133169) #134217
• [3.13] gh-122055: Clarify documentation for empty matches in RE (GH-133169) #134218