cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update documentation of httpapi's handle_httperror method for clarity (#70991)

Browse source
This commit is contained in:
Nathaniel Case 2020-08-03 16:35:00 -04:00 committed by GitHub
parent 4f4436c124
commit a0523e5b8a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 6 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/docsite/rst/network/dev_guide/developing_plugins_network.rst
View file

@ -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 <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/httpapi>`_ included with Ansible Core.

5
lib/ansible/plugins/httpapi/__init__.py
View file

@ -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.