@ -199,14 +199,14 @@ PERMS_RE = re.compile(r'^[rwxXstugo]*$')
# #
def get_platform ( ) : def get_platform ( ) :
'''
"""
* * Deprecated * * Use : py : func : ` platform . system ` directly .
* * Deprecated * * Use : py : func : ` platform . system ` directly .
: returns : Name of the platform the module is running on in a native string
: returns : Name of the platform the module is running on in a native string
Returns a native string that labels the platform ( " Linux " , " Solaris " , etc ) . Currently , this is
Returns a native string that labels the platform ( " Linux " , " Solaris " , etc ) . Currently , this is
the result of calling : py : func : ` platform . system ` .
the result of calling : py : func : ` platform . system ` .
'''
"""
return platform . system ( )
return platform . system ( )
# End deprecated functions # End deprecated functions
@ -231,7 +231,7 @@ def get_all_subclasses(cls):
def heuristic_log_sanitize ( data , no_log_values = None ) : def heuristic_log_sanitize ( data , no_log_values = None ) :
''' Remove strings that look like passwords from log messages '''
""" Remove strings that look like passwords from log messages """
# Currently filters:
# Currently filters:
# user:pass@foo/whatever and http://username:pass@wherever/foo
# user:pass@foo/whatever and http://username:pass@wherever/foo
# This code has false positives and consumes parts of logs that are
# This code has false positives and consumes parts of logs that are
@ -296,7 +296,7 @@ def heuristic_log_sanitize(data, no_log_values=None):
def _load_params ( ) : def _load_params ( ) :
'''
"""
This function may be needed for certain very dynamic custom modules which
This function may be needed for certain very dynamic custom modules which
want to process the parameters that are being handed the module . Since
want to process the parameters that are being handed the module . Since
@ -305,7 +305,7 @@ def _load_params():
will try not to break it gratuitously . It is certainly more future - proof
will try not to break it gratuitously . It is certainly more future - proof
to call this function and consume its outputs than to implement the logic
to call this function and consume its outputs than to implement the logic
inside it as a copy in your own code .
inside it as a copy in your own code .
'''
"""
global _ANSIBLE_ARGS
global _ANSIBLE_ARGS
if _ANSIBLE_ARGS is not None :
if _ANSIBLE_ARGS is not None :
buffer = _ANSIBLE_ARGS
buffer = _ANSIBLE_ARGS
@ -363,13 +363,13 @@ class AnsibleModule(object):
required_one_of = None , add_file_common_args = False ,
required_one_of = None , add_file_common_args = False ,
supports_check_mode = False , required_if = None , required_by = None ) :
supports_check_mode = False , required_if = None , required_by = None ) :
'''
"""
Common code for quickly building an ansible module in Python
Common code for quickly building an ansible module in Python
( although you can write modules with anything that can return JSON ) .
( although you can write modules with anything that can return JSON ) .
See : ref : ` developing_modules_general ` for a general introduction
See : ref : ` developing_modules_general ` for a general introduction
and : ref : ` developing_program_flow_modules ` for more detailed explanation .
and : ref : ` developing_program_flow_modules ` for more detailed explanation .
'''
"""
self . _name = os . path . basename ( __file__ ) # initialize name until we can parse from options
self . _name = os . path . basename ( __file__ ) # initialize name until we can parse from options
self . argument_spec = argument_spec
self . argument_spec = argument_spec
@ -516,13 +516,13 @@ class AnsibleModule(object):
self . log ( ' [DEPRECATION WARNING] %s %s ' % ( msg , version ) )
self . log ( ' [DEPRECATION WARNING] %s %s ' % ( msg , version ) )
def load_file_common_arguments ( self , params , path = None ) :
def load_file_common_arguments ( self , params , path = None ) :
'''
"""
many modules deal with files , this encapsulates common
many modules deal with files , this encapsulates common
options that the file module accepts such that it is directly
options that the file module accepts such that it is directly
available to all modules and they can share code .
available to all modules and they can share code .
Allows to overwrite the path / dest module argument by providing path .
Allows to overwrite the path / dest module argument by providing path .
'''
"""
if path is None :
if path is None :
path = params . get ( ' path ' , params . get ( ' dest ' , None ) )
path = params . get ( ' path ' , params . get ( ' dest ' , None ) )
@ -635,12 +635,12 @@ class AnsibleModule(object):
return ( uid , gid )
return ( uid , gid )
def find_mount_point ( self , path ) :
def find_mount_point ( self , path ) :
'''
"""
Takes a path and returns its mount point
Takes a path and returns its mount point
: param path : a string type with a filesystem path
: param path : a string type with a filesystem path
: returns : the path to the mount point as a text type
: returns : the path to the mount point as a text type
'''
"""
b_path = os . path . realpath ( to_bytes ( os . path . expanduser ( os . path . expandvars ( path ) ) , errors = ' surrogate_or_strict ' ) )
b_path = os . path . realpath ( to_bytes ( os . path . expanduser ( os . path . expandvars ( path ) ) , errors = ' surrogate_or_strict ' ) )
while not os . path . ismount ( b_path ) :
while not os . path . ismount ( b_path ) :
@ -1115,10 +1115,10 @@ class AnsibleModule(object):
return self . set_fs_attributes_if_different ( file_args , changed , diff , expand )
return self . set_fs_attributes_if_different ( file_args , changed , diff , expand )
def add_path_info ( self , kwargs ) :
def add_path_info ( self , kwargs ) :
'''
"""
for results that are files , supplement the info about the file
for results that are files , supplement the info about the file
in the return path with stats about the file path .
in the return path with stats about the file path .
'''
"""
path = kwargs . get ( ' path ' , kwargs . get ( ' dest ' , None ) )
path = kwargs . get ( ' path ' , kwargs . get ( ' dest ' , None ) )
if path is None :
if path is None :
@ -1155,10 +1155,10 @@ class AnsibleModule(object):
return kwargs
return kwargs
def _check_locale ( self ) :
def _check_locale ( self ) :
'''
"""
Uses the locale module to test the currently set locale
Uses the locale module to test the currently set locale
( per the LANG and LC_CTYPE environment settings )
( per the LANG and LC_CTYPE environment settings )
'''
"""
try :
try :
# setting the locale to '' uses the default locale
# setting the locale to '' uses the default locale
# as it would be returned by locale.getdefaultlocale()
# as it would be returned by locale.getdefaultlocale()
@ -1206,11 +1206,11 @@ class AnsibleModule(object):
return safe_eval ( value , locals , include_exceptions )
return safe_eval ( value , locals , include_exceptions )
def _load_params ( self ) :
def _load_params ( self ) :
'''
"""
This method is for backwards compatibility . The guts of the function
This method is for backwards compatibility . The guts of the function
were moved out in 2.1 so that custom modules could read the parameters .
were moved out in 2.1 so that custom modules could read the parameters .
'''
"""
# debug overrides to read args from file or cmdline
# debug overrides to read args from file or cmdline
self . params = _load_params ( )
self . params = _load_params ( )
@ -1297,7 +1297,7 @@ class AnsibleModule(object):
self . _log_to_syslog ( journal_msg )
self . _log_to_syslog ( journal_msg )
def _log_invocation ( self ) :
def _log_invocation ( self ) :
''' log that ansible ran the module '''
""" log that ansible ran the module """
# TODO: generalize a separate log function and make log_invocation use it
# TODO: generalize a separate log function and make log_invocation use it
# Sanitize possible password argument when logging.
# Sanitize possible password argument when logging.
log_args = dict ( )
log_args = dict ( )
@ -1350,7 +1350,7 @@ class AnsibleModule(object):
return None
return None
def get_bin_path ( self , arg , required = False , opt_dirs = None ) :
def get_bin_path ( self , arg , required = False , opt_dirs = None ) :
'''
"""
Find system executable in PATH .
Find system executable in PATH .
: param arg : The executable to find .
: param arg : The executable to find .
@ -1358,7 +1358,7 @@ class AnsibleModule(object):
: param opt_dirs : optional list of directories to search in addition to ` ` PATH ` `
: param opt_dirs : optional list of directories to search in addition to ` ` PATH ` `
: returns : if found return full path ; otherwise return original arg , unless ' warning ' then return None
: returns : if found return full path ; otherwise return original arg , unless ' warning ' then return None
: raises : Sysexit : if arg is not found and required = True ( via fail_json )
: raises : Sysexit : if arg is not found and required = True ( via fail_json )
'''
"""
bin_path = None
bin_path = None
try :
try :
@ -1370,7 +1370,7 @@ class AnsibleModule(object):
return bin_path
return bin_path
def boolean ( self , arg ) :
def boolean ( self , arg ) :
''' Convert the argument to a boolean '''
""" Convert the argument to a boolean """
if arg is None :
if arg is None :
return arg
return arg
@ -1447,14 +1447,14 @@ class AnsibleModule(object):
print ( ' \n %s ' % self . jsonify ( kwargs ) )
print ( ' \n %s ' % self . jsonify ( kwargs ) )
def exit_json ( self , * * kwargs ) :
def exit_json ( self , * * kwargs ) :
''' return from the module, without error '''
""" return from the module, without error """
self . do_cleanup_files ( )
self . do_cleanup_files ( )
self . _return_formatted ( kwargs )
self . _return_formatted ( kwargs )
sys . exit ( 0 )
sys . exit ( 0 )
def fail_json ( self , msg , * * kwargs ) :
def fail_json ( self , msg , * * kwargs ) :
''' return from the module, with an error message '''
""" return from the module, with an error message """
kwargs [ ' failed ' ] = True
kwargs [ ' failed ' ] = True
kwargs [ ' msg ' ] = msg
kwargs [ ' msg ' ] = msg
@ -1477,7 +1477,7 @@ class AnsibleModule(object):
self . fail_json ( msg = to_native ( e ) )
self . fail_json ( msg = to_native ( e ) )
def digest_from_file ( self , filename , algorithm ) :
def digest_from_file ( self , filename , algorithm ) :
''' '''
""" """
b_filename = to_bytes ( filename , errors = ' surrogate_or_strict ' )
b_filename = to_bytes ( filename , errors = ' surrogate_or_strict ' )
if not os . path . exists ( b_filename ) :
if not os . path . exists ( b_filename ) :
@ -1505,7 +1505,7 @@ class AnsibleModule(object):
return digest_method . hexdigest ( )
return digest_method . hexdigest ( )
def md5 ( self , filename ) :
def md5 ( self , filename ) :
'''
"""
Do not use this function unless you have no other choice for :
Do not use this function unless you have no other choice for :
1 ) Optional backwards compatibility
1 ) Optional backwards compatibility
@ -1514,21 +1514,21 @@ class AnsibleModule(object):
This function will not work on systems complying with FIPS - 140 - 2.
This function will not work on systems complying with FIPS - 140 - 2.
Most uses of this function can use the module . sha1 function instead .
Most uses of this function can use the module . sha1 function instead .
'''
"""
if ' md5 ' not in AVAILABLE_HASH_ALGORITHMS :
if ' md5 ' not in AVAILABLE_HASH_ALGORITHMS :
raise ValueError ( ' MD5 not available. Possibly running in FIPS mode ' )
raise ValueError ( ' MD5 not available. Possibly running in FIPS mode ' )
return self . digest_from_file ( filename , ' md5 ' )
return self . digest_from_file ( filename , ' md5 ' )
def sha1 ( self , filename ) :
def sha1 ( self , filename ) :
''' Return SHA1 hex digest of local file using digest_from_file(). '''
""" Return SHA1 hex digest of local file using digest_from_file(). """
return self . digest_from_file ( filename , ' sha1 ' )
return self . digest_from_file ( filename , ' sha1 ' )
def sha256 ( self , filename ) :
def sha256 ( self , filename ) :
''' Return SHA-256 hex digest of local file using digest_from_file(). '''
""" Return SHA-256 hex digest of local file using digest_from_file(). """
return self . digest_from_file ( filename , ' sha256 ' )
return self . digest_from_file ( filename , ' sha256 ' )
def backup_local ( self , fn ) :
def backup_local ( self , fn ) :
''' make a date-marked backup of the specified file, return True or False on success or failure '''
""" make a date-marked backup of the specified file, return True or False on success or failure """
backupdest = ' '
backupdest = ' '
if os . path . exists ( fn ) :
if os . path . exists ( fn ) :
@ -1586,9 +1586,9 @@ class AnsibleModule(object):
self . set_attributes_if_different ( dest , current_attribs , True )
self . set_attributes_if_different ( dest , current_attribs , True )
def atomic_move ( self , src , dest , unsafe_writes = False , keep_dest_attrs = True ) :
def atomic_move ( self , src , dest , unsafe_writes = False , keep_dest_attrs = True ) :
'''
"""
it uses os . rename to ensure this as it is an atomic operation , rest of the function is
it uses os . rename to ensure this as it is an atomic operation , rest of the function is
to work around limitations , corner cases and ensure selinux context is saved if possible '''
to work around limitations , corner cases and ensure selinux context is saved if possible """
context = None
context = None
dest_stat = None
dest_stat = None
b_src = to_bytes ( src , errors = ' surrogate_or_strict ' )
b_src = to_bytes ( src , errors = ' surrogate_or_strict ' )
@ -1756,7 +1756,7 @@ class AnsibleModule(object):
def run_command ( self , args , check_rc = False , close_fds = True , executable = None , data = None , binary_data = False , path_prefix = None , cwd = None ,
def run_command ( self , args , check_rc = False , close_fds = True , executable = None , data = None , binary_data = False , path_prefix = None , cwd = None ,
use_unsafe_shell = False , prompt_regex = None , environ_update = None , umask = None , encoding = ' utf-8 ' , errors = ' surrogate_or_strict ' ,
use_unsafe_shell = False , prompt_regex = None , environ_update = None , umask = None , encoding = ' utf-8 ' , errors = ' surrogate_or_strict ' ,
expand_user_and_vars = True , pass_fds = None , before_communicate_callback = None , ignore_invalid_cwd = True , handle_exceptions = True ) :
expand_user_and_vars = True , pass_fds = None , before_communicate_callback = None , ignore_invalid_cwd = True , handle_exceptions = True ) :
'''
"""
Execute a command , returns rc , stdout , and stderr .
Execute a command , returns rc , stdout , and stderr .
The mechanism of this method for reading stdout and stderr differs from
The mechanism of this method for reading stdout and stderr differs from
@ -1825,7 +1825,7 @@ class AnsibleModule(object):
byte strings . On python3 , stdout and stderr are text strings converted
byte strings . On python3 , stdout and stderr are text strings converted
according to the encoding and errors parameters . If you want byte
according to the encoding and errors parameters . If you want byte
strings on python3 , use encoding = None to turn decoding to text off .
strings on python3 , use encoding = None to turn decoding to text off .
'''
"""
# used by clean args later on
# used by clean args later on
self . _clean = None
self . _clean = None
Matt Clay
1 month ago
committed by