actually show plugin config warnings/deprecations

previouslly we recorded but did not show to avoid spam since we could not dedup from forks, that was already fixed in another PR so now we can show/display them. Also: * funcitonalize deprecation msg construct from docs * reuse formatting func in cli * normalize alternatives: most of the code used intended plural but some and most data/tests used the singular
ansible · Feb 1, 2024 · 7824434 · 7824434
1 parent e458cba
commit 7824434
Show file tree

Hide file tree

Showing 21 changed files with 81 additions and 47 deletions.
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
@@ -1350,16 +1350,13 @@ def get_man_text(doc, collection_name='', plugin_type=''):
         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']
+                text.append('\t' + C.config.get_deprecated_msg_from_config(doc['deprecated'], True))
             else:
-                text.append("%s" % doc.pop('deprecated'))
+                text.append("%s" % doc['deprecated'])
+            del doc['deprecated']
+            text.append("\n")
 
         if doc.pop('has_action', False):
             text.append("")

diff --git a/lib/ansible/config/manager.py b/lib/ansible/config/manager.py
@@ -606,3 +606,17 @@ def initialize_plugin_configuration_definitions(self, plugin_type, name, defs):
             self._plugins[plugin_type] = {}
 
         self._plugins[plugin_type][name] = defs
+
+    @staticmethod
+    def get_deprecated_msg_from_config(dep_docs, include_removal=False):
+
+        removal = ''
+        if include_removal:
+            if 'removed_at_date' in dep_docs:
+                removal = "Will be removed in a release after %(removed_at_date)s\n\t"
+            else:
+                removal = "Will be removed in: Ansible %(removed_in)s\n\t"
+
+        msg = "Reason: %(why)s\n\t" + removal + "Alternatives: %(alternatives)s"
+
+        return msg % dep_docs
diff --git a/lib/ansible/constants.py b/lib/ansible/constants.py
@@ -15,6 +15,10 @@
 from ansible.release import __version__
 from ansible.utils.fqcn import add_internal_fqcns
 
+# initialize config manager/config data to read/store global settings
+# and generate 'pseudo constants' for app consumption.
+config = ConfigManager()
+
 
 def _warning(msg):
     ''' display is not guaranteed here, nor it being the full class, but try anyways, fallback to sys.stderr.write '''
@@ -36,6 +40,26 @@ def _deprecated(msg, version):
         sys.stderr.write(' [DEPRECATED] %s, to be removed in %s\n' % (msg, version))
 
 
+def handle_config_noise(display=None):
+
+    if display is not None:
+        w = display.warning
+        d = display.deprecated
+    else:
+        w = _warning
+        d = _deprecated
+
+    while config.WARNINGS:
+        warn = config.WARNINGS.pop()
+        w(warn)
+
+    while config.DEPRECATED:
+        # tuple with name and options
+        dep = config.DEPRECATED.pop()
+        msg = config.get_deprecated_msg_from_config(dep[1])
+        d(msg, version=dep[1]['version'])
+
+
 def set_constant(name, value, export=vars()):
     ''' sets constants and returns resolved options dict '''
     export[name] = value
@@ -178,11 +202,8 @@ def __getitem__(self, y):
 )
 
 # POPULATE SETTINGS FROM CONFIG ###
-config = ConfigManager()
-
-# Generate constants from config
 for setting in config.get_configuration_definitions():
     set_constant(setting, config.get_config_value(setting, variables=vars()))
 
-for warn in config.WARNINGS:
-    _warning(warn)
+# emit any warnings or deprecations
+handle_config_noise()
diff --git a/lib/ansible/plugins/__init__.py b/lib/ansible/plugins/__init__.py
@@ -92,6 +92,7 @@ def get_options(self, hostvars=None):
 
     def set_option(self, option, value):
         self._options[option] = C.config.get_config_value(option, plugin_type=self.plugin_type, plugin_name=self._load_name, direct={option: value})
+        C.handle_config_noise(display)
 
     def set_options(self, task_keys=None, var_options=None, direct=None):
         '''
@@ -108,6 +109,7 @@ def set_options(self, task_keys=None, var_options=None, direct=None):
         if self.allow_extras and var_options and '_extras' in var_options:
             # these are largely unvalidated passthroughs, either plugin or underlying API will validate
             self._options['_extras'] = var_options['_extras']
+        C.handle_config_noise(display)
 
     def has_option(self, option):
         if not self._options:

diff --git a/...c/broken-docs/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py b/...c/broken-docs/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py
@@ -23,7 +23,7 @@
           - key: fact_caching_connection
             section: defaults
             deprecated:
-              alternative: none
+              alternatives: none
               why: Test deprecation
               version: '2.0.0'
       _prefix:
@@ -35,7 +35,7 @@
           - key: fact_caching_prefix
             section: defaults
         deprecated:
-          alternative: none
+          alternatives: none
           why: Another test deprecation
           removed_at_date: '2050-01-01'
       _timeout:
@@ -50,7 +50,7 @@
           - name: notsjonfile_fact_caching_timeout
             version_added: 1.5.0
             deprecated:
-              alternative: do not use a variable
+              alternatives: do not use a variable
               why: Test deprecation
               version: '3.0.0'
         type: integer

diff --git a/...ble-doc/broken-docs/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py b/...ble-doc/broken-docs/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py
@@ -12,7 +12,7 @@
     description:
       - this is a noop
     deprecated:
-        alternative: Use some other lookup
+        alternatives: Use some other lookup
         why: Test deprecation
         removed_in: '3.0.0'
     extends_documentation_fragment:

diff --git a/...roken-docs/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py b/...roken-docs/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py
@@ -12,7 +12,7 @@
     - Ansible Core Team
 version_added: 1.0.0
 deprecated:
-    alternative: Use some other module
+    alternatives: Use some other module
     why: Test deprecation
     removed_in: '3.0.0'
 options:
@@ -41,7 +41,7 @@
             - name: TEST_ENV
               version_added: 1.0.0
               deprecated:
-                alternative: none
+                alternatives: none
                 why: Test deprecation
                 removed_in: '2.0.0'
                 version: '2.0.0'

diff --git a/...s/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py b/...s/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py
@@ -22,7 +22,7 @@
           - key: fact_caching_connection
             section: defaults
             deprecated:
-              alternative: none
+              alternatives: none
               why: Test deprecation
               version: '2.0.0'
       _prefix:
@@ -34,7 +34,7 @@
           - key: fact_caching_prefix
             section: defaults
         deprecated:
-          alternative: none
+          alternatives: none
           why: Another test deprecation
           removed_at_date: '2050-01-01'
       _timeout:
@@ -49,7 +49,7 @@
           - name: notsjonfile_fact_caching_timeout
             version_added: 1.5.0
             deprecated:
-              alternative: do not use a variable
+              alternatives: do not use a variable
               why: Test deprecation
               version: '3.0.0'
         type: integer

diff --git a/...targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py b/...targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py
@@ -11,7 +11,7 @@
     description:
       - this is a noop
     deprecated:
-        alternative: Use some other lookup
+        alternatives: Use some other lookup
         why: Test deprecation
         removed_in: '3.0.0'
     extends_documentation_fragment:

diff --git a/...nsible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py b/...nsible-doc/collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py
@@ -17,7 +17,7 @@
     - Ansible Core Team
 version_added: 1.0.0
 deprecated:
-    alternative: Use some other module
+    alternatives: Use some other module
     why: Test deprecation
     removed_in: '3.0.0'
 options:
@@ -46,7 +46,7 @@
             - name: TEST_ENV
               version_added: 1.0.0
               deprecated:
-                alternative: none
+                alternatives: none
                 why: Test deprecation
                 removed_in: '2.0.0'
                 version: '2.0.0'

diff --git a/...-doc/collections/ansible_collections/testns/testcol2/plugins/doc_fragments/deprecation.py b/...-doc/collections/ansible_collections/testns/testcol2/plugins/doc_fragments/deprecation.py
@@ -9,7 +9,7 @@ class ModuleDocFragment(object):
     DOCUMENTATION = r'''
 options: {}
 deprecated:
-    alternative: Use some other module
+    alternatives: Use some other module
     why: Test deprecation
     removed_in: '3.0.0'
 '''
diff --git a/...sible-doc/collections/ansible_collections/testns/testcol2/plugins/doc_fragments/plugin.py b/...sible-doc/collections/ansible_collections/testns/testcol2/plugins/doc_fragments/plugin.py
@@ -18,29 +18,29 @@ class ModuleDocFragment(object):
               section: bar
               version_added: 1.1.0
               deprecated:
-                alternative: none
+                alternatives: none
                 why: Test deprecation
                 version: '3.0.0'
         env:
             - name: FOO_BAR
               version_added: 1.2.0
               deprecated:
-                alternative: none
+                alternatives: none
                 why: Test deprecation
                 removed_at_date: 2020-01-31
         vars:
             - name: foobar
               version_added: 1.3.0
               deprecated:
-                alternative: none
+                alternatives: none
                 why: Test deprecation
                 removed_at_date: 2040-12-31
     testcol2depr:
         description:
             - A plugin option taken from testcol2 that is deprecated
         type: str
         deprecated:
-            alternative: none
+            alternatives: none
             why: Test option deprecation
             version: '2.0.0'
 '''
diff --git a/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py b/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py
@@ -11,7 +11,7 @@
 author:
     - Ansible Core Team
 deprecated:
-  alternative: new_module
+  alternatives: new_module
   why: Updated module released with more functionality
   removed_at_date: '2022-06-01'
   removed_in: '2.14'

diff --git a/test/integration/targets/ansible-doc/lookup_plugins/_deprecated_with_docs.py b/test/integration/targets/ansible-doc/lookup_plugins/_deprecated_with_docs.py
@@ -12,7 +12,7 @@
     version_added: "2.14"
     deprecated:
         why: reasons
-        alternative: other thing
+        alternatives: other thing
         removed_in: "2.16"
         removed_from_collection: "ansible.legacy"
     options: {}

diff --git a/test/integration/targets/ansible-doc/lookup_plugins/deprecated_with_adj_docs.yml b/test/integration/targets/ansible-doc/lookup_plugins/deprecated_with_adj_docs.yml
@@ -6,7 +6,7 @@ DOCUMENTATION:
   version_added: "2.14"
   deprecated:
     why: reasons
-    alternative: use other thing
+    alternatives: use other thing
     removed_in: "2.16"
     removed_from_collection: "ansible.legacy"
   options: {}

diff --git a/test/integration/targets/ansible-doc/noop.output b/test/integration/targets/ansible-doc/noop.output
@@ -4,7 +4,7 @@
             "author": "Ansible core team",
             "collection": "testns.testcol",
             "deprecated": {
-                "alternative": "Use some other lookup",
+                "alternatives": "Use some other lookup",
                 "removed_from_collection": "testns.testcol",
                 "removed_in": "3.0.0",
                 "why": "Test deprecation"

diff --git a/test/integration/targets/ansible-doc/noop_vars_plugin.output b/test/integration/targets/ansible-doc/noop_vars_plugin.output
@@ -3,7 +3,7 @@
         "doc": {
             "collection": "testns.testcol",
             "deprecated": {
-                "alternative": "Use some other module",
+                "alternatives": "Use some other module",
                 "removed_from_collection": "testns.testcol2",
                 "removed_in": "3.0.0",
                 "why": "Test deprecation"

diff --git a/test/integration/targets/ansible-doc/notjsonfile.output b/test/integration/targets/ansible-doc/notjsonfile.output
@@ -11,7 +11,7 @@
             "options": {
                 "_prefix": {
                     "deprecated": {
-                        "alternative": "none",
+                        "alternatives": "none",
                         "collection_name": "testns.testcol",
                         "removed_at_date": "2050-01-01",
                         "why": "Another test deprecation"
@@ -49,7 +49,7 @@
                     "vars": [
                         {
                             "deprecated": {
-                                "alternative": "do not use a variable",
+                                "alternatives": "do not use a variable",
                                 "collection_name": "testns.testcol",
                                 "version": "3.0.0",
                                 "why": "Test deprecation"
@@ -74,7 +74,7 @@
                     "ini": [
                         {
                             "deprecated": {
-                                "alternative": "none",
+                                "alternatives": "none",
                                 "collection_name": "testns.testcol",
                                 "version": "2.0.0",
                                 "why": "Test deprecation"
@@ -87,7 +87,7 @@
                 },
                 "testcol2depr": {
                     "deprecated": {
-                        "alternative": "none",
+                        "alternatives": "none",
                         "collection_name": "testns.testcol2",
                         "version": "2.0.0",
                         "why": "Test option deprecation"
@@ -104,7 +104,7 @@
                     "env": [
                         {
                             "deprecated": {
-                                "alternative": "none",
+                                "alternatives": "none",
                                 "collection_name": "testns.testcol2",
                                 "removed_at_date": "2020-01-31",
                                 "why": "Test deprecation"
@@ -117,7 +117,7 @@
                     "ini": [
                         {
                             "deprecated": {
-                                "alternative": "none",
+                                "alternatives": "none",
                                 "collection_name": "testns.testcol2",
                                 "version": "3.0.0",
                                 "why": "Test deprecation"
@@ -132,7 +132,7 @@
                     "vars": [
                         {
                             "deprecated": {
-                                "alternative": "none",
+                                "alternatives": "none",
                                 "collection_name": "testns.testcol2",
                                 "removed_at_date": "2040-12-31",
                                 "why": "Test deprecation"

diff --git a/test/integration/targets/ansible-doc/randommodule-text-verbose.output b/test/integration/targets/ansible-doc/randommodule-text-verbose.output
@@ -14,7 +14,7 @@ OPTIONS (= inicates it is required):
           env:
           - added_in: version 1.0.0 of ansible-core
             deprecated:
-              alternative: none
+              alternatives: none
               removed_in: 2.0.0
               version: 2.0.0
               why: Test deprecation

diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output
@@ -20,7 +20,7 @@ OPTIONS (= inicates it is required):
         set_via:
           env:
           - deprecated:
-              alternative: none
+              alternatives: none
               removed_in: 2.0.0
               version: 2.0.0
               why: Test deprecation