From a0523e5b8a7c183b59836ad891c2af8b6c091ebb Mon Sep 17 00:00:00 2001 From: Nathaniel Case Date: Mon, 3 Aug 2020 16:35:00 -0400 Subject: [PATCH] Update documentation of httpapi's handle_httperror method for clarity (#70991) --- .../rst/network/dev_guide/developing_plugins_network.rst | 4 +++- lib/ansible/plugins/httpapi/__init__.py | 5 +++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst b/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst index fc1ef685b17..9c68c60b486 100644 --- a/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_plugins_network.rst @@ -113,7 +113,9 @@ The ``handle_httperror(self, exception)`` method can deal with status codes retu * A value of ``true`` means that the request can be retried. This my be used to indicate a transient error, or one that has been resolved. For example, the default implementation will try to call ``login()`` when presented with a 401, and return ``true`` if successful. -* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be returned to the calling module as an exception. Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response. +* A value of ``false`` means that the plugin is unable to recover from this response. The status code will be raised as an exception to the calling module. + +* Any other value will be taken as a nonfatal response from the request. This may be useful if the server returns error messages in the body of the response. Returning the original exception is usually sufficient in this case, as HTTPError objects have the same interface as a successful response. For example httpapi plugins, see the `source code for the httpapi plugins `_ included with Ansible Core. diff --git a/lib/ansible/plugins/httpapi/__init__.py b/lib/ansible/plugins/httpapi/__init__.py index d13f641dfce..0773921fb6e 100644 --- a/lib/ansible/plugins/httpapi/__init__.py +++ b/lib/ansible/plugins/httpapi/__init__.py @@ -62,8 +62,9 @@ class HttpApiBase(AnsiblePlugin): * True if the code has been handled in a way that the request may be resent without changes. * False if the error cannot be handled or recovered from by the - plugin. This will result in the HTTPError being returned to the - caller to deal with as appropriate. + plugin. This will result in the HTTPError being raised as an + exception for the caller to deal with as appropriate (most likely + by failing). * Any other value returned is taken as a valid response from the server without making another request. In many cases, this can just be the original exception.