Warn on incorrect use of parameter, and remove fix for now (#54336)

* Fix wrong example, remove strictness and fix tests

It was obvious that (because of an incorrect example) people were using
the **xml** module incorrectly, specifying the `attribute` parameter
where it was not supported (i.e. ignored).

While this functionality would have been useful, it currently returns as
if the information was requested from the parent, so we cannot simply
make it to what would be expected.

Therefor the real solution is to provide a warning when we find
incorrect use, and deprecate this use. Then later we could implement
this functionality correctly.

While troubleshooting this issue, I found that in some cases our
integration tests were not being run when we expected it.

This fixes #53459

* Change warning

* Fix weird sanity test error

* Add a comment to the deprecate-test

lib/ansible/modules/files/xml.py

@@ -251,15 +251,14 @@ EXAMPLES = r'''
     value: 1976-08-05
 
 # How to read an attribute value and access it in Ansible
-- name: Read attribute value
+- name: Read an element's attribute values
   xml:
     path: /foo/bar.xml
     xpath: /business/website/validxhtml
     content: attribute
-    attribute: validatedon
   register: xmlresp
 
-- name: Show attribute value
+- name: Show an attribute value
   debug:
     var: xmlresp.matches[0].validxhtml.validatedon
 
@@ -833,7 +832,8 @@ def main():
         supports_check_mode=True,
         required_by=dict(
             add_children=['xpath'],
-            attribute=['value'],
+            # TODO: Reinstate this in Ansible v2.12 when we have deprecated the incorrect use below
+            # attribute=['value'],
             content=['xpath'],
             set_children=['xpath'],
             value=['xpath'],
@@ -882,6 +882,11 @@ def main():
     elif LooseVersion('.'.join(to_native(f) for f in etree.LXML_VERSION)) < LooseVersion('3.0.0'):
         module.warn('Using lxml version lower than 3.0.0 does not guarantee predictable element attribute order.')
 
+    # Report wrongly used attribute parameter when using content=attribute
+    # TODO: Remove this in Ansible v2.12 (and reinstate strict parameter test above) and remove the integration test example
+    if content == 'attribute' and attribute is not None:
+        module.deprecate("Parameter 'attribute=%s' is ignored when using 'content=attribute' only 'xpath' is used. Please remove entry." % attribute, '2.12')
+
     # Check if the file exists
     if xml_string:
         infile = BytesIO(to_bytes(xml_string, errors='surrogate_or_strict'))

test/integration/targets/xml/tasks/test-get-element-content.yml

@@ -16,7 +16,27 @@
     assert:
       that:
       - get_element_attribute.changed == false
-      - get_element_attribute.matches[0]['rating'] is defined and get_element_attribute.matches[0]['rating']['subjective'] == 'true'
+      - get_element_attribute.matches[0]['rating'] is defined
+      - get_element_attribute.matches[0]['rating']['subjective'] == 'true'
+
+  # TODO: Remove this in Ansible v2.12 when this incorrect use of attribute is deprecated
+  - name: Get element attributes
+    xml:
+      path: /tmp/ansible-xml-beers.xml
+      xpath: /business/rating
+      content: attribute
+      attribute: subjective
+    register: get_element_attribute_wrong
+
+  - name: Test expected result
+    assert:
+      that:
+      - get_element_attribute_wrong.changed == false
+      - get_element_attribute_wrong.matches[0]['rating'] is defined
+      - get_element_attribute_wrong.matches[0]['rating']['subjective'] == 'true'
+      - get_element_attribute_wrong.deprecations is defined
+      - get_element_attribute_wrong.deprecations[0].msg == "Parameter 'attribute=subjective' is ignored when using 'content=attribute' only 'xpath' is used. Please remove entry."
+      - get_element_attribute_wrong.deprecations[0].version == '2.12'
 
   - name: Get element text
     xml: