From 3fc1cb23c2ffb2c29ab94e7bf0d305b453e1549d Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Sun, 29 Apr 2018 13:03:05 -0500 Subject: [PATCH 1/7] [2.7] bpo-32362: Fix references to non-existent multiprocessing.Connection() (GH-6223). (cherry picked from commit 9f3535c9cde8813ce631d6ebe4d790682f594828) Co-authored-by: Bo Bayles --- Doc/library/multiprocessing.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 97a7b536670ea6..192928eb218af2 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -574,8 +574,9 @@ For an example of the usage of queues for interprocess communication see .. function:: Pipe([duplex]) - Returns a pair ``(conn1, conn2)`` of :class:`Connection` objects representing - the ends of a pipe. + Returns a pair ``(conn1, conn2)`` of + :class:`~multiprocessing.connection.Connection` objects representing the + ends of a pipe. If *duplex* is ``True`` (the default) then the pipe is bidirectional. If *duplex* is ``False`` then the pipe is unidirectional: ``conn1`` can only be @@ -803,10 +804,13 @@ Miscellaneous Connection Objects ~~~~~~~~~~~~~~~~~~ +.. currentmodule:: multiprocessing.connection + Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. -Connection objects are usually created using :func:`Pipe` -- see also +Connection objects are usually created using +:func:`Pipe ` -- see also :ref:`multiprocessing-listeners-clients`. .. class:: Connection @@ -926,6 +930,8 @@ For example: Synchronization primitives ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. currentmodule:: multiprocessing + Generally synchronization primitives are not as necessary in a multiprocess program as they are in a multithreaded program. See the documentation for :mod:`threading` module. @@ -1943,7 +1949,7 @@ Listeners and Clients :synopsis: API for dealing with sockets. Usually message passing between processes is done using queues or by using -:class:`~multiprocessing.Connection` objects returned by +:class:`~Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra @@ -1972,7 +1978,7 @@ authentication* using the :mod:`hmac` module. .. function:: Client(address[, family[, authenticate[, authkey]]]) Attempt to set up a connection to the listener which is using address - *address*, returning a :class:`~multiprocessing.Connection`. + *address*, returning a :class:`~Connection`. The type of the connection is determined by *family* argument, but this can generally be omitted since it can usually be inferred from the format of @@ -2028,8 +2034,8 @@ authentication* using the :mod:`hmac` module. .. method:: accept() Accept a connection on the bound socket or named pipe of the listener - object and return a :class:`~multiprocessing.Connection` object. If - authentication is attempted and fails, then + object and return a :class:`~Connection` object. + If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. .. method:: close() @@ -2126,10 +2132,10 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -When one uses :meth:`Connection.recv `, the +When one uses :meth:`Connection.recv `, the data received is automatically -unpickled. Unfortunately unpickling data from an untrusted source is a security -risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module +unpickled. Unfortunately unpickling data from an untrusted source is a security +risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module to provide digest authentication. An authentication key is a string which can be thought of as a password: once a From 03a1b363ab49bd292e0642a835e855571fc9f53b Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Mon, 30 Apr 2018 21:40:06 -0500 Subject: [PATCH 2/7] Don't refer to multiprocessing.connection.Connection on 2.7 --- Doc/library/multiprocessing.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 192928eb218af2..54046dbad06b1e 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -574,9 +574,8 @@ For an example of the usage of queues for interprocess communication see .. function:: Pipe([duplex]) - Returns a pair ``(conn1, conn2)`` of - :class:`~multiprocessing.connection.Connection` objects representing the - ends of a pipe. + Returns a pair ``(conn1, conn2)`` of :class:`Connection` objects + representing the ends of a pipe. If *duplex* is ``True`` (the default) then the pipe is bidirectional. If *duplex* is ``False`` then the pipe is unidirectional: ``conn1`` can only be @@ -804,7 +803,7 @@ Miscellaneous Connection Objects ~~~~~~~~~~~~~~~~~~ -.. currentmodule:: multiprocessing.connection +.. currentmodule:: None Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. From efea0958b69ce412857ca8c5305b4f74f1443646 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 1 May 2018 06:19:38 -0500 Subject: [PATCH 3/7] Add noindex --- Doc/library/multiprocessing.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 38b3d7192e8091..6e1af86c5e9cd0 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -574,8 +574,8 @@ For an example of the usage of queues for interprocess communication see .. function:: Pipe([duplex]) - Returns a pair ``(conn1, conn2)`` of :class:`Connection` objects - representing the ends of a pipe. + Returns a pair ``(conn1, conn2)`` of :class:`Connection` object representing + the ends of a pipe. If *duplex* is ``True`` (the default) then the pipe is bidirectional. If *duplex* is ``False`` then the pipe is unidirectional: ``conn1`` can only be @@ -804,6 +804,7 @@ Connection Objects ~~~~~~~~~~~~~~~~~~ .. currentmodule:: None + :noindex: Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. @@ -1948,8 +1949,7 @@ Listeners and Clients :synopsis: API for dealing with sockets. Usually message passing between processes is done using queues or by using -:class:`~Connection` objects returned by -:func:`~multiprocessing.Pipe`. +:class:`Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra flexibility. It basically gives a high level message oriented API for dealing @@ -2144,10 +2144,10 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -When one uses :meth:`Connection.recv `, the +When one uses :meth:`Connection.recv`, the data received is automatically -unpickled. Unfortunately unpickling data from an untrusted source is a security -risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module +unpickled. Unfortunately unpickling data from an untrusted source is a security +risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module to provide digest authentication. An authentication key is a string which can be thought of as a password: once a From 10eeb7a74c102063b077fdf58493fef272a9c5c2 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 1 May 2018 14:41:53 -0500 Subject: [PATCH 4/7] Fix missing plural --- Doc/library/multiprocessing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 6e1af86c5e9cd0..e060b8beffd3ff 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -574,7 +574,7 @@ For an example of the usage of queues for interprocess communication see .. function:: Pipe([duplex]) - Returns a pair ``(conn1, conn2)`` of :class:`Connection` object representing + Returns a pair ``(conn1, conn2)`` of :class:`Connection` objects representing the ends of a pipe. If *duplex* is ``True`` (the default) then the pipe is bidirectional. If From 4101d5a132202949a13035daea9f430c618bc558 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 1 May 2018 14:42:58 -0500 Subject: [PATCH 5/7] Move noindex --- Doc/library/multiprocessing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index e060b8beffd3ff..c7fbe116807112 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -804,7 +804,6 @@ Connection Objects ~~~~~~~~~~~~~~~~~~ .. currentmodule:: None - :noindex: Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. @@ -814,6 +813,7 @@ Connection objects are usually created using :ref:`multiprocessing-listeners-clients`. .. class:: Connection + :noindex: .. method:: send(obj) From f709cadf8686ee72e3e18c5d8ce914cecc25af3e Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 1 May 2018 16:23:38 -0500 Subject: [PATCH 6/7] Remove extra ~ --- Doc/library/multiprocessing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index c7fbe116807112..0d93a39a9626a2 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1977,7 +1977,7 @@ authentication* using the :mod:`hmac` module. .. function:: Client(address[, family[, authenticate[, authkey]]]) Attempt to set up a connection to the listener which is using address - *address*, returning a :class:`~Connection`. + *address*, returning a :class:`Connection`. The type of the connection is determined by *family* argument, but this can generally be omitted since it can usually be inferred from the format of @@ -2033,7 +2033,7 @@ authentication* using the :mod:`hmac` module. .. method:: accept() Accept a connection on the bound socket or named pipe of the listener - object and return a :class:`~Connection` object. + object and return a :class:`Connection` object. If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. From 3a406d29ff7438ac2c6ae0cad08d52decf039209 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 1 May 2018 21:06:36 -0500 Subject: [PATCH 7/7] Remove noindex to restore links --- Doc/library/multiprocessing.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 0d93a39a9626a2..2d8660aba9c813 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -813,7 +813,6 @@ Connection objects are usually created using :ref:`multiprocessing-listeners-clients`. .. class:: Connection - :noindex: .. method:: send(obj)