Deprecate returning orders when retrieve_orders=url_list. (#178)

This allows to get rid of the ignore.txt entries for the return value syntax
error since then orders will always have the same type when returned.

changelogs/fragments/178-acme_account_info-orders-urls.yml

@@ -0,0 +1,4 @@
+minor_changes:
+- "acme_account_info - when ``retrieve_orders`` is not ``ignore`` and the ACME server allows to query orders, the new return value ``order_uris`` is always populated with a list of URIs (https://github.com/ansible-collections/community.crypto/pull/178)."
+deprecated_features:
+- "acme_account_info - when ``retrieve_orders=url_list``, ``orders`` will no longer be returned in community.crypto 2.0.0. Use ``order_uris`` instead (https://github.com/ansible-collections/community.crypto/pull/178)."

plugins/modules/acme_account_info.py

@@ -30,6 +30,10 @@ options:
       - "Whether to retrieve the list of order URLs or order objects, if provided
          by the ACME server."
       - "A value of C(ignore) will not fetch the list of orders."
+      - "If the value is not C(ignore) and the ACME server supports orders, the C(order_uris)
+         return value is always populated. The C(orders) return value currently depends on
+         whether this option is set to C(url_list) or C(object_list). In community.crypto 2.0.0,
+         it will only be returned if this option is set to C(object_list)."
       - "Currently, Let's Encrypt does not return orders, so the C(orders) result
          will always be empty."
     type: str
@@ -121,7 +125,8 @@ account:
 orders:
   description:
     - "The list of orders."
-    - "If I(retrieve_orders) is C(url_list), this will be a list of URLs."
+    - "If I(retrieve_orders) is C(url_list), this will be a list of URLs. In community.crypto 2.0.0,
+       this return value will no longer be returned for C(url_list)."
     - "If I(retrieve_orders) is C(object_list), this will be a list of objects."
   type: list
   #elements: ... depends on retrieve_orders
@@ -194,6 +199,16 @@ orders:
         - The URL for retrieving the certificate.
       type: str
       returned: when certificate was issued
+
+order_uris:
+  description:
+    - "The list of orders."
+    - "If I(retrieve_orders) is C(url_list), this will be a list of URLs."
+    - "If I(retrieve_orders) is C(object_list), this will be a list of objects."
+  type: list
+  elements: str
+  returned: if account exists, I(retrieve_orders) is not C(ignore), and server supports order listing
+  version_added: 1.5.0
 '''
 
 from ansible.module_utils.basic import AnsibleModule
@@ -288,9 +303,15 @@ def main():
             # Retrieve orders list
             if account_data.get('orders') and module.params['retrieve_orders'] != 'ignore':
                 orders = get_orders_list(module, account, account_data['orders'])
+                result['order_uris'] = orders
                 if module.params['retrieve_orders'] == 'url_list':
+                    module.deprecate(
+                        'retrieve_orders=url_list now returns the order URI list as `order_uris`.'
+                        ' Right now it also returns this list as `orders` for backwards compatibility,'
+                        ' but this will stop in community.crypto 2.0.0',
+                        version='2.0.0', collection_name='community.crypto')
                     result['orders'] = orders
-                else:
+                if module.params['retrieve_orders'] == 'object_list':
                     result['orders'] = [get_order(account, order) for order in orders]
         module.exit_json(**result)
     except ModuleFailException as e:

tests/integration/targets/acme_certificate/tests/validate.yml

@@ -121,6 +121,9 @@
       - "'account' in account_orders_urls"
       - "'orders' in account_orders_urls"
       - "account_orders_urls.orders[0] is string"
+      - "'order_uris' in account_orders_urls"
+      - "account_orders_urls.order_uris[0] is string"
+      - "account_orders_urls.order_uris == account_orders_urls.orders"
 
 - name: Validate that orders were retrieved as list of URLs (2/2)
   assert:
@@ -128,6 +131,9 @@
       - "'account' in account_orders_urls2"
       - "'orders' in account_orders_urls2"
       - "account_orders_urls2.orders[0] is string"
+      - "'order_uris' in account_orders_urls2"
+      - "account_orders_urls2.order_uris[0] is string"
+      - "account_orders_urls2.order_uris == account_orders_urls2.orders"
 
 - name: Validate that orders were retrieved as list of objects (1/2)
   assert:
@@ -135,6 +141,8 @@
       - "'account' in account_orders_full"
       - "'orders' in account_orders_full"
       - "account_orders_full.orders[0].status is string"
+      - "'order_uris' in account_orders_full"
+      - "account_orders_full.order_uris[0] is string"
 
 - name: Validate that orders were retrieved as list of objects (2/2)
   assert:
@@ -142,3 +150,5 @@
       - "'account' in account_orders_full2"
       - "'orders' in account_orders_full2"
       - "account_orders_full2.orders[0].status is string"
+      - "'order_uris' in account_orders_full2"
+      - "account_orders_full2.order_uris[0] is string"