From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 19 May 2025 13:49:29 +0000 (+0200)
Subject: [3.13] gh-122055: Clarify documentation for empty matches in RE (GH-133169) (GH-134218)
X-Git-Tag: v3.13.4~89
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=55a7cb1206b2cc6e5fa98e3bfe8fcd67b4ed2de4;p=thirdparty%2FPython%2Fcpython.git

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

(cherry picked from commit 44b73d3cd4466e148460883acf4494124eae8c91)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
---

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index a4ec538ee813..7a43723e119e 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -988,8 +988,8 @@ Functions
    That way, separator components are always found at the same relative
    indices within the result list.
 
-   Empty matches for the pattern split the string only when not adjacent
-   to a previous empty match.
+   Adjacent empty matches are not possible, but an empty match can occur
+   immediately after a non-empty match.
 
    .. code:: pycon
 
@@ -1092,9 +1092,12 @@ Functions
 
    The optional argument *count* is the maximum number of pattern occurrences to be
    replaced; *count* must be a non-negative integer.  If omitted or zero, all
-   occurrences will be replaced. Empty matches for the pattern are replaced only
-   when not adjacent to a previous empty match, so ``sub('x*', '-', 'abxd')`` returns
-   ``'-a-b--d-'``.
+   occurrences will be replaced.
+
+   Adjacent empty matches are not possible, but an empty match can occur
+   immediately after a non-empty match.
+   As a result, ``sub('x*', '-', 'abxd')`` returns ``'-a-b--d-'``
+   instead of ``'-a-b-d-'``.
 
    .. index:: single: \g; in regular expressions
 
@@ -1125,8 +1128,7 @@ Functions
    .. versionchanged:: 3.7
       Unknown escapes in *repl* consisting of ``'\'`` and an ASCII letter
       now are errors.
-      Empty matches for the pattern are replaced when adjacent to a previous
-      non-empty match.
+      An empty match can occur immediately after a non-empty match.
 
    .. versionchanged:: 3.12
       Group *id* can only contain ASCII digits.