From cbf42c95b2427eb0bdfec0cc3d0b38b0855274ea Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 12 Feb 2015 22:11:32 -0500 Subject: [PATCH 1/4] draft for documenting module returns --- files/acl.py | 8 +++++++ files/copy.py | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/files/acl.py b/files/acl.py index 9790f8c927f..3fa403cbfd6 100644 --- a/files/acl.py +++ b/files/acl.py @@ -102,6 +102,14 @@ EXAMPLES = ''' register: acl_info ''' +RETURN = ''' +acl: + description: Current acl on provided path (after changes, if any) + returned: always + type: list + sample: [ "user::rwx", "group::rwx", "other::rwx" ] +''' + def normalize_permissions(p): perms = ['-','-','-'] for char in p: diff --git a/files/copy.py b/files/copy.py index 364996f5293..bfd30d315b1 100644 --- a/files/copy.py +++ b/files/copy.py @@ -108,6 +108,68 @@ EXAMPLES = ''' - copy: src=/mine/sudoers dest=/etc/sudoers validate='visudo -cf %s' ''' +RETURN = ''' +dest: + description: destination file/path + returned: always + type: string + sample: "/path/to/file.txt" +src: + description: source file used for the copy on the target machine + returned: changed + type: string + sample: "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source" +md5sum: + description: md5 checksum of the file after running copy + returned: when supported + type: string + sample: "2a5aeecc61dc98c4d780b14b330e3282", +checksum: + description: checksum of the file after running copy + returned: always + type: string + sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827" +backup_file: + description: name of backup file created + returned: changed and if backup=yes + type: string + sample: "/path/to/file.txt.2015-02-12@22:09~" +gid: + description: group id of the file, after execution + returned: always + type: int + sample: 100 +group: + description: group of the file, after execution + returned: always + type: string + sample: "httpd" +owner: + description: owner of the file, after execution + returned: always + type: string + sample: "httpd" +uid: 100 + description: owner id of the file, after execution + returned: always + type: int + sample: 100 +mode: + description: permissions of the target, after execution + returned: always + type: string + sample: "0644" +size: + description: size of the target, after execution + returned: always + type: int + sample: 1220 +state: + description: permissions of the target, after execution + returned: always + type: string + sample: "file" +''' def split_pre_existing_dir(dirname): ''' From 13cdadcc4d213252e6f4374305c15c9838d73df5 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 19 Feb 2015 15:36:36 -0500 Subject: [PATCH 2/4] removed always for success, as data wont show on fail --- files/acl.py | 2 +- files/copy.py | 18 +++--- files/stat.py | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 183 insertions(+), 10 deletions(-) diff --git a/files/acl.py b/files/acl.py index 3fa403cbfd6..0c568ba59a5 100644 --- a/files/acl.py +++ b/files/acl.py @@ -105,7 +105,7 @@ EXAMPLES = ''' RETURN = ''' acl: description: Current acl on provided path (after changes, if any) - returned: always + returned: success type: list sample: [ "user::rwx", "group::rwx", "other::rwx" ] ''' diff --git a/files/copy.py b/files/copy.py index bfd30d315b1..7e1ea1db9c0 100644 --- a/files/copy.py +++ b/files/copy.py @@ -111,7 +111,7 @@ EXAMPLES = ''' RETURN = ''' dest: description: destination file/path - returned: always + returned: success type: string sample: "/path/to/file.txt" src: @@ -126,7 +126,7 @@ md5sum: sample: "2a5aeecc61dc98c4d780b14b330e3282", checksum: description: checksum of the file after running copy - returned: always + returned: success type: string sample: "6e642bb8dd5c2e027bf21dd923337cbb4214f827" backup_file: @@ -136,37 +136,37 @@ backup_file: sample: "/path/to/file.txt.2015-02-12@22:09~" gid: description: group id of the file, after execution - returned: always + returned: success type: int sample: 100 group: description: group of the file, after execution - returned: always + returned: success type: string sample: "httpd" owner: description: owner of the file, after execution - returned: always + returned: success type: string sample: "httpd" uid: 100 description: owner id of the file, after execution - returned: always + returned: success type: int sample: 100 mode: description: permissions of the target, after execution - returned: always + returned: success type: string sample: "0644" size: description: size of the target, after execution - returned: always + returned: success type: int sample: 1220 state: description: permissions of the target, after execution - returned: always + returned: success type: string sample: "file" ''' diff --git a/files/stat.py b/files/stat.py index 484da2136d9..a98e752ccf6 100644 --- a/files/stat.py +++ b/files/stat.py @@ -69,6 +69,179 @@ EXAMPLES = ''' - stat: path=/path/to/myhugefile get_md5=no ''' +RETURN = ''' +stat: + description: dictionary containing all the stat data + returned: success + type: dictionary + contains: + exists: + description: if the destination path actually exists or not + returned: success + type: boolean + sample: True + path: + description: The full path of the file/object to get the facts of + returned: success + type: boolean + sample: '/path/to/file' + mode: + description: Unix permissions of the file in octal + returned: success, path exists and user can read stats + type: octal + sample: 1755 + isdir: + description: Tells you if the path is a directory + returned: success, path exists and user can read stats + type: boolean + sample: False + ischr: + description: Tells you if the path is a character device + returned: success, path exists and user can read stats + type: boolean + sample: False + isblk: + description: Tells you if the path is a block device + returned: success, path exists and user can read stats + type: boolean + sample: False + isreg: + description: Tells you if the path is a regular file + returned: success, path exists and user can read stats + type: boolean + sample: True + isfifo: + description: Tells you if the path is a named pipe + returned: success, path exists and user can read stats + type: boolean + sample: False + islnk: + description: Tells you if the path is a symbolic link + returned: success, path exists and user can read stats + type: boolean + sample: False + issock: + description: Tells you if the path is a unix domain socket + returned: success, path exists and user can read stats + type: boolean + sample: False + uid: + description: Numeric id representing the file owner + returned: success, path exists and user can read stats + type: int + sample: 1003 + gid: + description: Numeric id representing the group of the owner + returned: success, path exists and user can read stats + type: int + sample: 1003 + size: + description: Size in bytes for a plain file, ammount of data for some special files + returned: success, path exists and user can read stats + type: int + sample: 203 + inode: + description: Inode number of the path + returned: success, path exists and user can read stats + type: int + sample: 12758 + dev: + description: Device the inode resides on + returned: success, path exists and user can read stats + type: int + sample: 33 + nlink: + description: Number of links to the inode (hard links) + returned: success, path exists and user can read stats + type: int + sample: 1 + atime: + description: Time of last access + returned: success, path exists and user can read stats + type: float + sample: 1424348972.575 + mtime: st.st_mtime, + description: Time of last modification + returned: success, path exists and user can read stats + type: float + sample: 1424348972.575 + ctime: + description: Time of last metadata update or creation (depends on OS) + returned: success, path exists and user can read stats + type: float + sample: 1424348972.575 + wusr: + description: Tells you if the owner has write permission + returned: success, path exists and user can read stats + type: boolean + sample: True + rusr: + description: Tells you if the owner has read permission + returned: success, path exists and user can read stats + type: boolean + sample: True + xusr: + description: Tells you if the owner has execute permission + returned: success, path exists and user can read stats + type: boolean + sample: True + wgrp: + description: Tells you if the owner's group has write permission + returned: success, path exists and user can read stats + type: boolean + sample: False + rgrp: + description: Tells you if the owner's group has read permission + returned: success, path exists and user can read stats + type: boolean + sample: True + xgrp: + description: Tells you if the owner's group has execute permission + returned: success, path exists and user can read stats + type: boolean + sample: True + woth: + description: Tells you if others have write permission + returned: success, path exists and user can read stats + type: boolean + sample: False + roth: + description: Tells you if others have read permission + returned: success, path exists and user can read stats + type: boolean + sample: True + xoth: + description: Tells you if others have execute permission + returned: success, path exists and user can read stats + type: boolean + sample: True + lnk_source: + description: Original path + returned: success, path exists and user can read stats and the path is a symbolic link + type: boolean + sample: True + md5: + description: md5 hash of the path + returned: success, path exists and user can read stats and path supports hashing and md5 is supported + type: boolean + sample: True + checksum: + description: hash of the path + returned: success, path exists and user can read stats and path supports hashing + type: boolean + sample: True + pw_name: + description: User name of owner + returned: success, path exists and user can read stats and installed python supports it + type: string + sample: httpd + gr_name: + description: + returned: success, path exists and user can read stats and installed python supports it + type: string + sample: www-data +''' + import os import sys from stat import * From 6e654f2442d8ad7fc707677d534cc012ba7c8f15 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 19 Feb 2015 16:43:20 -0500 Subject: [PATCH 3/4] fixed issues with stats return docs as per feedback --- files/stat.py | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/files/stat.py b/files/stat.py index a98e752ccf6..49d5f166d34 100644 --- a/files/stat.py +++ b/files/stat.py @@ -82,7 +82,7 @@ stat: sample: True path: description: The full path of the file/object to get the facts of - returned: success + returned: success and if path exists type: boolean sample: '/path/to/file' mode: @@ -160,7 +160,7 @@ stat: returned: success, path exists and user can read stats type: float sample: 1424348972.575 - mtime: st.st_mtime, + mtime: description: Time of last modification returned: success, path exists and user can read stats type: float @@ -215,6 +215,16 @@ stat: returned: success, path exists and user can read stats type: boolean sample: True + isuid: + description: Tells you if the invoking user's id matches the owner's id + returned: success, path exists and user can read stats + type: boolean + sample: False + isrid: + description: Tells you if the invoking user's group id matches the owner's group id + returned: success, path exists and user can read stats + type: boolean + sample: False lnk_source: description: Original path returned: success, path exists and user can read stats and the path is a symbolic link @@ -236,7 +246,7 @@ stat: type: string sample: httpd gr_name: - description: + description: Group name of owner returned: success, path exists and user can read stats and installed python supports it type: string sample: www-data From dbd8ea1e7de75eeaf8c9aaaa0f29702fd3450c99 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 20 Feb 2015 09:57:27 -0500 Subject: [PATCH 4/4] fixed typo on isgid --- files/stat.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/stat.py b/files/stat.py index 49d5f166d34..fbf2d4cb8f6 100644 --- a/files/stat.py +++ b/files/stat.py @@ -220,7 +220,7 @@ stat: returned: success, path exists and user can read stats type: boolean sample: False - isrid: + isgid: description: Tells you if the invoking user's group id matches the owner's group id returned: success, path exists and user can read stats type: boolean