bpo-31965: fix doc for multiprocessing.connection.Client and Listener (GH-4304) ...

* fix doc for multiprocessing.connection.Client

The authenticate argument does not exist on either Client or Listener:
- https://github.com/python/cpython/blob/master/Lib/multiprocessing/connection.pyGH-L483 (master)
- https://github.com/python/cpython/blob/3.6/Lib/multiprocessing/connection.pyGH-L478 (3.6)
- https://github.com/python/cpython/blob/3.5/Lib/multiprocessing/connection.pyGH-L478 (3.5)
- https://github.com/python/cpython/blob/3.4/Lib/multiprocessing/connection.pyGH-L487 (3.4)
The documentation also claimed that these functions will call `current_process().auth_key`, for which I could find no evidence in the code. I rewrote the documentation to reflect the actual behavior.

Also made some small changes to vary sentence structure.
(cherry picked from commit 1e5d54cfa031f1de9ee2d2e968e0551b6e2397b7)

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 2a52af1c8972193e2a1b537fd14093a8008d7b4c..6577ea6c6ae48263bec8a5a94814ffa34f23214f 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -2280,7 +2280,7 @@ multiple connections at the same time.
    If a welcome message is not received, then
    :exc:`~multiprocessing.AuthenticationError` is raised.
 
-.. function:: Client(address[, family[, authenticate[, authkey]]])
+.. function:: Client(address[, family[, authkey]])
 
    Attempt to set up a connection to the listener which is using address
    *address*, returning a :class:`~multiprocessing.Connection`.
@@ -2289,14 +2289,13 @@ multiple connections at the same time.
    generally be omitted since it can usually be inferred from the format of
    *address*. (See :ref:`multiprocessing-address-formats`)
 
-   If *authenticate* is ``True`` or *authkey* is a byte string then digest
-   authentication is used.  The key used for authentication will be either
-   *authkey* or ``current_process().authkey`` if *authkey* is ``None``.
-   If authentication fails then
-   :exc:`~multiprocessing.AuthenticationError` is raised.  See
-   :ref:`multiprocessing-auth-keys`.
+   If *authkey* is given and not None, it should be a byte string and will be
+   used as the secret key for an HMAC-based authentication challenge. No
+   authentication is done if *authkey* is None.
+   :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
+   See :ref:`multiprocessing-auth-keys`.
 
-.. class:: Listener([address[, family[, backlog[, authenticate[, authkey]]]]])
+.. class:: Listener([address[, family[, backlog[, authkey]]]])
 
    A wrapper for a bound socket or Windows named pipe which is 'listening' for
    connections.
@@ -2325,17 +2324,10 @@ multiple connections at the same time.
    to the :meth:`~socket.socket.listen` method of the socket once it has been
    bound.
 
-   If *authenticate* is ``True`` (``False`` by default) or *authkey* is not
-   ``None`` then digest authentication is used.
-
-   If *authkey* is a byte string then it will be used as the
-   authentication key; otherwise it must be ``None``.
-
-   If *authkey* is ``None`` and *authenticate* is ``True`` then
-   ``current_process().authkey`` is used as the authentication key.  If
-   *authkey* is ``None`` and *authenticate* is ``False`` then no
-   authentication is done.  If authentication fails then
-   :exc:`~multiprocessing.AuthenticationError` is raised.
+   If *authkey* is given and not None, it should be a byte string and will be
+   used as the secret key for an HMAC-based authentication challenge. No
+   authentication is done if *authkey* is None.
+   :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails.
    See :ref:`multiprocessing-auth-keys`.
 
    .. method:: accept()