[docs] Inadequate documentation on re.sub()

[Malik Rumi]

1. I am aware of issues 34304 and 28450. I am writing because I think those
fixes are inadequate. This is my proposed language change to
https://docs.python.org/3/library/re.html#re.sub

re.sub(pattern, repl, string, count=0, flags=0)
Return the string obtained by replacing the leftmost non-overlapping
occurrences of pattern in string by the replacement repl. If the pattern
isn’t found, string is returned unchanged. repl can be a string or a
function; if it is a string, any backslash escapes in it are processed. This
includes common re forms such as "\d". It also means the raw string prefix
"r'" will *not* work the way you might expect. ***If you want to replace %d
with literal \d, you need to repeat the backslash 4 times:

    pattern = re.sub('%d', '\\\\d+', pattern)

or use a raw string literal and repeat the backslash 2 times:

    pattern = re.sub('%d', r'\\d+', pattern)***

That is, \n is converted to a single newline character ...'*
################################################
I have always been told that '\n' was **already** a single character:
        >>> s = "How many chars in \n?"
        >>> len(s)
        20
        >>> s2 = "How many chars in n?"
        >>> len(s2)
        20
So this sentence means nothing to me.
################################################

Unknown escapes of ASCII letters are reserved for future use and treated as
errors...

###############################################
I would never in a *million* years have guessed that '\d' was an "unknown
escape". It is far too fundamental to regex for me to conceive of it that
way. Why didn't you tell us what the right way to do it is? If I had not
found  https://bugs.python.org/issue34304#msg322854 I would STILL not know
how to fix this problem. I am confident I am not the only one.


***Source of some of the new language:
https://bugs.python.org/issue34304#msg322854***

I am not able to log in to the bug tracker. I don't know why. I tried
posting about it as an issue on github, but I don't see it now. Maybe it
has to be moderated?




*“None of you has faith until he loves for his brother or his neighbor what
he loves for himself.”*
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20190822/3e2690e1/attachment-0001.html>