multiprocessing AF_PIPE name format is slightly confusing in the docs

[anntzer]

BPO	44189
Nosy	@anntzer, @eryksun

^{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 2021-05-20.12:11:12.410>
labels = ['3.8', '3.9', '3.10', '3.11', 'type-feature', 'docs']
title = 'multiprocessing AF_PIPE name format is slightly confusing in the docs'
updated_at = <Date 2021-05-20.23:19:26.845>
user = 'https://github.com/anntzer'

bugs.python.org fields:

activity = <Date 2021-05-20.23:19:26.845>
actor = 'eryksun'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-05-20.12:11:12.410>
creator = 'Antony.Lee'
dependencies = []
files = []
hgrepos = []
issue_num = 44189
keywords = []
message_count = 2.0
messages = ['394020', '394078']
nosy_count = 3.0
nosy_names = ['docs@python', 'Antony.Lee', 'eryksun']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44189'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10', 'Python 3.11']

[anntzer]

https://docs.python.org/3/library/multiprocessing.html#address-formats currently states

An 'AF_PIPE' address is a string of the form r'\.\pipe{PipeName}'. To use Client() to connect to a named pipe on a remote computer called ServerName one should use an address of the form r'\ServerName\pipe{PipeName}' instead.

which suggests that if the pipe is named "foo", the string should be r'\.\pipe{foo}' (especially given that the other substituted string, ServerName, is given in italics... but actually the correct format is r'\.\pipe\foo'.

Hence I would suggest fixing the markup to give name formats as r'\.pipe\PipeName' where PipeName, is in italics, like ServerName.

[eryksun]

There's a formatting problem in Doc/library/multiprocessing.rst due to consumption of the backslashes in multiple steps. The following keeps all of the required backslashes in the HTML output:

* An ``'AF_PIPE'`` address is a string of the form
  :samp:`r'\\\\\\.\\pipe\\\\{PipeName}'`.  To use :func:`Client` to connect to a named
  pipe on a remote computer called *ServerName* one should use an address of the
  form :samp:`r'\\\\\\\\{ServerName}\\pipe\\\\{PipeName}'` instead.

Or just use a regular literal and rely on the reader to understand that "{PipeName}" and "{ServerName}" are parameters:

* An ``'AF_PIPE'`` address is a string of the form
  ``r'\\.\pipe\{PipeName}'``.  To use :func:`Client` to connect to a named
  pipe on a remote computer called *ServerName* one should use an address of the
  form ``r'\\{ServerName}\pipe\{PipeName}'`` instead.

[slateny]

What's the reason for the double slashes (r'\\.\pipe\{PipeName}' instead of r'\.\pipe\{PipeName}')?

[cousteaulecommandant]

What's the reason for the double slashes (r'\\.\pipe\{PipeName}' instead of r'\.\pipe\{PipeName}')?

The string actually has to contain two backslashes, like \\.\pipe\myProgramPipe or \\NetworkPC123\pipe\myProgramPipe; it's not any markup syntax for the documentation, or Python's r'...' syntax, if that's what you're asking.
If you use r'\.\pipe\myProgramPipe' with a single \ you get an error saying that the filename syntax is incorrect (and then will spend a while trying to figure out what you did wrong, until you come across this bug report which explains the proper syntax).

(Fortunately, both Python's r'...' syntax and ReST's ``...`` syntax allow you to pass backslashes without needing to escape them, so the backslashes you see there are the ones that actually need to appear in the result.)

[cousteaulecommandant]

Or just use a regular literal and rely on the reader to understand that "{PipeName}" and "{ServerName}" are parameters:

Isn't it more common to use angle brackets <...> for this sort of thing when font formatting is not available, like \\<ServerName>\pipe\<PipeName>?
(If using braces for this sort of thing is a common idiom in Python documentation, then disregard this comment.)