find: PEP8, imports, cosmetics (#24646)

- Make PEP8 compliant
- Ensure imports are specific
- Few cosmetic changes (sort lists, casing, punctuation)

lib/ansible/modules/files/find.py

@@ -23,27 +23,22 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 module: find
 author: Brian Coca (based on Ruggero Marchei's Tidy)
 version_added: "2.0"
-short_description: return a list of files based on specific criteria
+short_description: Return a list of files based on specific criteria
-requirements: []
 description:
     - Return a list of files based on specific criteria. Multiple criteria are AND'd together.
 options:
     age:
-        required: false
-        default: null
         description:
             - Select files whose age is equal to or greater than the specified time.
               Use a negative age to find files equal to or less than the specified time.
               You can choose seconds, minutes, hours, days, or weeks by specifying the
               first letter of any of those words (e.g., "1w").
     patterns:
-        required: false
         default: '*'
         description:
             - One or more (shell or regex) patterns, which type is controlled by C(use_regex) option.
@@ -51,31 +46,25 @@ options:
               least one of the patterns specified. Multiple patterns can be specified using a list.
         aliases: ['pattern']
     contains:
-        required: false
-        default: null
         description:
-            - One or more regex patterns which should be matched against the file content
+            - One or more regex patterns which should be matched against the file content.
     paths:
         required: true
-        aliases: [ "name", "path" ]
+        aliases: [ name, path ]
         description:
             - List of paths of directories to search. All paths must be fully qualified.
     file_type:
-        required: false
         description:
-            - Type of file to select
+            - Type of file to select.
-            - The 'link' and 'any' choices were added in version 2.3
+            - The 'link' and 'any' choices were added in version 2.3.
-        choices: [ "file", "directory", "link", "any" ]
+        choices: [ any, directory, file, link ]
-        default: "file"
+        default: file
     recurse:
-        required: false
+        default: 'no'
-        default: "no"
+        choices: [ 'no', 'yes' ]
-        choices: [ "yes", "no" ]
         description:
             - If target is a directory, recursively descend into the directory looking for files.
     size:
-        required: false
-        default: null
         description:
             - Select files whose size is equal to or greater than the specified size.
               Use a negative size to find files equal to or less than the specified size.
@@ -83,76 +72,70 @@ options:
               bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively.
               Size is not evaluated for directories.
     age_stamp:
-        required: false
+        default: mtime
-        default: "mtime"
+        choices: [ atime, ctime, mtime ]
-        choices: [ "atime", "mtime", "ctime" ]
         description:
-            - Choose the file property against which we compare age. Default is mtime.
+            - Choose the file property against which we compare age.
     hidden:
-        required: false
+        default: 'no'
-        default: "False"
+        choices: [ 'no', 'yes' ]
-        choices: [ True, False ]
         description:
             - Set this to true to include hidden files, otherwise they'll be ignored.
     follow:
-        required: false
+        default: 'no'
-        default: "False"
+        choices: [ 'no', 'yes' ]
-        choices: [ True, False ]
         description:
-            - Set this to true to follow symlinks in path for systems with python 2.6+
+            - Set this to true to follow symlinks in path for systems with python 2.6+.
     get_checksum:
-        required: false
+        default: 'no'
-        default: "False"
+        choices: [ 'no', 'yes' ]
-        choices: [ True, False ]
         description:
-            - Set this to true to retrieve a file's sha1 checksum
+            - Set this to true to retrieve a file's sha1 checksum.
     use_regex:
-        required: false
+        default: 'no'
-        default: "False"
+        choices: [ 'no', 'yes' ]
-        choices: [ True, False ]
         description:
-            - If false the patterns are file globs (shell) if true they are python regexes
+            - If false the patterns are file globs (shell) if true they are python regexes.
 '''
 
 
 EXAMPLES = r'''
-# Recursively find /tmp files older than 2 days
+- name: Recursively find /tmp files older than 2 days
-- find:
+  find:
-    paths: "/tmp"
+    paths: /tmp
-    age: "2d"
+    age: 2d
     recurse: yes
 
-# Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
+- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
 - find:
-    paths: "/tmp"
+    paths: /tmp
-    age: "4w"
+    age: 4w
-    size: "1m"
+    size: 1m
     recurse: yes
 
-# Recursively find /var/tmp files with last access time greater than 3600 seconds
+- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
 - find:
-    paths: "/var/tmp"
+    paths: /var/tmp
-    age: "3600"
+    age: 3600
     age_stamp: atime
     recurse: yes
 
-# find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
+- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
 - find:
-    paths: "/var/tmp"
+    paths: /var/tmp
-    patterns: "*.old,*.log.gz"
+    patterns: '*.old,*.log.gz'
-    size: "10m"
+    size: 10m
 
-# find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
+# Note that YAML double quotes require escaping backslashes but yaml single quotes do not.
-# Note that yaml double quotes require escaping backslashes but yaml single
+- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
-# quotes do not.
 - find:
-    paths: "/var/tmp"
+    paths: /var/tmp
     patterns: "^.*?\\.(?:old|log\\.gz)$"
-    size: "10m"
+    size: 10m
-    use_regex: True
+    use_regex: yes
 '''
 
-RETURN = '''
+RETURN = r'''
 files:
     description: all matches found with the specified criteria (see stat module for full output of each dictionary)
     returned: success
@@ -179,11 +162,14 @@ examined:
     sample: 34
 '''
 
+import fnmatch
 import os
+import re
 import stat
-import fnmatch
+import sys
 import time
-import re
+
+from ansible.module_utils.basic import AnsibleModule
 
 
 def pfilter(f, patterns=None, use_regex=False):
@@ -194,7 +180,7 @@ def pfilter(f, patterns=None, use_regex=False):
 
     if use_regex:
         for p in patterns:
-            r =  re.compile(p)
+            r = re.compile(p)
             if r.match(f):
                 return True
     else:
@@ -208,24 +194,26 @@ def pfilter(f, patterns=None, use_regex=False):
 
 def agefilter(st, now, age, timestamp):
     '''filter files older than age'''
-    if age is None or \
+    if age is None:
-      (age >= 0 and now - st.__getattribute__("st_%s" % timestamp) >= abs(age)) or \
+        return True
-      (age < 0 and now - st.__getattribute__("st_%s" % timestamp) <= abs(age)):
+    elif age >= 0 and now - st.__getattribute__("st_%s" % timestamp) >= abs(age):
-
+        return True
+    elif age < 0 and now - st.__getattribute__("st_%s" % timestamp) <= abs(age):
         return True
     return False
 
 
 def sizefilter(st, size):
     '''filter files greater than size'''
-    if size is None or \
+    if size is None:
-       (size >= 0 and st.st_size >= abs(size)) or \
+        return True
-       (size < 0 and st.st_size <= abs(size)):
+    elif size >= 0 and st.st_size >= abs(size):
-
+        return True
+    elif size < 0 and st.st_size <= abs(size):
         return True
-
     return False
 
+
 def contentfilter(fsname, pattern):
     '''filter files which contain the given expression'''
     if pattern is None:
@@ -235,7 +223,7 @@ def contentfilter(fsname, pattern):
         f = open(fsname)
         prog = re.compile(pattern)
         for line in f:
-            if prog.match (line):
+            if prog.match(line):
                 f.close()
                 return True
 
@@ -245,54 +233,55 @@ def contentfilter(fsname, pattern):
 
     return False
 
+
 def statinfo(st):
     return {
-        'mode'     : "%04o" % stat.S_IMODE(st.st_mode),
+        'mode': "%04o" % stat.S_IMODE(st.st_mode),
-        'isdir'    : stat.S_ISDIR(st.st_mode),
+        'isdir': stat.S_ISDIR(st.st_mode),
-        'ischr'    : stat.S_ISCHR(st.st_mode),
+        'ischr': stat.S_ISCHR(st.st_mode),
-        'isblk'    : stat.S_ISBLK(st.st_mode),
+        'isblk': stat.S_ISBLK(st.st_mode),
-        'isreg'    : stat.S_ISREG(st.st_mode),
+        'isreg': stat.S_ISREG(st.st_mode),
-        'isfifo'   : stat.S_ISFIFO(st.st_mode),
+        'isfifo': stat.S_ISFIFO(st.st_mode),
-        'islnk'    : stat.S_ISLNK(st.st_mode),
+        'islnk': stat.S_ISLNK(st.st_mode),
-        'issock'   : stat.S_ISSOCK(st.st_mode),
+        'issock': stat.S_ISSOCK(st.st_mode),
-        'uid'      : st.st_uid,
+        'uid': st.st_uid,
-        'gid'      : st.st_gid,
+        'gid': st.st_gid,
-        'size'     : st.st_size,
+        'size': st.st_size,
-        'inode'    : st.st_ino,
+        'inode': st.st_ino,
-        'dev'      : st.st_dev,
+        'dev': st.st_dev,
-        'nlink'    : st.st_nlink,
+        'nlink': st.st_nlink,
-        'atime'    : st.st_atime,
+        'atime': st.st_atime,
-        'mtime'    : st.st_mtime,
+        'mtime': st.st_mtime,
-        'ctime'    : st.st_ctime,
+        'ctime': st.st_ctime,
-        'wusr'     : bool(st.st_mode & stat.S_IWUSR),
+        'wusr': bool(st.st_mode & stat.S_IWUSR),
-        'rusr'     : bool(st.st_mode & stat.S_IRUSR),
+        'rusr': bool(st.st_mode & stat.S_IRUSR),
-        'xusr'     : bool(st.st_mode & stat.S_IXUSR),
+        'xusr': bool(st.st_mode & stat.S_IXUSR),
-        'wgrp'     : bool(st.st_mode & stat.S_IWGRP),
+        'wgrp': bool(st.st_mode & stat.S_IWGRP),
-        'rgrp'     : bool(st.st_mode & stat.S_IRGRP),
+        'rgrp': bool(st.st_mode & stat.S_IRGRP),
-        'xgrp'     : bool(st.st_mode & stat.S_IXGRP),
+        'xgrp': bool(st.st_mode & stat.S_IXGRP),
-        'woth'     : bool(st.st_mode & stat.S_IWOTH),
+        'woth': bool(st.st_mode & stat.S_IWOTH),
-        'roth'     : bool(st.st_mode & stat.S_IROTH),
+        'roth': bool(st.st_mode & stat.S_IROTH),
-        'xoth'     : bool(st.st_mode & stat.S_IXOTH),
+        'xoth': bool(st.st_mode & stat.S_IXOTH),
-        'isuid'    : bool(st.st_mode & stat.S_ISUID),
+        'isuid': bool(st.st_mode & stat.S_ISUID),
-        'isgid'    : bool(st.st_mode & stat.S_ISGID),
+        'isgid': bool(st.st_mode & stat.S_ISGID),
     }
 
 
 def main():
     module = AnsibleModule(
-        argument_spec = dict(
+        argument_spec=dict(
-            paths         = dict(required=True, aliases=['name','path'], type='list'),
+            paths=dict(type='list', required=True, aliases=['name', 'path']),
-            patterns      = dict(default=['*'], type='list', aliases=['pattern']),
+            patterns=dict(type='list', default=['*'], aliases=['pattern']),
-            contains      = dict(default=None, type='str'),
+            contains=dict(type='str'),
-            file_type     = dict(default="file", choices=['file', 'directory', 'link', 'any'], type='str'),
+            file_type=dict(type='str', default="file", choices=['any', 'directory', 'file', 'link']),
-            age           = dict(default=None, type='str'),
+            age=dict(type='str'),
-            age_stamp     = dict(default="mtime", choices=['atime','mtime','ctime'], type='str'),
+            age_stamp=dict(type='str', default="mtime", choices=['atime', 'mtime', 'ctime']),
-            size          = dict(default=None, type='str'),
+            size=dict(type='str'),
-            recurse       = dict(default='no', type='bool'),
+            recurse=dict(type='bool', default='no'),
-            hidden        = dict(default="False", type='bool'),
+            hidden=dict(type='bool', default='no'),
-            follow        = dict(default="False", type='bool'),
+            follow=dict(type='bool', default='no'),
-            get_checksum  = dict(default="False", type='bool'),
+            get_checksum=dict(type='bool', default='no'),
-            use_regex     = dict(default="False", type='bool'),
+            use_regex=dict(type='bool', default='no'),
         ),
         supports_check_mode=True,
     )
@@ -329,13 +318,11 @@ def main():
     for npath in params['paths']:
         npath = os.path.expanduser(os.path.expandvars(npath))
         if os.path.isdir(npath):
-
             ''' ignore followlinks for python version < 2.6 '''
-            for root,dirs,files in (sys.version_info < (2,6,0) and os.walk(npath)) or \
+            for root, dirs, files in (sys.version_info < (2, 6, 0) and os.walk(npath)) or os.walk(npath, followlinks=params['follow']):
-                                    os.walk( npath, followlinks=params['follow']):
                 looked = looked + len(files) + len(dirs)
                 for fsobj in (files + dirs):
-                    fsname=os.path.normpath(os.path.join(root, fsobj))
+                    fsname = os.path.normpath(os.path.join(root, fsobj))
 
                     if os.path.basename(fsname).startswith('.') and not params['hidden']:
                         continue
@@ -343,7 +330,7 @@ def main():
                     try:
                         st = os.lstat(fsname)
                     except:
-                        msg+="%s was skipped as it does not seem to be a valid file or it cannot be accessed\n" % fsname
+                        msg += "%s was skipped as it does not seem to be a valid file or it cannot be accessed\n" % fsname
                         continue
 
                     r = {'path': fsname}
@@ -376,13 +363,11 @@ def main():
                 if not params['recurse']:
                     break
         else:
-            msg+="%s was skipped as it does not seem to be a valid directory or it cannot be accessed\n" % npath
+            msg += "%s was skipped as it does not seem to be a valid directory or it cannot be accessed\n" % npath
 
     matched = len(filelist)
     module.exit_json(files=filelist, changed=False, msg=msg, matched=matched, examined=looked)
 
-# import module snippets
-from ansible.module_utils.basic import *
 
 if __name__ == '__main__':
     main()

test/sanity/pep8/legacy-files.txt

@@ -306,7 +306,6 @@ lib/ansible/modules/files/archive.py
 lib/ansible/modules/files/assemble.py
 lib/ansible/modules/files/blockinfile.py
 lib/ansible/modules/files/copy.py
-lib/ansible/modules/files/find.py
 lib/ansible/modules/files/ini_file.py
 lib/ansible/modules/files/iso_extract.py
 lib/ansible/modules/files/replace.py