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

ansible/modules/replace.py

@@ -39,7 +39,7 @@ options:
   path:
     description:
       - The file to modify.
-      - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
+      - Before Ansible 2.3 this option was only usable as O(dest), O(destfile) and O(name).
     type: path
     required: true
     aliases: [ dest, destfile, name ]
@@ -48,13 +48,13 @@ options:
       - The regular expression to look for in the contents of the file.
       - Uses Python regular expressions; see
         U(https://docs.python.org/3/library/re.html).
-      - Uses MULTILINE mode, which means C(^) and C($) match the beginning
+      - Uses MULTILINE mode, which means V(^) and V($) match the beginning
         and end of the file, as well as the beginning and end respectively
         of I(each line) of the file.
-      - Does not use DOTALL, which means the C(.) special character matches
+      - Does not use DOTALL, which means the V(.) special character matches
         any character I(except newlines). A common mistake is to assume that
-        a negated character set like C([^#]) will also not match newlines.
-      - In order to exclude newlines, they must be added to the set like C([^#\n]).
+        a negated character set like V([^#]) will also not match newlines.
+      - In order to exclude newlines, they must be added to the set like V([^#\\n]).
       - Note that, as of Ansible 2.0, short form tasks should have any escape
         sequences backslash-escaped in order to prevent them being parsed
         as string literal escapes. See the examples.
@@ -65,25 +65,25 @@ options:
       - The string to replace regexp matches.
       - May contain backreferences that will get expanded with the regexp capture groups if the regexp matches.
       - If not set, matches are removed entirely.
-      - Backreferences can be used ambiguously like C(\1), or explicitly like C(\g<1>).
+      - Backreferences can be used ambiguously like V(\\1), or explicitly like V(\\g<1>).
     type: str
     default: ''
   after:
     description:
       - If specified, only content after this match will be replaced/removed.
-      - Can be used in combination with C(before).
+      - Can be used in combination with O(before).
       - Uses Python regular expressions; see
         U(https://docs.python.org/3/library/re.html).
-      - Uses DOTALL, which means the C(.) special character I(can match newlines).
+      - Uses DOTALL, which means the V(.) special character I(can match newlines).
     type: str
     version_added: "2.4"
   before:
     description:
       - If specified, only content before this match will be replaced/removed.
-      - Can be used in combination with C(after).
+      - Can be used in combination with O(after).
       - Uses Python regular expressions; see
         U(https://docs.python.org/3/library/re.html).
-      - Uses DOTALL, which means the C(.) special character I(can match newlines).
+      - Uses DOTALL, which means the V(.) special character I(can match newlines).
     type: str
     version_added: "2.4"
   backup:
@@ -103,11 +103,12 @@ options:
     default: utf-8
     version_added: "2.4"
 notes:
-  - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well.
-  - As of Ansible 2.7.10, the combined use of I(before) and I(after) works properly. If you were relying on the
+  - As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
+  - As of Ansible 2.7.10, the combined use of O(before) and O(after) works properly. If you were relying on the
     previous incorrect behavior, you may be need to adjust your tasks.
     See U(https://github.com/ansible/ansible/issues/31354) for details.
-  - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense.
+  - Option O(ignore:follow) has been removed in Ansible 2.5, because this module modifies the contents of the file
+    so O(ignore:follow=no) does not make sense.
 '''
 
 EXAMPLES = r'''
@@ -185,7 +186,7 @@ import re
 import tempfile
 from traceback import format_exc
 
-from ansible.module_utils._text import to_text, to_bytes
+from ansible.module_utils.common.text.converters import to_text, to_bytes
 from ansible.module_utils.basic import AnsibleModule
 
 
@@ -284,7 +285,11 @@ def main():
         section = contents
 
     mre = re.compile(params['regexp'], re.MULTILINE)
-    result = re.subn(mre, params['replace'], section, 0)
+    try:
+        result = re.subn(mre, params['replace'], section, 0)
+    except re.error as e:
+        module.fail_json(msg="Unable to process replace due to error: %s" % to_text(e),
+                         exception=format_exc())
 
     if result[1] > 0 and section != result[0]:
         if pattern:

ansible/modules/rpm_key.py

@@ -33,7 +33,7 @@ options:
       choices: [ absent, present ]
     validate_certs:
       description:
-        - If C(false) and the C(key) is a url starting with https, SSL certificates will not be validated.
+        - If V(false) and the O(key) is a url starting with V(https), SSL certificates will not be validated.
         - This should only be used on personally controlled sites using self-signed certificates.
       type: bool
       default: 'yes'
@@ -85,7 +85,7 @@ import tempfile
 # import module snippets
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.urls import fetch_url
-from ansible.module_utils._text import to_native
+from ansible.module_utils.common.text.converters import to_native
 
 
 def is_pubkey(string):

ansible/modules/script.py

@@ -11,16 +11,17 @@ module: script
 version_added: "0.9"
 short_description: Runs a local script on a remote node after transferring it
 description:
-  - The C(script) module takes the script name followed by a list of space-delimited arguments.
-  - Either a free form command or C(cmd) parameter is required, see the examples.
-  - The local script at path will be transferred to the remote node and then executed.
+  - The M(ansible.builtin.script) module takes the script name followed by a list of space-delimited arguments.
+  - Either a free-form command or O(cmd) parameter is required, see the examples.
+  - The local script at the path will be transferred to the remote node and then executed.
   - The given script will be processed through the shell environment on the remote node.
-  - This module does not require python on the remote system, much like the M(ansible.builtin.raw) module.
+  - This module does not require Python on the remote system, much like the M(ansible.builtin.raw) module.
   - This module is also supported for Windows targets.
 options:
   free_form:
     description:
       - Path to the local script file followed by optional arguments.
+    type: str
   cmd:
     type: str
     description:
@@ -29,25 +30,30 @@ options:
     description:
       - A filename on the remote node, when it already exists, this step will B(not) be run.
     version_added: "1.5"
+    type: str
   removes:
     description:
       - A filename on the remote node, when it does not exist, this step will B(not) be run.
     version_added: "1.5"
+    type: str
   chdir:
     description:
       - Change into this directory on the remote node before running the script.
     version_added: "2.4"
+    type: str
   executable:
     description:
-      - Name or path of a executable to invoke the script with.
+      - Name or path of an executable to invoke the script with.
     version_added: "2.6"
+    type: str
 notes:
   - It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points!
-  - The C(ssh) connection plugin will force pseudo-tty allocation via C(-tt) when scripts are executed. Pseudo-ttys do not have a stderr channel and all
-    stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
+  - The P(ansible.builtin.ssh#connection) connection plugin will force pseudo-tty allocation via C(-tt) when scripts are executed.
+    Pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys,
+    please switch to a set of tasks that comprises M(ansible.builtin.copy) with M(ansible.builtin.command) instead of using M(ansible.builtin.script).
   - If the path to the local script contains spaces, it needs to be quoted.
   - This module is also supported for Windows targets.
-  - If the script returns non UTF-8 data, it must be encoded to avoid issues. One option is to pipe
+  - If the script returns non-UTF-8 data, it must be encoded to avoid issues. One option is to pipe
     the output through C(base64).
 seealso:
   - module: ansible.builtin.shell
@@ -63,7 +69,7 @@ extends_documentation_fragment:
 attributes:
     check_mode:
         support: partial
-        details: while the script itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
+        details: while the script itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
     diff_mode:
         support: none
     platform:
@@ -105,6 +111,6 @@ EXAMPLES = r'''
   args:
     executable: python3
 
-- name: Run a Powershell script on a windows host
+- name: Run a Powershell script on a Windows host
   script: subdirectories/under/path/with/your/playbook/script.ps1
 '''

ansible/modules/service.py

@@ -21,8 +21,8 @@ description:
     - This module is a proxy for multiple more specific service manager modules
       (such as M(ansible.builtin.systemd) and M(ansible.builtin.sysvinit)).
       This allows management of a heterogeneous environment of machines without creating a specific task for
-      each service manager. The module to be executed is determined by the I(use) option, which defaults to the
-      service manager discovered by M(ansible.builtin.setup).  If C(setup) was not yet run, this module may run it.
+      each service manager. The module to be executed is determined by the O(use) option, which defaults to the
+      service manager discovered by M(ansible.builtin.setup).  If M(ansible.builtin.setup) was not yet run, this module may run it.
     - For Windows targets, use the M(ansible.windows.win_service) module instead.
 options:
     name:
@@ -32,10 +32,10 @@ options:
         required: true
     state:
         description:
-          - C(started)/C(stopped) are idempotent actions that will not run
+          - V(started)/V(stopped) are idempotent actions that will not run
             commands unless necessary.
-          - C(restarted) will always bounce the service.
-          - C(reloaded) will always reload.
+          - V(restarted) will always bounce the service.
+          - V(reloaded) will always reload.
           - B(At least one of state and enabled are required.)
           - Note that reloaded will start the service if it is not already started,
             even if your chosen init system wouldn't normally.
@@ -43,7 +43,7 @@ options:
         choices: [ reloaded, restarted, started, stopped ]
     sleep:
         description:
-        - If the service is being C(restarted) then sleep this many seconds
+        - If the service is being V(restarted) then sleep this many seconds
           between the stop and start command.
         - This helps to work around badly-behaving init scripts that exit immediately
           after signaling a process to stop.
@@ -82,6 +82,7 @@ options:
         description:
         - The service module actually uses system specific modules, normally through auto detection, this setting can force a specific module.
         - Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found.
+        - The 'old service module' still uses autodetection and in no way does it correspond to the C(service) command.
         type: str
         default: auto
         version_added: 2.2
@@ -106,6 +107,9 @@ attributes:
         platforms: all
 notes:
     - For AIX, group subsystem names can be used.
+    - The C(service) command line utility is not part of any service manager system but a convenience.
+      It does not have a standard implementation across systems, and this action cannot use it directly.
+      Though it might be used if found in certain circumstances, the detected system service manager is normally preferred.
 seealso:
     - module: ansible.windows.win_service
 author:
@@ -172,7 +176,7 @@ import time
 if platform.system() != 'SunOS':
     from ansible.module_utils.compat.version import LooseVersion
 
-from ansible.module_utils._text import to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.locale import get_best_parsable_locale
 from ansible.module_utils.common.sys_info import get_platform_subclass
@@ -1191,107 +1195,31 @@ class OpenBsdService(Service):
             return self.execute_command("%s -f %s" % (self.svc_cmd, self.action))
 
     def service_enable(self):
+
         if not self.enable_cmd:
             return super(OpenBsdService, self).service_enable()
 
-        rc, stdout, stderr = self.execute_command("%s %s %s %s" % (self.enable_cmd, 'getdef', self.name, 'flags'))
-
-        if stderr:
-            self.module.fail_json(msg=stderr)
-
-        getdef_string = stdout.rstrip()
-
-        # Depending on the service the string returned from 'getdef' may be
-        # either a set of flags or the boolean YES/NO
-        if getdef_string == "YES" or getdef_string == "NO":
-            default_flags = ''
-        else:
-            default_flags = getdef_string
-
-        rc, stdout, stderr = self.execute_command("%s %s %s %s" % (self.enable_cmd, 'get', self.name, 'flags'))
-
-        if stderr:
-            self.module.fail_json(msg=stderr)
-
-        get_string = stdout.rstrip()
-
-        # Depending on the service the string returned from 'get' may be
-        # either a set of flags or the boolean YES/NO
-        if get_string == "YES" or get_string == "NO":
-            current_flags = ''
-        else:
-            current_flags = get_string
-
-        # If there are arguments from the user we use these as flags unless
-        # they are already set.
-        if self.arguments and self.arguments != current_flags:
-            changed_flags = self.arguments
-        # If the user has not supplied any arguments and the current flags
-        # differ from the default we reset them.
-        elif not self.arguments and current_flags != default_flags:
-            changed_flags = ' '
-        # Otherwise there is no need to modify flags.
-        else:
-            changed_flags = ''
-
         rc, stdout, stderr = self.execute_command("%s %s %s %s" % (self.enable_cmd, 'get', self.name, 'status'))
 
+        status_action = None
         if self.enable:
-            if rc == 0 and not changed_flags:
-                return
-
             if rc != 0:
-                status_action = "set %s status on" % (self.name)
-            else:
-                status_action = ''
-            if changed_flags:
-                flags_action = "set %s flags %s" % (self.name, changed_flags)
-            else:
-                flags_action = ''
-        else:
-            if rc == 1:
-                return
-
-            status_action = "set %s status off" % self.name
-            flags_action = ''
-
-        # Verify state assumption
-        if not status_action and not flags_action:
-            self.module.fail_json(msg="neither status_action or status_flags is set, this should never happen")
-
-        if self.module.check_mode:
-            self.module.exit_json(changed=True, msg="changing service enablement")
-
-        status_modified = 0
-        if status_action:
-            rc, stdout, stderr = self.execute_command("%s %s" % (self.enable_cmd, status_action))
-
-            if rc != 0:
-                if stderr:
-                    self.module.fail_json(msg=stderr)
-                else:
-                    self.module.fail_json(msg="rcctl failed to modify service status")
+                status_action = "on"
+        elif self.enable is not None:
+            # should be explicit False at this point
+            if rc != 1:
+                status_action = "off"
 
-            status_modified = 1
-
-        if flags_action:
-            rc, stdout, stderr = self.execute_command("%s %s" % (self.enable_cmd, flags_action))
+        if status_action is not None:
+            self.changed = True
+            if not self.module.check_mode:
+                rc, stdout, stderr = self.execute_command("%s set %s status %s" % (self.enable_cmd, self.name, status_action))
 
-            if rc != 0:
-                if stderr:
-                    if status_modified:
-                        error_message = "rcctl modified service status but failed to set flags: " + stderr
-                    else:
-                        error_message = stderr
-                else:
-                    if status_modified:
-                        error_message = "rcctl modified service status but failed to set flags"
+                if rc != 0:
+                    if stderr:
+                        self.module.fail_json(msg=stderr)
                     else:
-                        error_message = "rcctl failed to modify service flags"
-
-                self.module.fail_json(msg=error_message)
-
-        self.changed = True
+                        self.module.fail_json(msg="rcctl failed to modify service status")
 
 
 class NetBsdService(Service):

ansible/modules/service_facts.py

@@ -28,7 +28,7 @@ attributes:
     platform:
         platforms: posix
 notes:
-  - When accessing the C(ansible_facts.services) facts collected by this module,
+  - When accessing the RV(ansible_facts.services) facts collected by this module,
     it is recommended to not use "dot notation" because services can have a C(-)
     character in their name which would result in invalid "dot notation", such as
     C(ansible_facts.services.zuul-gateway). It is instead recommended to
@@ -57,19 +57,20 @@ ansible_facts:
     services:
       description: States of the services with service name as key.
       returned: always
-      type: complex
+      type: list
+      elements: dict
       contains:
         source:
           description:
           - Init system of the service.
-          - One of C(rcctl), C(systemd), C(sysv), C(upstart), C(src).
+          - One of V(rcctl), V(systemd), V(sysv), V(upstart), V(src).
           returned: always
           type: str
           sample: sysv
         state:
           description:
           - State of the service.
-          - 'This commonly includes (but is not limited to) the following: C(failed), C(running), C(stopped) or C(unknown).'
+          - 'This commonly includes (but is not limited to) the following: V(failed), V(running), V(stopped) or V(unknown).'
           - Depending on the used init system additional states might be returned.
           returned: always
           type: str
@@ -77,7 +78,7 @@ ansible_facts:
         status:
           description:
           - State of the service.
-          - Either C(enabled), C(disabled), C(static), C(indirect) or C(unknown).
+          - Either V(enabled), V(disabled), V(static), V(indirect) or V(unknown).
           returned: systemd systems or RedHat/SUSE flavored sysvinit/upstart or OpenBSD
           type: str
           sample: enabled
@@ -361,14 +362,31 @@ class OpenBSDScanService(BaseService):
                     svcs.append(svc)
         return svcs
 
+    def get_info(self, name):
+        info = {}
+        rc, stdout, stderr = self.module.run_command("%s get %s" % (self.rcctl_path, name))
+        if 'needs root privileges' in stderr.lower():
+            self.module.warn('rcctl requires root privileges')
+        else:
+            undy = '%s_' % name
+            for variable in stdout.split('\n'):
+                if variable == '' or '=' not in variable:
+                    continue
+                else:
+                    k, v = variable.replace(undy, '', 1).split('=')
+                    info[k] = v
+        return info
+
     def gather_services(self):
 
         services = {}
         self.rcctl_path = self.module.get_bin_path("rcctl")
         if self.rcctl_path:
 
+            # populate services will all possible
             for svc in self.query_rcctl('all'):
-                services[svc] = {'name': svc, 'source': 'rcctl'}
+                services[svc] = {'name': svc, 'source': 'rcctl', 'rogue': False}
+                services[svc].update(self.get_info(svc))
 
             for svc in self.query_rcctl('on'):
                 services[svc].update({'status': 'enabled'})
@@ -376,16 +394,22 @@ class OpenBSDScanService(BaseService):
             for svc in self.query_rcctl('started'):
                 services[svc].update({'state': 'running'})
 
-            # Based on the list of services that are enabled, determine which are disabled
-            [services[svc].update({'status': 'disabled'}) for svc in services if services[svc].get('status') is None]
-
-            # and do the same for those are aren't running
-            [services[svc].update({'state': 'stopped'}) for svc in services if services[svc].get('state') is None]
-
             # Override the state for services which are marked as 'failed'
             for svc in self.query_rcctl('failed'):
                 services[svc].update({'state': 'failed'})
 
+            for svc in services.keys():
+                # Based on the list of services that are enabled/failed, determine which are disabled
+                if services[svc].get('status') is None:
+                    services[svc].update({'status': 'disabled'})
+
+                # and do the same for those are aren't running
+                if services[svc].get('state') is None:
+                    services[svc].update({'state': 'stopped'})
+
+            for svc in self.query_rcctl('rogue'):
+                services[svc]['rogue'] = True
+
         return services
 
 

ansible/modules/set_fact.py

@@ -15,13 +15,13 @@ version_added: "1.2"
 description:
     - This action allows setting variables associated to the current host.
     - These variables will be available to subsequent plays during an ansible-playbook run via the host they were set on.
-    - Set C(cacheable) to C(true) to save variables across executions using a fact cache.
+    - Set O(cacheable) to V(true) to save variables across executions using a fact cache.
       Variables will keep the set_fact precedence for the current run, but will used 'cached fact' precedence for subsequent ones.
     - Per the standard Ansible variable precedence rules, other types of variables have a higher priority, so this value may be overridden.
 options:
   key_value:
     description:
-      - "The C(set_fact) module takes C(key=value) pairs or C(key: value) (YAML notation) as variables to set in the playbook scope.
+      - "The M(ansible.builtin.set_fact) module takes C(key=value) pairs or C(key: value) (YAML notation) as variables to set in the playbook scope.
         The 'key' is the resulting variable name and the value is, of course, the value of said variable."
       - You can create multiple variables at once, by supplying multiple pairs, but do NOT mix notations.
     required: true

ansible/modules/set_stats.py

@@ -28,7 +28,7 @@ options:
     default: no
   aggregate:
     description:
-        - Whether the provided value is aggregated to the existing stat C(true) or will replace it C(false).
+        - Whether the provided value is aggregated to the existing stat V(true) or will replace it V(false).
     type: bool
     default: yes
 extends_documentation_fragment:
@@ -55,7 +55,7 @@ attributes:
         support: none
 notes:
     - In order for custom stats to be displayed, you must set C(show_custom_stats) in section C([defaults]) in C(ansible.cfg)
-      or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to C(true). See the C(default) callback plugin for details.
+      or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to V(true). See the P(ansible.builtin.default#callback) callback plugin for details.
 version_added: "2.3"
 '''
 

ansible/modules/setup.py

@@ -17,24 +17,24 @@ options:
         version_added: "2.1"
         description:
             - "If supplied, restrict the additional facts collected to the given subset.
-              Possible values: C(all), C(all_ipv4_addresses), C(all_ipv6_addresses), C(apparmor), C(architecture),
-              C(caps), C(chroot),C(cmdline), C(date_time), C(default_ipv4), C(default_ipv6), C(devices),
-              C(distribution), C(distribution_major_version), C(distribution_release), C(distribution_version),
-              C(dns), C(effective_group_ids), C(effective_user_id), C(env), C(facter), C(fips), C(hardware),
-              C(interfaces), C(is_chroot), C(iscsi), C(kernel), C(local), C(lsb), C(machine), C(machine_id),
-              C(mounts), C(network), C(ohai), C(os_family), C(pkg_mgr), C(platform), C(processor), C(processor_cores),
-              C(processor_count), C(python), C(python_version), C(real_user_id), C(selinux), C(service_mgr),
-              C(ssh_host_key_dsa_public), C(ssh_host_key_ecdsa_public), C(ssh_host_key_ed25519_public),
-              C(ssh_host_key_rsa_public), C(ssh_host_pub_keys), C(ssh_pub_keys), C(system), C(system_capabilities),
-              C(system_capabilities_enforced), C(user), C(user_dir), C(user_gecos), C(user_gid), C(user_id),
-              C(user_shell), C(user_uid), C(virtual), C(virtualization_role), C(virtualization_type).
+              Possible values: V(all), V(all_ipv4_addresses), V(all_ipv6_addresses), V(apparmor), V(architecture),
+              V(caps), V(chroot),V(cmdline), V(date_time), V(default_ipv4), V(default_ipv6), V(devices),
+              V(distribution), V(distribution_major_version), V(distribution_release), V(distribution_version),
+              V(dns), V(effective_group_ids), V(effective_user_id), V(env), V(facter), V(fips), V(hardware),
+              V(interfaces), V(is_chroot), V(iscsi), V(kernel), V(local), V(lsb), V(machine), V(machine_id),
+              V(mounts), V(network), V(ohai), V(os_family), V(pkg_mgr), V(platform), V(processor), V(processor_cores),
+              V(processor_count), V(python), V(python_version), V(real_user_id), V(selinux), V(service_mgr),
+              V(ssh_host_key_dsa_public), V(ssh_host_key_ecdsa_public), V(ssh_host_key_ed25519_public),
+              V(ssh_host_key_rsa_public), V(ssh_host_pub_keys), V(ssh_pub_keys), V(system), V(system_capabilities),
+              V(system_capabilities_enforced), V(user), V(user_dir), V(user_gecos), V(user_gid), V(user_id),
+              V(user_shell), V(user_uid), V(virtual), V(virtualization_role), V(virtualization_type).
              Can specify a list of values to specify a larger subset.
              Values can also be used with an initial C(!) to specify that
               that specific subset should not be collected.  For instance:
-              C(!hardware,!network,!virtual,!ohai,!facter). If C(!all) is specified
+              V(!hardware,!network,!virtual,!ohai,!facter). If V(!all) is specified
               then only the min subset is collected. To avoid collecting even the
-              min subset, specify C(!all,!min). To collect only specific facts,
-              use C(!all,!min), and specify the particular fact subsets.
+              min subset, specify V(!all,!min). To collect only specific facts,
+              use V(!all,!min), and specify the particular fact subsets.
               Use the filter parameter if you do not want to display some collected
               facts."
         type: list
@@ -64,12 +64,12 @@ options:
             - Path used for local ansible facts (C(*.fact)) - files in this dir
               will be run (if executable) and their results be added to C(ansible_local) facts.
               If a file is not executable it is read instead.
-              File/results format can be JSON or INI-format. The default C(fact_path) can be
+              File/results format can be JSON or INI-format. The default O(fact_path) can be
               specified in C(ansible.cfg) for when setup is automatically called as part of
               C(gather_facts).
               NOTE - For windows clients, the results will be added to a variable named after the
               local file (without extension suffix), rather than C(ansible_local).
-            - Since Ansible 2.1, Windows hosts can use C(fact_path). Make sure that this path
+            - Since Ansible 2.1, Windows hosts can use O(fact_path). Make sure that this path
               exists on the target host. Files in this path MUST be PowerShell scripts C(.ps1)
               which outputs an object. This object will be formatted by Ansible as json so the
               script should be outputting a raw hashtable, array, or other primitive object.
@@ -104,7 +104,7 @@ notes:
       remote systems. (See also M(community.general.facter) and M(community.general.ohai).)
     - The filter option filters only the first level subkey below ansible_facts.
     - If the target host is Windows, you will not currently have the ability to use
-      C(filter) as this is provided by a simpler implementation of the module.
+      O(filter) as this is provided by a simpler implementation of the module.
     - This module should be run with elevated privileges on BSD systems to gather facts like ansible_product_version.
     - For more information about delegated facts,
       please check U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_delegation.html#delegating-facts).
@@ -174,7 +174,7 @@ EXAMPLES = r"""
 # import module snippets
 from ..module_utils.basic import AnsibleModule
 
-from ansible.module_utils._text import to_text
+from ansible.module_utils.common.text.converters import to_text
 from ansible.module_utils.facts import ansible_collector, default_collectors
 from ansible.module_utils.facts.collector import CollectorNotFoundError, CycleFoundInFactDeps, UnresolvedFactDep
 from ansible.module_utils.facts.namespace import PrefixFactNamespace

ansible/modules/shell.py

@@ -16,8 +16,8 @@ DOCUMENTATION = r'''
 module: shell
 short_description: Execute shell commands on targets
 description:
-     - The C(shell) module takes the command name followed by a list of space-delimited arguments.
-     - Either a free form command or C(cmd) parameter is required, see the examples.
+     - The M(ansible.builtin.shell) module takes the command name followed by a list of space-delimited arguments.
+     - Either a free form command or O(cmd) parameter is required, see the examples.
      - It is almost exactly like the M(ansible.builtin.command) module but runs
        the command through a shell (C(/bin/sh)) on the remote node.
      - For Windows targets, use the M(ansible.windows.win_shell) module instead.
@@ -69,7 +69,7 @@ extends_documentation_fragment:
     - action_common_attributes.raw
 attributes:
     check_mode:
-        details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
+        details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
         support: partial
     diff_mode:
         support: none