https://github.com/python/cpython/commit/cebce2e8d15db101435194f79be31b5d804... commit: cebce2e8d15db101435194f79be31b5d80455bb0 branch: 3.7 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: GitHub <noreply@github.com> date: 2018-04-29T12:09:34-07:00 summary: bpo-32362: Fix references to non-existent multiprocessing.Connection() (GH-6223) (cherry picked from commit 9f3535c9cde8813ce631d6ebe4d790682f594828) Co-authored-by: Bo Bayles <bbayles@gmail.com> files: M Doc/library/multiprocessing.rst diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 8b3081cb80c9..504f3a1c3c33 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,10 +1022,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 <multiprocessing.Pipe>` -- see also :ref:`multiprocessing-listeners-clients`. .. class:: Connection @@ -1159,6 +1163,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. @@ -2269,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` objects returned by +:class:`~Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra @@ -2299,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`. + *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 @@ -2349,8 +2355,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:`~Connection` object. + If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. .. method:: close() @@ -2386,7 +2392,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,10 +2515,10 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -When one uses :meth:`Connection.recv <multiprocessing.Connection.recv>`, the +When one uses :meth:`Connection.recv <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 byte string which can be thought of as a