From 0dc388851051accf2f7405dccaeb9ec6d8fa816c Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Mon, 11 Jul 2022 21:37:51 -0700 Subject: [PATCH 1/6] Add note about ending backslashes for raw strings --- Doc/tutorial/introduction.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 33678f5a64b1f3..739db31d6a0374 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -189,6 +189,29 @@ 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. That is of special concern while dealing with Windows +paths. This is because the interpreter sees this as an escaped quote character, +and so it does not recognize it as the end of the string:: + + >>> fn = r'C:\this\will\not\work\' + File "", line 1 + fn = 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:: + + >>> fn = 'C:\\this\\will\\work\\' + +Another is to add a blank character before the quote and then remove it:: + + >>> fn = r'C:\this\will\work\ '.strip() + +It is also possible to use :func:`os.path.join` (by leaving the last parameter empty). + 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 From 81d05a153f9707e32c5db313969c0a480ec81281 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 23 Oct 2022 17:24:40 -0700 Subject: [PATCH 2/6] Be more specific with platform --- Doc/tutorial/introduction.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 739db31d6a0374..2aaaba6e8e5987 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -210,7 +210,8 @@ Another is to add a blank character before the quote and then remove it:: >>> fn = r'C:\this\will\work\ '.strip() -It is also possible to use :func:`os.path.join` (by leaving the last parameter empty). +It is also possible to use :func:`os.path.join` to append a backslash on Windows +(by leaving the last parameter empty). String literals can span multiple lines. One way is using triple-quotes: ``"""..."""`` or ``'''...'''``. End of lines are automatically From 9e3d190b134793b980865f0a7dc01bd2b2d444e7 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sat, 24 Dec 2022 22:54:55 -0800 Subject: [PATCH 3/6] Move information on raw string and backslashes from tutorial to FAQ entry --- Doc/faq/programming.rst | 31 +++++++++++++++++++++++++++++++ Doc/tutorial/introduction.rst | 25 +++---------------------- 2 files changed, 34 insertions(+), 22 deletions(-) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 5207add7783d3f..15446a0945a9f7 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1019,6 +1019,37 @@ 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 "", 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 add a blank character before the quote and then remove it:: + + >>> r'C:\this\will\work\ '.strip() + '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\\' + + Performance =========== diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 2aaaba6e8e5987..2e2c79f5688147 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -190,28 +190,9 @@ the first quote:: C:\some\name There is one subtle aspect to raw strings: a raw string may not end in an odd -number of ``\`` characters. That is of special concern while dealing with Windows -paths. This is because the interpreter sees this as an escaped quote character, -and so it does not recognize it as the end of the string:: - - >>> fn = r'C:\this\will\not\work\' - File "", line 1 - fn = 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:: - - >>> fn = 'C:\\this\\will\\work\\' - -Another is to add a blank character before the quote and then remove it:: - - >>> fn = r'C:\this\will\work\ '.strip() - -It is also possible to use :func:`os.path.join` to append a backslash on Windows -(by leaving the last parameter empty). +number of ``\`` characters; see +:ref:`the FAQ entry ` for more information +and workarounds. String literals can span multiple lines. One way is using triple-quotes: ``"""..."""`` or ``'''...'''``. End of lines are automatically From efad6341e23973e5a9503d4394e9431be008fac8 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 25 Dec 2022 14:57:42 -0800 Subject: [PATCH 4/6] Use string concatenation over strip; add note on backslashed quotes in r-string --- Doc/faq/programming.rst | 5 ++--- Doc/tutorial/introduction.rst | 9 +++++++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 15446a0945a9f7..5d7d7e17672762 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1038,12 +1038,11 @@ the backslashes:: >>> 'C:\\this\\will\\work\\' 'C:\\this\\will\\work\\' -Another is to add a blank character before the quote and then remove it:: +Another is to concatenate doubled slashes after the string:: - >>> r'C:\this\will\work\ '.strip() + >>> 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', '') diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 2e2c79f5688147..abd6fbe88ce1c0 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -189,8 +189,13 @@ 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 +Note that escaping quotes in raw strings will keep the backslash:: + + >>> r'before\'after' + "before\\'after" + +There is also one subtle aspect to raw strings: a raw string may not end in +an odd number of ``\`` characters; see :ref:`the FAQ entry ` for more information and workarounds. From b8e6594e4f5c20fcd40295871320cfaaa350a4b5 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Tue, 27 Dec 2022 20:03:42 -0800 Subject: [PATCH 5/6] Reword text and move to faq --- Doc/faq/programming.rst | 8 ++++++++ Doc/tutorial/introduction.rst | 9 ++------- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 5d7d7e17672762..725ccb1f2d0c17 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1048,6 +1048,14 @@ 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, there are no escape +sequences that affect the interpretation of the value of the raw string. +That is, the backslash remains present in the value of the raw string:: + + >>> r'backslash\'preserved' + "backslash\\'preserved" + Performance =========== diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index abd6fbe88ce1c0..cb907f07622ba0 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -189,15 +189,10 @@ the first quote:: >>> print(r'C:\some\name') # note the r before the quote C:\some\name -Note that escaping quotes in raw strings will keep the backslash:: - - >>> r'before\'after' - "before\\'after" - -There is also one subtle aspect to raw strings: a raw string may not end in +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 ` for more information -and workarounds. +and workarounds, as well as the the :ref:`language reference `. String literals can span multiple lines. One way is using triple-quotes: ``"""..."""`` or ``'''...'''``. End of lines are automatically From 3b0de27c3c7d43dfca902c461e2dec00c799459f Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Wed, 28 Dec 2022 00:18:41 -0500 Subject: [PATCH 6/6] improve wording slightly --- Doc/faq/programming.rst | 12 +++++++----- Doc/tutorial/introduction.rst | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 725ccb1f2d0c17..d7a84550037e22 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1038,7 +1038,8 @@ the backslashes:: >>> 'C:\\this\\will\\work\\' 'C:\\this\\will\\work\\' -Another is to concatenate doubled slashes after the string:: +Another is to concatenate a regular string containing an escaped backslash to the +raw string:: >>> r'C:\this\will\work' '\\' 'C:\\this\\will\\work\\' @@ -1048,14 +1049,15 @@ 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, there are no escape -sequences that affect the interpretation of the value of the raw string. -That is, the backslash remains present in the value of the raw string:: +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 `. Performance =========== diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index cb907f07622ba0..c4a593cab31ab9 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -192,7 +192,7 @@ the first quote:: 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 ` for more information -and workarounds, as well as the the :ref:`language reference `. +and workarounds. String literals can span multiple lines. One way is using triple-quotes: ``"""..."""`` or ``'''...'''``. End of lines are automatically