Add discussion of trailing backslash in raw string to tutorial

[bitdancer]

BPO	11479
Nosy	@birkenfeld, @facundobatista, @ezio-melotti, @bitdancer, @iritkatriel, @dancinglightning
PRs	bpo-11479: Added a discussion of trailing backslash in raw string to tutorial #27949
Files	tutorial-raw-string.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2011-03-13.03:10:02.668>
labels = ['easy', '3.9', '3.10', '3.11', 'type-feature', 'docs']
title = 'Add discussion of trailing backslash in raw string to tutorial'
updated_at = <Date 2021-08-25.15:52:29.825>
user = 'https://github.com/bitdancer'

bugs.python.org fields:

activity = <Date 2021-08-25.15:52:29.825>
actor = 'dancinglightning'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2011-03-13.03:10:02.668>
creator = 'r.david.murray'
dependencies = []
files = ['21097']
hgrepos = []
issue_num = 11479
keywords = ['patch', 'easy']
message_count = 9.0
messages = ['130720', '130727', '130739', '130742', '130743', '130744', '130748', '227698', '399988']
nosy_count = 11.0
nosy_names = ['georg.brandl', 'facundobatista', 'QuantumTim', 'ezio.melotti', 'v+python', 'r.david.murray', 'eli.bendersky', 'docs@python', 'gwideman', 'iritkatriel', 'dancinglightning']
pr_nums = ['27949']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue11479'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-55688: Add note about ending backslashes for raw strings #94768
• [3.10] gh-55688: Add note about ending backslashes for raw strings (GH-94768) #100570
• [3.11] gh-55688: Add note about ending backslashes for raw strings (GH-94768) #100571

[bitdancer]

Here is a proposed addition to the tutorial noting the problem with using raw strings for windows paths and how to work around it.

[elibendersky]

Would it not be better to just recommend Windows users not to put that last backslash in at all? IIUC it's only needed to later append file names to directory names, but that's better achieved with os.path.join

[gwideman]

Eli: Excellent and thoughtful point. This would indeed be exactly the place to suggest os.path.join as an alternative.

In addition, there are still occasions where one needs to form a string with trailing backslash. Two examples:

1. When writing the string specifying root directory: r'C:\ '[:-1]
2. Using python to prepare command lines to run other command line programs, where an argument may require a final backslash to explicitly specify a target directory (as opposed to a file).

[ezio-melotti]

I would rephrase:
+There is one subtle aspect to raw strings that is of special concern to Windows
+programmers: a raw string may not end in an odd number of \ characters.

to something like:
+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.

Otherwise it seems that this problem only affects raw strings on Windows.

[elibendersky]

Ezio Melotti ezio.melotti@gmail.com added the comment:

I would rephrase:
+There is one subtle aspect to raw strings that is of special concern to
Windows
+programmers: a raw string may not end in an odd number of \
characters.

to something like:
+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.

Otherwise it seems that this problem only affects raw strings on Windows.

I agree, but I'd also say something about os.path.join when mentioning
Windows paths, because the vast majority of problems that require the
trailing backslashes can be solved with it.

[ezio-melotti]

That would of course be a good addition too.

[bitdancer]

Well, the problem with both [:-1] and os.path.join is that they are inappropriate for that section of the tutorial. I considered putting the discussion later in the section so that I could use [:-1] (which hasn't been introduced at that point), but it made the flow even worse than adding the text where I did. I suppose the os.path.join could be put in if the sentence was short and cross referenced the library docs rather than going into a detailed example.

[bitdancer]

I'm on a quest to clear my 'commit ready' queue. This issue needs to go back to 'needs patch' stage...I'll leave it to someone else to rewrite my original patch based on the feedback, since it is unlikely I will get back to it any time soon. I'll commit it if someone else does the revision and moves it back to commit review, though ;)

[iritkatriel]

The patch needs to be converted into a github PR, and modified according to the feedback on this issue.