From 44e1adb3e12105cb33fe657069005e250dda8e82 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Sat, 24 Mar 2018 20:48:39 -0500 Subject: [PATCH 1/4] bpo-32362: Fix references to non-existent multiprocessing.Connection() --- Doc/library/multiprocessing.rst | 22 +++++++++++-------- .../2018-03-24-20-31-56.bpo-32362.CeGpEt.rst | 2 ++ 2 files changed, 15 insertions(+), 9 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 8b3081cb80c972..b37a7f3042928f 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -735,8 +735,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 @@ -1021,6 +1022,9 @@ Miscellaneous Connection Objects ~~~~~~~~~~~~~~~~~~ +.. module:: multiprocessing.connection + :noindex: + Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. @@ -2269,7 +2273,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:`~multiprocessing.connection.Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra @@ -2299,7 +2303,7 @@ multiple connections at the same time. .. function:: Client(address[, family[, authkey]]) Attempt to set up a connection to the listener which is using address - *address*, returning a :class:`~multiprocessing.Connection`. + *address*, returning a :class:`~multiprocessing.connection.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 @@ -2349,8 +2353,8 @@ multiple connections at the same time. .. 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:`~multiprocessing.connection.Connection` object. + If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. .. method:: close() @@ -2386,7 +2390,7 @@ multiple connections at the same time. For both Unix and Windows, an object can appear in *object_list* if it is - * a readable :class:`~multiprocessing.Connection` object; + * a readable :class:`~multiprocessing.connection.Connection` object; * a connected and readable :class:`socket.socket` object; or * the :attr:`~multiprocessing.Process.sentinel` attribute of a :class:`~multiprocessing.Process` object. @@ -2509,8 +2513,8 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -When one uses :meth:`Connection.recv `, the -data received is automatically +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 to provide digest authentication. diff --git a/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst b/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst new file mode 100644 index 00000000000000..fc5c120e16906f --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst @@ -0,0 +1,2 @@ +Fix multiprocessing doc references to +``multiprocessing.connection.Connection``. From 0e2771289cde9a1e175b2a664c9e8803a4c5f2de Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Tue, 27 Mar 2018 06:39:06 -0500 Subject: [PATCH 2/4] Use currentmodule directive --- Doc/library/multiprocessing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index b37a7f3042928f..2390aec8d56884 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1022,8 +1022,7 @@ Miscellaneous Connection Objects ~~~~~~~~~~~~~~~~~~ -.. module:: multiprocessing.connection - :noindex: +.. 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. @@ -1163,6 +1162,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. From 53693df5b1c32f5b3881b91e65779db6e87338de Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Wed, 28 Mar 2018 07:50:09 -0500 Subject: [PATCH 3/4] Delete 2018-03-24-20-31-56.bpo-32362.CeGpEt.rst --- .../next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst diff --git a/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst b/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst deleted file mode 100644 index fc5c120e16906f..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2018-03-24-20-31-56.bpo-32362.CeGpEt.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix multiprocessing doc references to -``multiprocessing.connection.Connection``. From 9a69a019eefe0c44f5c336bc0dde40b7df136ff1 Mon Sep 17 00:00:00 2001 From: Bo Bayles Date: Wed, 28 Mar 2018 20:38:20 -0500 Subject: [PATCH 4/4] Further updates for currentmodule --- Doc/library/multiprocessing.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 2390aec8d56884..504f3a1c3c33bf 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1027,7 +1027,8 @@ Connection Objects 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 @@ -2274,7 +2275,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.Connection` objects returned by +:class:`~Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra @@ -2304,7 +2305,7 @@ multiple connections at the same time. .. function:: Client(address[, family[, authkey]]) Attempt to set up a connection to the listener which is using address - *address*, returning a :class:`~multiprocessing.connection.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 @@ -2354,7 +2355,7 @@ multiple connections at the same time. .. method:: accept() Accept a connection on the bound socket or named pipe of the listener - object and return a :class:`~multiprocessing.connection.Connection` object. + object and return a :class:`~Connection` object. If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. @@ -2514,10 +2515,10 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -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 +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 to provide digest authentication. An authentication key is a byte string which can be thought of as a