From 616fe433c6bcf8342ba30eb8a70b4d4493168201 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Mon, 6 Nov 2017 22:53:00 -0800 Subject: [PATCH 1/3] 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. --- Doc/library/multiprocessing.rst | 29 +++++++++-------------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 5fff93d1cd9439..bead3c0b106f6c 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,11 @@ 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 a byte string, digest authentication is used. + :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,18 +2338,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. - See :ref:`multiprocessing-auth-keys`. + If *authkey* is a byte string then it will be used as the authentication key; + otherwise it must be ``None``. If *authkey* is ``None`` then no + authentication is done. :exc:`~multiprocessing.AuthenticationError` + is raised if authentication fails. See :ref:`multiprocessing-auth-keys`. .. method:: accept() From 3f932a57ae5988dadebdd86a33e31f0e83a6dbb2 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 7 Nov 2017 08:04:17 -0800 Subject: [PATCH 2/3] reword per Antoine's suggestion --- Doc/library/multiprocessing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index bead3c0b106f6c..031cf679262c97 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -2305,7 +2305,8 @@ 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 *authkey* is a byte string, digest authentication is used. + If *authkey* is given and not None, it should be a byte string and will be + used as the secret key for an authentication challenge. :exc:`~multiprocessing.AuthenticationError` is raised if authentication fails. See :ref:`multiprocessing-auth-keys`. From ebeb919e15667da0964b79d1454cc7d4305f15ee Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 7 Nov 2017 08:06:22 -0800 Subject: [PATCH 3/3] use the same wording for Client and Listener --- Doc/library/multiprocessing.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 031cf679262c97..80a87b8590e9ef 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -2306,7 +2306,8 @@ multiple connections at the same time. *address*. (See :ref:`multiprocessing-address-formats`) If *authkey* is given and not None, it should be a byte string and will be - used as the secret key for an authentication challenge. + 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`. @@ -2339,10 +2340,11 @@ multiple connections at the same time. to the :meth:`~socket.socket.listen` method of the socket once it has been bound. - If *authkey* is a byte string then it will be used as the authentication key; - otherwise it must be ``None``. If *authkey* is ``None`` then no - authentication is done. :exc:`~multiprocessing.AuthenticationError` - is raised if authentication fails. 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`. .. method:: accept()