[Python-checkins] bpo-31965: fix doc for multiprocessing.connection.Client and Listener (#4304)

[Antoine Pitrou]

https://github.com/python/cpython/commit/1e5d54cfa031f1de9ee2d2e968e0551b6e2397b7
commit: 1e5d54cfa031f1de9ee2d2e968e0551b6e2397b7
branch: master
author: Jelle Zijlstra <jelle.zijlstra at gmail.com>
committer: Antoine Pitrou <pitrou at free.fr>
date: 2017-11-07T17:13:02+01:00
summary:

bpo-31965: fix doc for multiprocessing.connection.Client and Listener (#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.py#L483 (master)
- https://github.com/python/cpython/blob/3.6/Lib/multiprocessing/connection.py#L478 (3.6)
- https://github.com/python/cpython/blob/3.5/Lib/multiprocessing/connection.py#L478 (3.5)
- https://github.com/python/cpython/blob/3.4/Lib/multiprocessing/connection.py#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.

files:
M Doc/library/multiprocessing.rst

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 5fff93d1cd9..80a87b8590e 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -2296,7 +2296,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`.
@@ -2305,14 +2305,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.
@@ -2341,17 +2340,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()