ansible-core 2.15.4rc1__py3-none-any.whl → 2.16.0b2__py3-none-any.whl

ansible/modules/stat.py

@@ -36,7 +36,7 @@ options:
     description:
       - Algorithm to determine checksum of file.
       - Will throw an error if the host is unable to use specified algorithm.
-      - The remote host has to support the hashing method specified, C(md5)
+      - The remote host has to support the hashing method specified, V(md5)
         can be unavailable if the host is FIPS-140 compliant.
     type: str
     choices: [ md5, sha1, sha224, sha256, sha384, sha512 ]
@@ -47,8 +47,8 @@ options:
     description:
       - Use file magic and return data about the nature of the file. this uses
         the 'file' utility found on most Linux/Unix systems.
-      - This will add both C(mimetype) and C(charset) fields to the return, if possible.
-      - In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(true).
+      - This will add both RV(stat.mimetype) and RV(stat.charset) fields to the return, if possible.
+      - In Ansible 2.3 this option changed from O(mime) to O(get_mime) and the default changed to V(true).
     type: bool
     default: yes
     aliases: [ mime, mime_type, mime-type ]
@@ -144,7 +144,7 @@ RETURN = r'''
 stat:
     description: Dictionary containing all the stat data, some platforms might add additional fields.
     returned: success
-    type: complex
+    type: dict
     contains:
         exists:
             description: If the destination path actually exists or not
@@ -307,13 +307,6 @@ stat:
             type: str
             sample: ../foobar/21102015-1445431274-908472971
             version_added: 2.4
-        md5:
-            description: md5 hash of the file; this will be removed in Ansible 2.9 in
-                favor of the checksum return value
-            returned: success, path exists and user can read stats and path
-                supports hashing and md5 is supported
-            type: str
-            sample: f88fa92d8cf2eeecf4c0a50ccc96d0c0
         checksum:
             description: hash of the file
             returned: success, path exists, user can read stats, path supports
@@ -333,15 +326,15 @@ stat:
         mimetype:
             description: file magic data or mime-type
             returned: success, path exists and user can read stats and
-                installed python supports it and the I(get_mime) option was true, will
-                return C(unknown) on error.
+                installed python supports it and the O(get_mime) option was V(true), will
+                return V(unknown) on error.
             type: str
             sample: application/pdf; charset=binary
         charset:
             description: file character set or encoding
             returned: success, path exists and user can read stats and
-                installed python supports it and the I(get_mime) option was true, will
-                return C(unknown) on error.
+                installed python supports it and the O(get_mime) option was V(true), will
+                return V(unknown) on error.
             type: str
             sample: us-ascii
         readable:
@@ -384,7 +377,7 @@ import stat
 
 # import module snippets
 from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils._text import to_bytes
+from ansible.module_utils.common.text.converters import to_bytes
 
 
 def format_output(module, path, st):
@@ -454,7 +447,6 @@ def main():
         argument_spec=dict(
             path=dict(type='path', required=True, aliases=['dest', 'name']),
             follow=dict(type='bool', default=False),
-            get_md5=dict(type='bool', default=False),
             get_checksum=dict(type='bool', default=True),
             get_mime=dict(type='bool', default=True, aliases=['mime', 'mime_type', 'mime-type']),
             get_attributes=dict(type='bool', default=True, aliases=['attr', 'attributes']),
@@ -473,10 +465,6 @@ def main():
     get_checksum = module.params.get('get_checksum')
     checksum_algorithm = module.params.get('checksum_algorithm')
 
-    # NOTE: undocumented option since 2.9 to be removed at a later date if possible (3.0+)
-    # no real reason for keeping other than fear we may break older content.
-    get_md5 = module.params.get('get_md5')
-
     # main stat data
     try:
         if follow:
@@ -516,15 +504,6 @@ def main():
 
     # checksums
     if output.get('isreg') and output.get('readable'):
-
-        # NOTE: see above about get_md5
-        if get_md5:
-            # Will fail on FIPS-140 compliant systems
-            try:
-                output['md5'] = module.md5(b_path)
-            except ValueError:
-                output['md5'] = None
-
         if get_checksum:
             output['checksum'] = module.digest_from_file(b_path, checksum_algorithm)
 

ansible/modules/subversion.py

@@ -26,7 +26,7 @@ options:
   dest:
     description:
       - Absolute path where the repository should be deployed.
-      - The destination directory must be specified unless I(checkout=no), I(update=no), and I(export=no).
+      - The destination directory must be specified unless O(checkout=no), O(update=no), and O(export=no).
     type: path
   revision:
     description:
@@ -36,8 +36,8 @@ options:
     aliases: [ rev, version ]
   force:
     description:
-      - If C(true), modified files will be discarded. If C(false), module will fail if it encounters modified files.
-        Prior to 1.9 the default was C(true).
+      - If V(true), modified files will be discarded. If V(false), module will fail if it encounters modified files.
+        Prior to 1.9 the default was V(true).
     type: bool
     default: "no"
   in_place:
@@ -65,32 +65,32 @@ options:
     version_added: "1.4"
   checkout:
     description:
-     - If C(false), do not check out the repository if it does not exist locally.
+     - If V(false), do not check out the repository if it does not exist locally.
     type: bool
     default: "yes"
     version_added: "2.3"
   update:
     description:
-     - If C(false), do not retrieve new revisions from the origin repository.
+     - If V(false), do not retrieve new revisions from the origin repository.
     type: bool
     default: "yes"
     version_added: "2.3"
   export:
     description:
-      - If C(true), do export instead of checkout/update.
+      - If V(true), do export instead of checkout/update.
     type: bool
     default: "no"
     version_added: "1.6"
   switch:
     description:
-      - If C(false), do not call svn switch before update.
+      - If V(false), do not call svn switch before update.
     default: "yes"
     version_added: "2.0"
     type: bool
   validate_certs:
     description:
-      - If C(false), passes the C(--trust-server-cert) flag to svn.
-      - If C(true), does not pass the flag.
+      - If V(false), passes the C(--trust-server-cert) flag to svn.
+      - If V(true), does not pass the flag.
     default: "no"
     version_added: "2.11"
     type: bool

ansible/modules/systemd.py

@@ -25,8 +25,9 @@ options:
         aliases: [ service, unit ]
     state:
         description:
-            - C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
-              C(restarted) will always bounce the unit. C(reloaded) will always reload.
+            - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+              V(restarted) will always bounce the unit.
+              V(reloaded) will always reload and if the service is not running at the moment of the reload, it is started.
         type: str
         choices: [ reloaded, restarted, started, stopped ]
     enabled:
@@ -45,7 +46,7 @@ options:
     daemon_reload:
         description:
             - Run daemon-reload before doing any other operations, to make sure systemd has read any changes.
-            - When set to C(true), runs daemon-reload even if the module does not start or stop anything.
+            - When set to V(true), runs daemon-reload even if the module does not start or stop anything.
         type: bool
         default: no
         aliases: [ daemon-reload ]
@@ -58,8 +59,8 @@ options:
         version_added: "2.8"
     scope:
         description:
-            - Run systemctl within a given service manager scope, either as the default system scope C(system),
-              the current user's scope C(user), or the scope of all users C(global).
+            - Run systemctl within a given service manager scope, either as the default system scope V(system),
+              the current user's scope V(user), or the scope of all users V(global).
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
@@ -85,9 +86,9 @@ attributes:
     platform:
         platforms: posix
 notes:
-    - Since 2.4, one of the following options is required C(state), C(enabled), C(masked), C(daemon_reload), (C(daemon_reexec) since 2.8),
-      and all except C(daemon_reload) and (C(daemon_reexec) since 2.8) also require C(name).
-    - Before 2.4 you always required C(name).
+    - Since 2.4, one of the following options is required O(state), O(enabled), O(masked), O(daemon_reload), (O(daemon_reexec) since 2.8),
+      and all except O(daemon_reload) and (O(daemon_reexec) since 2.8) also require O(name).
+    - Before 2.4 you always required O(name).
     - Globs are not supported in name, i.e C(postgres*.service).
     - The service names might vary by specific OS/distribution
     - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state.
@@ -98,48 +99,48 @@ requirements:
 
 EXAMPLES = '''
 - name: Make sure a service unit is running
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     state: started
     name: httpd
 
 - name: Stop service cron on debian, if running
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: cron
     state: stopped
 
 - name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     state: restarted
     daemon_reload: true
     name: crond
 
 - name: Reload service httpd, in all cases
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: httpd.service
     state: reloaded
 
 - name: Enable service httpd and ensure it is not masked
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: httpd
     enabled: true
     masked: no
 
 - name: Enable a timer unit for dnf-automatic
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: dnf-automatic.timer
     state: started
     enabled: true
 
 - name: Just force systemd to reread configs (2.4 and above)
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     daemon_reload: true
 
 - name: Just force systemd to re-execute itself (2.8 and above)
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     daemon_reexec: true
 
 - name: Run a user service when XDG_RUNTIME_DIR is not set on remote login
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: myservice
     state: started
     scope: user
@@ -151,7 +152,7 @@ RETURN = '''
 status:
     description: A dictionary with the key=value pairs returned from C(systemctl show).
     returned: success
-    type: complex
+    type: dict
     sample: {
             "ActiveEnterTimestamp": "Sun 2016-05-15 18:28:49 EDT",
             "ActiveEnterTimestampMonotonic": "8135942",
@@ -282,7 +283,7 @@ import os
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.facts.system.chroot import is_chroot
 from ansible.module_utils.service import sysv_exists, sysv_is_enabled, fail_if_missing
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 
 def is_running_service(service_status):

ansible/modules/systemd_service.py

@@ -25,8 +25,9 @@ options:
         aliases: [ service, unit ]
     state:
         description:
-            - C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
-              C(restarted) will always bounce the unit. C(reloaded) will always reload.
+            - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+              V(restarted) will always bounce the unit.
+              V(reloaded) will always reload and if the service is not running at the moment of the reload, it is started.
         type: str
         choices: [ reloaded, restarted, started, stopped ]
     enabled:
@@ -45,7 +46,7 @@ options:
     daemon_reload:
         description:
             - Run daemon-reload before doing any other operations, to make sure systemd has read any changes.
-            - When set to C(true), runs daemon-reload even if the module does not start or stop anything.
+            - When set to V(true), runs daemon-reload even if the module does not start or stop anything.
         type: bool
         default: no
         aliases: [ daemon-reload ]
@@ -58,8 +59,8 @@ options:
         version_added: "2.8"
     scope:
         description:
-            - Run systemctl within a given service manager scope, either as the default system scope C(system),
-              the current user's scope C(user), or the scope of all users C(global).
+            - Run systemctl within a given service manager scope, either as the default system scope V(system),
+              the current user's scope V(user), or the scope of all users V(global).
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
@@ -85,9 +86,9 @@ attributes:
     platform:
         platforms: posix
 notes:
-    - Since 2.4, one of the following options is required C(state), C(enabled), C(masked), C(daemon_reload), (C(daemon_reexec) since 2.8),
-      and all except C(daemon_reload) and (C(daemon_reexec) since 2.8) also require C(name).
-    - Before 2.4 you always required C(name).
+    - Since 2.4, one of the following options is required O(state), O(enabled), O(masked), O(daemon_reload), (O(daemon_reexec) since 2.8),
+      and all except O(daemon_reload) and (O(daemon_reexec) since 2.8) also require O(name).
+    - Before 2.4 you always required O(name).
     - Globs are not supported in name, i.e C(postgres*.service).
     - The service names might vary by specific OS/distribution
     - The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state.
@@ -98,48 +99,48 @@ requirements:
 
 EXAMPLES = '''
 - name: Make sure a service unit is running
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     state: started
     name: httpd
 
 - name: Stop service cron on debian, if running
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: cron
     state: stopped
 
 - name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     state: restarted
     daemon_reload: true
     name: crond
 
 - name: Reload service httpd, in all cases
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: httpd.service
     state: reloaded
 
 - name: Enable service httpd and ensure it is not masked
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: httpd
     enabled: true
     masked: no
 
 - name: Enable a timer unit for dnf-automatic
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: dnf-automatic.timer
     state: started
     enabled: true
 
 - name: Just force systemd to reread configs (2.4 and above)
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     daemon_reload: true
 
 - name: Just force systemd to re-execute itself (2.8 and above)
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     daemon_reexec: true
 
 - name: Run a user service when XDG_RUNTIME_DIR is not set on remote login
-  ansible.builtin.systemd:
+  ansible.builtin.systemd_service:
     name: myservice
     state: started
     scope: user
@@ -151,7 +152,7 @@ RETURN = '''
 status:
     description: A dictionary with the key=value pairs returned from C(systemctl show).
     returned: success
-    type: complex
+    type: dict
     sample: {
             "ActiveEnterTimestamp": "Sun 2016-05-15 18:28:49 EDT",
             "ActiveEnterTimestampMonotonic": "8135942",
@@ -282,7 +283,7 @@ import os
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.facts.system.chroot import is_chroot
 from ansible.module_utils.service import sysv_exists, sysv_is_enabled, fail_if_missing
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 
 def is_running_service(service_status):

ansible/modules/sysvinit.py

@@ -26,8 +26,8 @@ options:
     state:
         choices: [ 'started', 'stopped', 'restarted', 'reloaded' ]
         description:
-            - C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
-              Not all init scripts support C(restarted) nor C(reloaded) natively, so these will both trigger a stop and start as needed.
+            - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
+              Not all init scripts support V(restarted) nor V(reloaded) natively, so these will both trigger a stop and start as needed.
         type: str
     enabled:
         type: bool
@@ -36,7 +36,7 @@ options:
     sleep:
         default: 1
         description:
-            - If the service is being C(restarted) or C(reloaded) then sleep this many seconds between the stop and start command.
+            - If the service is being V(restarted) or V(reloaded) then sleep this many seconds between the stop and start command.
               This helps to workaround badly behaving services.
         type: int
     pattern:
@@ -102,24 +102,29 @@ results:
     description: results from actions taken
     returned: always
     type: complex
-    sample: {
-            "attempts": 1,
-            "changed": true,
-            "name": "apache2",
-            "status": {
-                "enabled": {
-                    "changed": true,
-                    "rc": 0,
-                    "stderr": "",
-                    "stdout": ""
-                },
-                "stopped": {
-                    "changed": true,
-                    "rc": 0,
-                    "stderr": "",
-                    "stdout": "Stopping web server: apache2.\n"
-                }
-            }
+    contains:
+      name:
+        description: Name of the service
+        type: str
+        returned: always
+        sample: "apache2"
+      status:
+        description: Status of the service
+        type: dict
+        returned: changed
+        sample: {
+          "enabled": {
+             "changed": true,
+             "rc": 0,
+             "stderr": "",
+             "stdout": ""
+          },
+          "stopped": {
+             "changed": true,
+             "rc": 0,
+             "stderr": "",
+             "stdout": "Stopping web server: apache2.\n"
+          }
         }
 '''
 

ansible/modules/tempfile.py

@@ -14,9 +14,10 @@ module: tempfile
 version_added: "2.3"
 short_description: Creates temporary files and directories
 description:
-  - The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps
-    to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible
-    you need to use M(ansible.builtin.file) module.
+  - The M(ansible.builtin.tempfile) module creates temporary files and directories. C(mktemp) command
+    takes different parameters on various systems, this module helps to avoid troubles related to that.
+    Files/directories created by module are accessible only by creator. In case you need to make them
+    world-accessible you need to use M(ansible.builtin.file) module.
   - For Windows targets, use the M(ansible.windows.win_tempfile) module instead.
 options:
   state:
@@ -87,7 +88,7 @@ from tempfile import mkstemp, mkdtemp
 from traceback import format_exc
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 
 def main():

ansible/modules/template.py

@@ -18,16 +18,17 @@ options:
   follow:
     description:
     - Determine whether symbolic links should be followed.
-    - When set to C(true) symbolic links will be followed, if they exist.
-    - When set to C(false) symbolic links will not be followed.
-    - Previous to Ansible 2.4, this was hardcoded as C(true).
+    - When set to V(true) symbolic links will be followed, if they exist.
+    - When set to V(false) symbolic links will not be followed.
+    - Previous to Ansible 2.4, this was hardcoded as V(true).
     type: bool
     default: no
     version_added: '2.4'
 notes:
-- For Windows you can use M(ansible.windows.win_template) which uses C(\r\n) as C(newline_sequence) by default.
-- The C(jinja2_native) setting has no effect. Native types are never used in the C(template) module which is by design used for generating text files.
-  For working with templates and utilizing Jinja2 native types see the C(jinja2_native) parameter of the C(template lookup).
+- For Windows you can use M(ansible.windows.win_template) which uses V(\\r\\n) as O(newline_sequence) by default.
+- The C(jinja2_native) setting has no effect. Native types are never used in the M(ansible.builtin.template) module
+  which is by design used for generating text files. For working with templates and utilizing Jinja2 native types see
+  the O(ansible.builtin.template#lookup:jinja2_native) parameter of the P(ansible.builtin.template#lookup) lookup.
 seealso:
 - module: ansible.builtin.copy
 - module: ansible.windows.win_copy
@@ -109,3 +110,56 @@ EXAMPLES = r'''
     validate: /usr/sbin/sshd -t -f %s
     backup: yes
 '''
+
+RETURN = r'''
+dest:
+    description: Destination file/path, equal to the value passed to I(dest).
+    returned: success
+    type: str
+    sample: /path/to/file.txt
+checksum:
+    description: SHA1 checksum of the rendered file
+    returned: always
+    type: str
+    sample: 373296322247ab85d26d5d1257772757e7afd172
+uid:
+    description: Numeric id representing the file owner
+    returned: success
+    type: int
+    sample: 1003
+gid:
+    description: Numeric id representing the group of the owner
+    returned: success
+    type: int
+    sample: 1003
+owner:
+    description: User name of owner
+    returned: success
+    type: str
+    sample: httpd
+group:
+    description: Group name of owner
+    returned: success
+    type: str
+    sample: www-data
+md5sum:
+    description: MD5 checksum of the rendered file
+    returned: changed
+    type: str
+    sample: d41d8cd98f00b204e9800998ecf8427e
+mode:
+    description: Unix permissions of the file in octal representation as a string
+    returned: success
+    type: str
+    sample: 1755
+size:
+    description: Size of the rendered file in bytes
+    returned: success
+    type: int
+    sample: 42
+src:
+    description: Source file used for the copy on the target machine.
+    returned: changed
+    type: str
+    sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
+'''