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

Co-authored-by: hauntsaninja <hauntsaninja@gmail.com>

diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index c396e2b081fca3fd7958e4ae975c685b97f1817d..ba42289f3466c2a2a4b62c752cc9d39d5a425467 100644 (file)
--- 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 6532a4e2cc83feaa95973259b50133b647107c9b..ebc2e9187534b45707e9f7cc5e3cbed161984db5 100644 (file)
--- 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