[Python-checkins] gh-55688: Add note about ending backslashes for raw strings (GH-94768)

[miss-islington]

https://github.com/python/cpython/commit/de621281ce704546b87334fd7da7a7ec534719b7
commit: de621281ce704546b87334fd7da7a7ec534719b7
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-12-27T21:45:45-08:00
summary:

gh-55688: Add note about ending backslashes for raw strings (GH-94768)

(cherry picked from commit b95b1b3b25b0a93a22c7d58ac5bd5870e62070a8)

Co-authored-by: Stanley <46876382+slateny at users.noreply.github.com>
Co-authored-by: hauntsaninja <hauntsaninja at gmail.com>

files:
M Doc/faq/programming.rst
M Doc/tutorial/introduction.rst

diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index c396e2b081fc..ba42289f3466 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -1026,6 +1026,46 @@ What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error  mean?
 See the :ref:`unicode-howto`.
 
 
+.. _faq-programming-raw-string-backslash:
+
+Can I end a raw string with an odd number of backslashes?
+---------------------------------------------------------
+
+A raw string ending with an odd number of backslashes will escape the string's quote::
+
+   >>> r'C:\this\will\not\work\'
+     File "<stdin>", line 1
+       r'C:\this\will\not\work\'
+            ^
+   SyntaxError: unterminated string literal (detected at line 1)
+
+There are several workarounds for this. One is to use regular strings and double
+the backslashes::
+
+   >>> 'C:\\this\\will\\work\\'
+   'C:\\this\\will\\work\\'
+
+Another is to concatenate a regular string containing an escaped backslash to the
+raw string::
+
+   >>> r'C:\this\will\work' '\\'
+   'C:\\this\\will\\work\\'
+
+It is also possible to use :func:`os.path.join` to append a backslash on Windows::
+
+   >>> os.path.join(r'C:\this\will\work', '')
+   'C:\\this\\will\\work\\'
+
+Note that while a backslash will "escape" a quote for the purposes of
+determining where the raw string ends, no escaping occurs when interpreting the
+value of the raw string. That is, the backslash remains present in the value of
+the raw string::
+
+   >>> r'backslash\'preserved'
+   "backslash\\'preserved"
+
+Also see the specification in the :ref:`language reference <strings>`.
+
 Performance
 ===========
 
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index 558b1c3eec60..b7a89905e4f3 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -189,6 +189,11 @@ the first quote::
    >>> print(r'C:\some\name')  # note the r before the quote
    C:\some\name
 
+There is one subtle aspect to raw strings: a raw string may not end in
+an odd number of ``\`` characters; see
+:ref:`the FAQ entry <faq-programming-raw-string-backslash>` for more information
+and workarounds.
+
 String literals can span multiple lines.  One way is using triple-quotes:
 ``"""..."""`` or ``'''...'''``.  End of lines are automatically
 included in the string, but it's possible to prevent this by adding a ``\`` at