ansible-core 2.17.4__py3-none-any.whl → 2.18.0b1__py3-none-any.whl

ansible/__main__.py

@@ -3,9 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import importlib
-import os
-import sys
 
 from importlib.metadata import distribution
 
@@ -19,22 +16,10 @@ def main():
     ep_map = {_short_name(ep.name): ep for ep in dist.entry_points if ep.group == 'console_scripts'}
 
     parser = argparse.ArgumentParser(prog='python -m ansible', add_help=False)
-    parser.add_argument('entry_point', choices=list(ep_map) + ['test'])
+    parser.add_argument('entry_point', choices=list(ep_map))
     args, extra = parser.parse_known_args()
 
-    if args.entry_point == 'test':
-        ansible_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-        source_root = os.path.join(ansible_root, 'test', 'lib')
-
-        if os.path.exists(os.path.join(source_root, 'ansible_test', '_internal', '__init__.py')):
-            # running from source, use that version of ansible-test instead of any version that may already be installed
-            sys.path.insert(0, source_root)
-
-        module = importlib.import_module('ansible_test._util.target.cli.ansible_test_cli_stub')
-        main = module.main
-    else:
-        main = ep_map[args.entry_point].load()
-
+    main = ep_map[args.entry_point].load()
     main([args.entry_point] + extra)
 
 

ansible/cli/__init__.py

@@ -11,9 +11,9 @@ import sys
 
 # Used for determining if the system is running a new enough python version
 # and should only restrict on our documented minimum versions
-if sys.version_info < (3, 10):
+if sys.version_info < (3, 11):
     raise SystemExit(
-        'ERROR: Ansible requires Python 3.10 or newer on the controller. '
+        'ERROR: Ansible requires Python 3.11 or newer on the controller. '
         'Current version: %s' % ''.join(sys.version.splitlines())
     )
 
@@ -167,19 +167,7 @@ class CLI(ABC):
         else:
             display.v(u"No config file found; using defaults")
 
-        # warn about deprecated config options
-        for deprecated in C.config.DEPRECATED:
-            name = deprecated[0]
-            why = deprecated[1]['why']
-            if 'alternatives' in deprecated[1]:
-                alt = ', use %s instead' % deprecated[1]['alternatives']
-            else:
-                alt = ''
-            ver = deprecated[1].get('version')
-            date = deprecated[1].get('date')
-            collection_name = deprecated[1].get('collection_name')
-            display.deprecated("%s option, %s%s" % (name, why, alt),
-                               version=ver, date=date, collection_name=collection_name)
+        C.handle_config_noise(display)
 
     @staticmethod
     def split_vault_id(vault_id):

ansible/cli/config.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 from ansible.cli import CLI
 
 import os
-import yaml
 import shlex
 import subprocess
+import sys
+import yaml
 
 from collections.abc import Mapping
 
@@ -21,7 +22,7 @@ import ansible.plugins.loader as plugin_loader
 from ansible import constants as C
 from ansible.cli.arguments import option_helpers as opt_help
 from ansible.config.manager import ConfigManager, Setting
-from ansible.errors import AnsibleError, AnsibleOptionsError
+from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleRequiredOptionError
 from ansible.module_utils.common.text.converters import to_native, to_text, to_bytes
 from ansible.module_utils.common.json import json_dump
 from ansible.module_utils.six import string_types
@@ -34,6 +35,9 @@ from ansible.utils.path import unfrackpath
 display = Display()
 
 
+_IGNORE_CHANGED = frozenset({'_terms', '_input'})
+
+
 def yaml_dump(data, default_flow_style=False, default_style=None):
     return yaml.dump(data, Dumper=AnsibleDumper, default_flow_style=default_flow_style, default_style=default_style)
 
@@ -49,6 +53,37 @@ def get_constants():
     return get_constants.cvars
 
 
+def _ansible_env_vars(varname):
+    ''' return true or false depending if variable name is possibly a 'configurable' ansible env variable '''
+    return all(
+        [
+            varname.startswith("ANSIBLE_"),
+            not varname.startswith(("ANSIBLE_TEST_", "ANSIBLE_LINT_")),
+            varname not in ("ANSIBLE_CONFIG", "ANSIBLE_DEV_HOME"),
+        ]
+    )
+
+
+def _get_evar_list(settings):
+    data = []
+    for setting in settings:
+        if 'env' in settings[setting] and settings[setting]['env']:
+            for varname in settings[setting]['env']:
+                data.append(varname.get('name'))
+    return data
+
+
+def _get_ini_entries(settings):
+    data = {}
+    for setting in settings:
+        if 'ini' in settings[setting] and settings[setting]['ini']:
+            for kv in settings[setting]['ini']:
+                if not kv['section'] in data:
+                    data[kv['section']] = set()
+                data[kv['section']].add(kv['key'])
+    return data
+
+
 class ConfigCLI(CLI):
     """ Config command line class """
 
@@ -99,9 +134,13 @@ class ConfigCLI(CLI):
         init_parser.add_argument('--disabled', dest='commented', action='store_true', default=False,
                                  help='Prefixes all entries with a comment character to disable them')
 
-        # search_parser = subparsers.add_parser('find', help='Search configuration')
-        # search_parser.set_defaults(func=self.execute_search)
-        # search_parser.add_argument('args', help='Search term', metavar='<search term>')
+        validate_parser = subparsers.add_parser('validate',
+                                                help='Validate the configuration file and environment variables. '
+                                                     'By default it only checks the base settings without accounting for plugins (see -t).',
+                                                parents=[common])
+        validate_parser.set_defaults(func=self.execute_validate)
+        validate_parser.add_argument('--format', '-f', dest='format', action='store', choices=['ini', 'env'] , default='ini',
+                                     help='Output format for init')
 
     def post_process_args(self, options):
         options = super(ConfigCLI, self).post_process_args(options)
@@ -113,6 +152,10 @@ class ConfigCLI(CLI):
 
         super(ConfigCLI, self).run()
 
+        # initialize each galaxy server's options from known listed servers
+        self._galaxy_servers = [s for s in C.GALAXY_SERVER_LIST or [] if s]  # clean list, reused later here
+        C.config.load_galaxy_server_defs(self._galaxy_servers)
+
         if context.CLIARGS['config_file']:
             self.config_file = unfrackpath(context.CLIARGS['config_file'], follow=False)
             b_config = to_bytes(self.config_file)
@@ -226,11 +269,17 @@ class ConfigCLI(CLI):
         '''
         build a dict with the list requested configs
         '''
+
         config_entries = {}
         if context.CLIARGS['type'] in ('base', 'all'):
             # this dumps main/common configs
             config_entries = self.config.get_configuration_definitions(ignore_private=True)
 
+            # for base and all, we include galaxy servers
+            config_entries['GALAXY_SERVERS'] = {}
+            for server in self._galaxy_servers:
+                config_entries['GALAXY_SERVERS'][server] = self.config.get_configuration_definitions('galaxy_server', server)
+
         if context.CLIARGS['type'] != 'base':
             config_entries['PLUGINS'] = {}
 
@@ -239,6 +288,7 @@ class ConfigCLI(CLI):
             for ptype in C.CONFIGURABLE_PLUGINS:
                 config_entries['PLUGINS'][ptype.upper()] = self._list_plugin_settings(ptype)
         elif context.CLIARGS['type'] != 'base':
+            # only for requested types
             config_entries['PLUGINS'][context.CLIARGS['type']] = self._list_plugin_settings(context.CLIARGS['type'], context.CLIARGS['args'])
 
         return config_entries
@@ -358,7 +408,7 @@ class ConfigCLI(CLI):
                     elif default is None:
                         default = ''
 
-                    if context.CLIARGS['commented']:
+                    if context.CLIARGS.get('commented', False):
                         entry['key'] = ';%s' % entry['key']
 
                     key = desc + '\n%s=%s' % (entry['key'], default)
@@ -408,13 +458,13 @@ class ConfigCLI(CLI):
 
         entries = []
         for setting in sorted(config):
-            changed = (config[setting].origin not in ('default', 'REQUIRED'))
+            changed = (config[setting].origin not in ('default', 'REQUIRED') and setting not in _IGNORE_CHANGED)
 
             if context.CLIARGS['format'] == 'display':
                 if isinstance(config[setting], Setting):
                     # proceed normally
                     value = config[setting].value
-                    if config[setting].origin == 'default':
+                    if config[setting].origin == 'default' or setting in _IGNORE_CHANGED:
                         color = 'green'
                         value = self.config.template_default(value, get_constants())
                     elif config[setting].origin == 'REQUIRED':
@@ -431,6 +481,8 @@ class ConfigCLI(CLI):
             else:
                 entry = {}
                 for key in config[setting]._fields:
+                    if key == 'type':
+                        continue
                     entry[key] = getattr(config[setting], key)
 
             if not context.CLIARGS['only_changed'] or changed:
@@ -439,7 +491,10 @@ class ConfigCLI(CLI):
         return entries
 
     def _get_global_configs(self):
-        config = self.config.get_configuration_definitions(ignore_private=True).copy()
+
+        # Add base
+        config = self.config.get_configuration_definitions(ignore_private=True)
+        # convert to settings
         for setting in config.keys():
             v, o = C.config.get_config_value_and_origin(setting, cfile=self.config_file, variables=get_constants())
             config[setting] = Setting(setting, v, o, None)
@@ -451,7 +506,7 @@ class ConfigCLI(CLI):
         # prep loading
         loader = getattr(plugin_loader, '%s_loader' % ptype)
 
-        # acumulators
+        # accumulators
         output = []
         config_entries = {}
 
@@ -468,7 +523,7 @@ class ConfigCLI(CLI):
             plugin_cs = loader.all(class_only=True)
 
         for plugin in plugin_cs:
-            # in case of deprecastion they diverge
+            # in case of deprecation they diverge
             finalname = name = plugin._load_name
             if name.startswith('_'):
                 if os.path.islink(plugin._original_path):
@@ -491,12 +546,9 @@ class ConfigCLI(CLI):
             for setting in config_entries[finalname].keys():
                 try:
                     v, o = C.config.get_config_value_and_origin(setting, cfile=self.config_file, plugin_type=ptype, plugin_name=name, variables=get_constants())
-                except AnsibleError as e:
-                    if to_text(e).startswith('No setting was provided for required configuration'):
-                        v = None
-                        o = 'REQUIRED'
-                    else:
-                        raise e
+                except AnsibleRequiredOptionError:
+                    v = None
+                    o = 'REQUIRED'
 
                 if v is None and o is None:
                     # not all cases will be error
@@ -516,17 +568,60 @@ class ConfigCLI(CLI):
 
         return output
 
+    def _get_galaxy_server_configs(self):
+
+        output = []
+        # add galaxy servers
+        for server in self._galaxy_servers:
+            server_config = {}
+            s_config = self.config.get_configuration_definitions('galaxy_server', server)
+            for setting in s_config.keys():
+                try:
+                    v, o = C.config.get_config_value_and_origin(setting, plugin_type='galaxy_server', plugin_name=server, cfile=self.config_file)
+                except AnsibleError as e:
+                    if s_config[setting].get('required', False):
+                        v = None
+                        o = 'REQUIRED'
+                    else:
+                        raise e
+                if v is None and o is None:
+                    # not all cases will be error
+                    o = 'REQUIRED'
+                server_config[setting] = Setting(setting, v, o, None)
+            if context.CLIARGS['format'] == 'display':
+                if not context.CLIARGS['only_changed'] or server_config:
+                    equals = '=' * len(server)
+                    output.append(f'\n{server}\n{equals}')
+                    output.extend(self._render_settings(server_config))
+            else:
+                output.append({server: server_config})
+
+        return output
+
     def execute_dump(self):
         '''
         Shows the current settings, merges ansible.cfg if specified
         '''
-        if context.CLIARGS['type'] == 'base':
-            # deal with base
-            output = self._get_global_configs()
-        elif context.CLIARGS['type'] == 'all':
+        output = []
+        if context.CLIARGS['type'] in ('base', 'all'):
             # deal with base
             output = self._get_global_configs()
-            # deal with plugins
+
+            # add galaxy servers
+            server_config_list = self._get_galaxy_server_configs()
+            if context.CLIARGS['format'] == 'display':
+                output.append('\nGALAXY_SERVERS:\n')
+                output.extend(server_config_list)
+            else:
+                configs = {}
+                for server_config in server_config_list:
+                    server = list(server_config.keys())[0]
+                    server_reduced_config = server_config.pop(server)
+                    configs[server] = server_reduced_config
+                output.append({'GALAXY_SERVERS': configs})
+
+        if context.CLIARGS['type'] == 'all':
+            # add all plugins
             for ptype in C.CONFIGURABLE_PLUGINS:
                 plugin_list = self._get_plugin_configs(ptype, context.CLIARGS['args'])
                 if context.CLIARGS['format'] == 'display':
@@ -539,8 +634,9 @@ class ConfigCLI(CLI):
                     else:
                         pname = '%s_PLUGINS' % ptype.upper()
                     output.append({pname: plugin_list})
-        else:
-            # deal with plugins
+
+        elif context.CLIARGS['type'] != 'base':
+            # deal with specific plugin
             output = self._get_plugin_configs(context.CLIARGS['type'], context.CLIARGS['args'])
 
         if context.CLIARGS['format'] == 'display':
@@ -552,6 +648,73 @@ class ConfigCLI(CLI):
 
         self.pager(to_text(text, errors='surrogate_or_strict'))
 
+    def execute_validate(self):
+
+        found = False
+        config_entries = self._list_entries_from_args()
+        plugin_types = config_entries.pop('PLUGINS', None)
+        galaxy_servers = config_entries.pop('GALAXY_SERVERS', None)
+
+        if context.CLIARGS['format'] == 'ini':
+            if C.CONFIG_FILE is not None:
+                # validate ini config since it is found
+
+                sections = _get_ini_entries(config_entries)
+                # Also from plugins
+                if plugin_types:
+                    for ptype in plugin_types:
+                        for plugin in plugin_types[ptype].keys():
+                            plugin_sections = _get_ini_entries(plugin_types[ptype][plugin])
+                            for s in plugin_sections:
+                                if s in sections:
+                                    sections[s].update(plugin_sections[s])
+                                else:
+                                    sections[s] = plugin_sections[s]
+                if galaxy_servers:
+                    for server in galaxy_servers:
+                        server_sections = _get_ini_entries(galaxy_servers[server])
+                        for s in server_sections:
+                            if s in sections:
+                                sections[s].update(server_sections[s])
+                            else:
+                                sections[s] = server_sections[s]
+                if sections:
+                    p = C.config._parsers[C.CONFIG_FILE]
+                    for s in p.sections():
+                        # check for valid sections
+                        if s not in sections:
+                            display.error(f"Found unknown section '{s}' in '{C.CONFIG_FILE}.")
+                            found = True
+                            continue
+
+                        # check keys in valid sections
+                        for k in p.options(s):
+                            if k not in sections[s]:
+                                display.error(f"Found unknown key '{k}' in section '{s}' in '{C.CONFIG_FILE}.")
+                                found = True
+
+        elif context.CLIARGS['format'] == 'env':
+            # validate any 'ANSIBLE_' env vars found
+            evars = [varname for varname in os.environ.keys() if _ansible_env_vars(varname)]
+            if evars:
+                data = _get_evar_list(config_entries)
+                if plugin_types:
+                    for ptype in plugin_types:
+                        for plugin in plugin_types[ptype].keys():
+                            data.extend(_get_evar_list(plugin_types[ptype][plugin]))
+
+                for evar in evars:
+                    if evar not in data:
+                        display.error(f"Found unknown environment variable '{evar}'.")
+                        found = True
+
+        # we found discrepancies!
+        if found:
+            sys.exit(1)
+
+        # allsgood
+        display.display("All configurations seem valid!")
+
 
 def main(args=None):
     ConfigCLI.cli_executor(args)

ansible/cli/console.py

@@ -545,7 +545,7 @@ class ConsoleCLI(CLI, cmd.Cmd):
                 if path:
                     module_loader.add_directory(path)
 
-        # dynamically add 'cannonical' modules as commands, aliases coudld be used and dynamically loaded
+        # dynamically add 'canonical' modules as commands, aliases could be used and dynamically loaded
         self.modules = self.list_modules()
         for module in self.modules:
             setattr(self, 'do_' + module, lambda arg, module=module: self.default(module + ' ' + arg))

ansible/cli/doc.py

@@ -50,7 +50,7 @@ PB_OBJECTS = ['Play', 'Role', 'Block', 'Task', 'Handler']
 PB_LOADED = {}
 SNIPPETS = ['inventory', 'lookup', 'module']
 
-# harcoded from ascii values
+# hardcoded from ascii values
 STYLE = {
     'BLINK': '\033[5m',
     'BOLD': '\033[1m',
@@ -71,8 +71,14 @@ NOCOLOR = {
     'PLUGIN': r'[%s]',
 }
 
-# TODO: make configurable
-ref_style = {'MODULE': 'yellow', 'REF': 'magenta', 'LINK': 'cyan', 'DEP': 'magenta', 'CONSTANT': 'dark gray', 'PLUGIN': 'yellow'}
+ref_style = {
+    'MODULE': C.COLOR_DOC_MODULE,
+    'REF': C.COLOR_DOC_REFERENCE,
+    'LINK': C.COLOR_DOC_LINK,
+    'DEP': C.COLOR_DOC_DEPRECATED,
+    'CONSTANT': C.COLOR_DOC_CONSTANT,
+    'PLUGIN': C.COLOR_DOC_PLUGIN,
+}
 
 
 def jdump(text):
@@ -381,6 +387,12 @@ class RoleMixin(object):
 
         for role, collection, role_path in (roles | collroles):
             argspec = self._load_argspec(role, role_path, collection)
+            if 'error' in argspec:
+                if fail_on_errors:
+                    raise argspec['exception']
+                else:
+                    display.warning('Skipping role (%s) due to: %s' % (role, argspec['error']), True)
+                    continue
             fqcn, doc = self._build_doc(role, role_path, collection, argspec, entry_point)
             if doc:
                 result[fqcn] = doc
@@ -881,6 +893,7 @@ class DocCLI(CLI, RoleMixin):
         plugin_type = context.CLIARGS['type'].lower()
         do_json = context.CLIARGS['json_format'] or context.CLIARGS['dump']
         listing = context.CLIARGS['list_files'] or context.CLIARGS['list_dir']
+        no_fail = bool(not context.CLIARGS['no_fail_on_errors'])
 
         if context.CLIARGS['list_files']:
             content = 'files'
@@ -903,7 +916,6 @@ class DocCLI(CLI, RoleMixin):
             docs['all'] = {}
             for ptype in ptypes:
 
-                no_fail = bool(not context.CLIARGS['no_fail_on_errors'])
                 if ptype == 'role':
                     roles = self._create_role_list(fail_on_errors=no_fail)
                     docs['all'][ptype] = self._create_role_doc(roles.keys(), context.CLIARGS['entry_point'], fail_on_errors=no_fail)
@@ -929,7 +941,7 @@ class DocCLI(CLI, RoleMixin):
             if plugin_type == 'keyword':
                 docs = DocCLI._get_keywords_docs(context.CLIARGS['args'])
             elif plugin_type == 'role':
-                docs = self._create_role_doc(context.CLIARGS['args'], context.CLIARGS['entry_point'])
+                docs = self._create_role_doc(context.CLIARGS['args'], context.CLIARGS['entry_point'], fail_on_errors=no_fail)
             else:
                 # display specific plugin docs
                 docs = self._get_plugins_docs(plugin_type, context.CLIARGS['args'])
@@ -1083,7 +1095,7 @@ class DocCLI(CLI, RoleMixin):
             text = DocCLI.get_man_text(doc, collection_name, plugin_type)
         except Exception as e:
             display.vvv(traceback.format_exc())
-            raise AnsibleError("Unable to retrieve documentation from '%s' due to: %s" % (plugin, to_native(e)), orig_exc=e)
+            raise AnsibleError("Unable to retrieve documentation from '%s'" % (plugin), orig_exc=e)
 
         return text
 
@@ -1189,7 +1201,7 @@ class DocCLI(CLI, RoleMixin):
                     opt_leadin = "-"
                 key = "%s%s %s" % (base_indent, opt_leadin, _format(o, 'yellow'))
 
-            # description is specifically formated and can either be string or list of strings
+            # description is specifically formatted and can either be string or list of strings
             if 'description' not in opt:
                 raise AnsibleError("All (sub-)options and return values must have a 'description' field")
             text.append('')
@@ -1339,6 +1351,17 @@ class DocCLI(CLI, RoleMixin):
                     # use empty indent since this affects the start of the yaml doc, not it's keys
                     text.append(DocCLI._indent_lines(DocCLI._dump_yaml({k.upper(): doc[k]}), ''))
 
+            if doc.get('examples', False):
+                text.append('')
+                text.append(_format("EXAMPLES:", 'bold'))
+                if isinstance(doc['examples'], string_types):
+                    text.append(doc.pop('examples').strip())
+                else:
+                    try:
+                        text.append(yaml_dump(doc.pop('examples'), indent=2, default_flow_style=False))
+                    except Exception as e:
+                        raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
+
         return text
 
     @staticmethod
@@ -1370,16 +1393,15 @@ class DocCLI(CLI, RoleMixin):
         if doc.get('deprecated', False):
             text.append(_format("DEPRECATED: ", 'bold', 'DEP'))
             if isinstance(doc['deprecated'], dict):
-                if 'removed_at_date' in doc['deprecated']:
-                    text.append(
-                        "\tReason: %(why)s\n\tWill be removed in a release after %(removed_at_date)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated')
-                    )
-                else:
-                    if 'version' in doc['deprecated'] and 'removed_in' not in doc['deprecated']:
-                        doc['deprecated']['removed_in'] = doc['deprecated']['version']
-                    text.append("\tReason: %(why)s\n\tWill be removed in: Ansible %(removed_in)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated'))
+                if 'removed_at_date' not in doc['deprecated'] and 'version' in doc['deprecated'] and 'removed_in' not in doc['deprecated']:
+                    doc['deprecated']['removed_in'] = doc['deprecated']['version']
+                try:
+                    text.append('\t' + C.config.get_deprecated_msg_from_config(doc['deprecated'], True))
+                except KeyError as e:
+                    raise AnsibleError("Invalid deprecation documentation structure", orig_exc=e)
             else:
-                text.append("%s" % doc.pop('deprecated'))
+                text.append("%s" % doc['deprecated'])
+            del doc['deprecated']
 
         if doc.pop('has_action', False):
             text.append("")