config, moved 'choices info to keys (#76569)

* config, moved 'choices' from wall of text, to keys
* updated to ensure all pythons handle the 2 modes correctly
* Update lib/ansible/config/base.yml

Co-authored-by: Sandra McCann <samccann@redhat.com>

2 files changed, 38 insertions, 24 deletions

diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml
index 1c36451ec2..1707f74ad3 100644
--- a/lib/ansible/config/base.yml
+++ b/lib/ansible/config/base.yml
@@ -223,12 +223,13 @@ COLLECTIONS_PATHS:
 COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH:
   name: Defines behavior when loading a collection that does not support the current Ansible version
   description:
-  - When a collection is loaded that does not support the running Ansible version (via the collection metadata key
-    `requires_ansible`), the default behavior is to issue a warning and continue anyway. Setting this value to `ignore`
-    skips the warning entirely, while setting it to `error` will immediately halt Ansible execution.
+  - When a collection is loaded that does not support the running Ansible version (with the collection metadata key `requires_ansible`).
   env: [{name: ANSIBLE_COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH}]
   ini: [{key: collections_on_ansible_version_mismatch, section: defaults}]
-  choices: [error, warning, ignore]
+  choices: &basic_error
+    error: issue a 'fatal' error and stop the play
+    warning: issue a warning but continue
+    ignore: just continue silently
   default: warning
 _COLOR_DEFAULTS: &color
   name: placeholder for color settings' defaults
@@ -659,17 +660,16 @@ DEFAULT_GATHERING:
   default: 'implicit'
   description:
     - This setting controls the default policy of fact gathering (facts discovered about remote systems).
-    - "When 'implicit' (the default), the cache plugin will be ignored and facts will be gathered per play unless 'gather_facts: False' is set."
-    - "When 'explicit' the inverse is true, facts will not be gathered unless directly requested in the play."
-    - "The 'smart' value means each new host that has no facts discovered will be scanned,
-      but if the same host is addressed in multiple plays it will not be contacted again in the playbook run."
     - "This option can be useful for those wishing to save fact gathering time. Both 'smart' and 'explicit' will use the cache plugin."
   env: [{name: ANSIBLE_GATHERING}]
   ini:
     - key: gathering
       section: defaults
   version_added: "1.6"
-  choices: ['smart', 'explicit', 'implicit']
+  choices:
+    implicit: "the cache plugin will be ignored and facts will be gathered per play unless 'gather_facts: False' is set."
+    explicit: facts will not be gathered unless directly requested in the play.
+    smart: each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the run.
 DEFAULT_GATHER_SUBSET:
   name: Gather facts subset
   description:
@@ -1285,7 +1285,10 @@ DUPLICATE_YAML_DICT_KEY:
   ini:
   - {key: duplicate_dict_key, section: defaults}
   type: string
-  choices: ['warn', 'error', 'ignore']
+  choices: &basic_error2
+    error: issue a 'fatal' error and stop the play
+    warn: issue a warning but continue
+    ignore: just continue silently
   version_added: "2.9"
 ERROR_ON_MISSING_HANDLER:
   name: Missing handler error
@@ -1454,7 +1457,8 @@ HOST_PATTERN_MISMATCH:
   env: [{name: ANSIBLE_HOST_PATTERN_MISMATCH}]
   ini:
   - {key: host_pattern_mismatch, section: inventory}
-  choices: ['warning', 'error', 'ignore']
+  choices:
+    <<: *basic_error
   version_added: "2.8"
 INTERPRETER_PYTHON:
   name: Python interpreter path (or automatic discovery behavior) used for module execution
@@ -1516,15 +1520,15 @@ TRANSFORM_INVALID_GROUP_CHARS:
   default: 'never'
   description:
     - Make ansible transform invalid characters in group names supplied by inventory sources.
-    - If 'never' it will allow for the group name but warn about the issue.
-    - When 'ignore', it does the same as 'never', without issuing a warning.
-    - When 'always' it will replace any invalid characters with '_' (underscore) and warn the user
-    - When 'silently', it does the same as 'always', without issuing a warning.
   env: [{name: ANSIBLE_TRANSFORM_INVALID_GROUP_CHARS}]
   ini:
   - {key: force_valid_group_names, section: defaults}
   type: string
-  choices: ['always', 'never', 'ignore', 'silently']
+  choices:
+    always: it will replace any invalid characters with '_' (underscore) and warn the user
+    never: it will allow for the group name but warn about the issue
+    ignore: it does the same as 'never', without issuing a warning
+    silently: it does the same as 'always', without issuing a warning
   version_added: '2.8'
 INVALID_TASK_ATTRIBUTE_FAILED:
   name: Controls whether invalid attributes for a task result in errors instead of warnings
@@ -1774,13 +1778,13 @@ PLAYBOOK_VARS_ROOT:
   version_added: "2.4.1"
   description:
     - This sets which playbook dirs will be used as a root to process vars plugins, which includes finding host_vars/group_vars
-    - The ``top`` option follows the traditional behaviour of using the top playbook in the chain to find the root directory.
-    - The ``bottom`` option follows the 2.4.0 behaviour of using the current playbook to find the root directory.
-    - The ``all`` option examines from the first parent to the current playbook.
   env: [{name: ANSIBLE_PLAYBOOK_VARS_ROOT}]
   ini:
   - {key: playbook_vars_root, section: defaults}
-  choices: [ top, bottom, all ]
+  choices:
+    top: follows the traditional behavior of using the top playbook in the chain to find the root directory.
+    bottom: follows the 2.4.0 behavior of using the current playbook to find the root directory.
+    all: examines from the first parent to the current playbook.
 PLUGIN_FILTERS_CFG:
   name: Config file for limiting valid plugins
   default: null
@@ -1836,13 +1840,13 @@ RUN_VARS_PLUGINS:
   default: demand
   description:
     - This setting can be used to optimize vars_plugin usage depending on user's inventory size and play selection.
-    - Setting to C(demand) will run vars_plugins relative to inventory sources anytime vars are 'demanded' by tasks.
-    - Setting to C(start) will run vars_plugins relative to inventory sources after importing that inventory source.
   env: [{name: ANSIBLE_RUN_VARS_PLUGINS}]
   ini:
   - {key: run_vars_plugins, section: defaults}
   type: str
-  choices: ['demand', 'start']
+  choices:
+    demand: will run vars_plugins relative to inventory sources anytime vars are 'demanded' by tasks.
+    start: will run vars_plugins relative to inventory sources after importing that inventory source.
   version_added: "2.10"
 SHOW_CUSTOM_STATS:
   name: Display custom stats
diff --git a/lib/ansible/config/manager.py b/lib/ansible/config/manager.py
index fe56c063e8..c701baffd2 100644
--- a/lib/ansible/config/manager.py
+++ b/lib/ansible/config/manager.py
@@ -553,8 +553,18 @@ class ConfigManager(object):
                     invalid_choices = value not in defs[config]['choices']
 
                 if invalid_choices:
+
+                    if isinstance(defs[config]['choices'], Mapping):
+                        valid = ', '.join([to_text(k) for k in defs[config]['choices'].keys()])
+                    elif isinstance(defs[config]['choices'], string_types):
+                        valid = defs[config]['choices']
+                    elif isinstance(defs[config]['choices'], Sequence):
+                        valid = ', '.join([to_text(c) for c in defs[config]['choices']])
+                    else:
+                        valid = defs[config]['choices']
+
                     raise AnsibleOptionsError('Invalid value "%s" for configuration option "%s", valid values are: %s' %
-                                              (value, to_native(_get_entry(plugin_type, plugin_name, config)), defs[config]['choices']))
+                                              (value, to_native(_get_entry(plugin_type, plugin_name, config)), valid))
 
             # deal with deprecation of the setting
             if 'deprecated' in defs[config] and origin != 'default':