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

16888: comment module_utils/urls.py (#16987)

Browse source 
* 16888: comment module_utils/urls.py

* improved documentation of module (mentioning ‘requests’)

* remove mentioning of implementation details (urllib)

* improved parameter and return value documentation
This commit is contained in:
Victor Volle 2016-08-10 17:39:48 +02:00 committed by Toshio Kuratomi
parent 57fca2dde2
commit c9d2a67ec7
1 changed files with 56 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
lib/ansible/module_utils/urls.py
View file

@ -81,6 +81,21 @@
# agrees to be bound by the terms and conditions of this License # agrees to be bound by the terms and conditions of this License
# Agreement. # Agreement.
'''
The **urls** utils module offers a replacement for the urllib2 python library.
urllib2 is the python stdlib way to retrieve files from the Internet but it
lacks some security features (around verifying SSL certificates) that users
should care about in most situations. Using the functions in this module corrects
deficiencies in the urllib2 module wherever possible.
There are also third-party libraries (for instance, requests) which can be used
to replace urllib2 with a more secure library. However, all third party libraries
require that the library be installed on the managed machine. That is an extra step
for users making use of a module. If possible, avoid third party libraries by using
this code instead.
'''
import netrc import netrc
import os import os
import re import re
@ -732,7 +747,7 @@ def open_url(url, data=None, headers=None, method=None, use_proxy=True,
url_username=None, url_password=None, http_agent=None, url_username=None, url_password=None, http_agent=None,
force_basic_auth=False, follow_redirects='urllib2'): force_basic_auth=False, follow_redirects='urllib2'):
''' '''
Fetches a file from an HTTP/FTP server using urllib2 Sends a request via HTTP(S) or FTP using urllib2 (Python2) or urllib (Python3)
Does not require the module environment Does not require the module environment
''' '''
@ -884,8 +899,34 @@ def url_argument_spec():
def fetch_url(module, url, data=None, headers=None, method=None, def fetch_url(module, url, data=None, headers=None, method=None,
use_proxy=True, force=False, last_mod_time=None, timeout=10): use_proxy=True, force=False, last_mod_time=None, timeout=10):
''' '''Sends a request via HTTP(S) or FTP (needs the module as parameter)
Fetches a file from an HTTP/FTP server using urllib2. Requires the module environment
:arg module: The AnsibleModule (used to get username, password etc. (s.b.).
:arg url: The url to use.
:kwarg data: The data to be sent (in case of POST/PUT).
:kwarg headers: A dict with the request headers.
:kwarg method: "POST", "PUT", etc.
:kwarg boolean use_proxy: Default: True
:kwarg boolean force: If True: Do not get a cached copy (Default: False)
:kwarg last_mod_time: Default: None
:kwarg int timeout: Default: 10
:returns: A tuple of (**response**, **info**). Use ``response.body()`` to read the data.
The **info** contains the 'status' and other meta data. When a HttpError (status > 400)
occurred then ``info['body']`` contains the error response data::
Example::
data={...}
resp, info = fetch_url("http://example.com",
data=module.jsonify(data)
header={Content-type': 'application/json'},
method="POST")
status_code = info["status"]
body = resp.read()
if status_code >= 400 :
body = info['body']
''' '''
if not HAS_URLPARSE: if not HAS_URLPARSE: