Deprecate hetzner_user and hetzner_pass parameters; deprecate hetzner_token not being required; deprecate membership of robot action group.

Author: felixfontein

changelogs/fragments/173-storagebox.yml

@@ -0,0 +1,4 @@
+deprecated_features:
+  - "storagebox* modules - the ``hetzner_user`` and ``hetzner_pass`` options for these modules are deprecated; support will be removed in community.hrobot 3.0.0. Use ``hetzner_token`` instead (https://github.com/ansible-collections/community.hrobot/pull/173)."
+  - "storagebox* modules - the ``hetzner_token`` option for these modules will be required from community.hrobot 3.0.0 on (https://github.com/ansible-collections/community.hrobot/pull/173)."
+  - "storagebox* modules - membership in the ``community.hrobot.robot`` action group (module defaults group) is deprecated; the modules will be removed from the group in community.hrobot 3.0.0. Use ``community.hrobot.api`` instead (https://github.com/ansible-collections/community.hrobot/pull/173)."

plugins/doc_fragments/api.py

@@ -47,3 +47,27 @@ class ModuleDocFragment(object):
       - If O(hetzner_password) is specified, O(hetzner_user) must also be specified, and O(hetzner_token) must not be specified.
     required: false
 """
+
+    # Only for transition period
+    _ROBOT_COMPAT_SHIM_DEPRECATION = r"""
+options:
+  hetzner_token:
+    description:
+      - The API token for the Robot web-service user.
+      - One of O(hetzner_token) and O(hetzner_user) must be specified.
+      - This option will be required from community.hrobot 3.0.0 on.
+    required: false
+  hetzner_user:
+    description:
+      - The username for the Robot web-service user.
+      - One of O(hetzner_token) and O(hetzner_user) must be specified.
+      - If O(hetzner_user) is specified, O(hetzner_password) must also be specified, and O(hetzner_token) must not be specified.
+      - This option is deprecated for this module, and support will be removed in community.hrobot 3.0.0.
+    required: false
+  hetzner_password:
+    description:
+      - The password for the Robot web-service user.
+      - If O(hetzner_password) is specified, O(hetzner_user) must also be specified, and O(hetzner_token) must not be specified.
+      - This option is deprecated for this module, and support will be removed in community.hrobot 3.0.0.
+    required: false
+"""

plugins/doc_fragments/attributes.py

@@ -80,6 +80,20 @@ class ModuleDocFragment(object):
       - community.hrobot.robot
 '''
 
+    # Only for transition period
+    _ACTIONGROUP_ROBOT_AND_API_DEPRECATION = r'''
+options: {}
+attributes:
+  action_group:
+    description:
+      - Use C(group/community.hrobot.robot) or C(group/community.hrobot.api) in C(module_defaults) to set defaults for this module.
+      - The C(group/community.hrobot.robot) group is B(deprecated) for this module; the module will be removed from the group in community.hrobot 3.0.0.
+    support: full
+    membership:
+      - community.hrobot.api
+      - community.hrobot.robot
+'''
+
     CONN = r"""
 options: {}
 attributes:

plugins/module_utils/robot.py

@@ -33,6 +33,12 @@
     hetzner_password=dict(type='str', required=False, no_log=True),
 )
 
+_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED = dict(
+    hetzner_user=dict(type='str', required=False, removed_in_version="3.0.0", removed_from_collection="community.hrobot"),
+    hetzner_password=dict(type='str', required=False, no_log=True, removed_in_version="3.0.0", removed_from_collection="community.hrobot"),
+)
+
+
 # The API endpoint is fixed.
 BASE_URL = "https://robot-ws.your-server.de"
 

plugins/modules/storagebox.py

@@ -18,11 +18,11 @@
 description:
   - Modify a storage box's basic configuration.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
 attributes:
@@ -126,7 +126,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -199,7 +199,7 @@ def main():
         zfs=dict(type='bool'),
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
     module = AnsibleModule(
@@ -215,6 +215,12 @@ def main():
     after = {}
     changes = {}
 
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}".format(BASE_URL, storagebox_id)

plugins/modules/storagebox_info.py

@@ -18,11 +18,11 @@
 description:
   - Query information on one or more storage box.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
   - community.hrobot.attributes.idempotent_not_modify_state
@@ -521,7 +521,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -571,7 +571,7 @@ def main():
         full_info=dict(type='bool', default=False),
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
     module = AnsibleModule(
@@ -587,6 +587,12 @@ def main():
     full_info = module.params['full_info']
 
     storageboxes = []
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
         if storagebox_id is not None:

plugins/modules/storagebox_set_password.py

@@ -17,11 +17,11 @@
 description:
   - (Re)set the password for a storage box.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
 
@@ -85,7 +85,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -110,7 +110,7 @@ def main():
         password=dict(type="str", no_log=True),
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
     module = AnsibleModule(
@@ -122,6 +122,12 @@ def main():
     id = module.params["id"]
     password = module.params.get("password")
 
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}/password".format(BASE_URL, id)

plugins/modules/storagebox_snapshot.py

@@ -18,11 +18,11 @@
 description:
   - Create, update comment, or delete a snapshot of a storage box.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
 attributes:
@@ -108,7 +108,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -157,7 +157,7 @@ def main():
         snapshot_comment=dict(type='str')
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
 
@@ -172,6 +172,12 @@ def main():
     snapshot_name = module.params['snapshot_name']
     snapshot_comment = module.params['snapshot_comment']
 
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
 

plugins/modules/storagebox_snapshot_info.py

@@ -18,11 +18,11 @@
 description:
   - Query the snapshots for a storage box.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
   - community.hrobot.attributes.idempotent_not_modify_state
@@ -167,7 +167,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -194,7 +194,7 @@ def main():
         storagebox_id=dict(type='int', required=True),
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
     module = AnsibleModule(
@@ -204,6 +204,12 @@ def main():
 
     storagebox_id = module.params['storagebox_id']
 
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}/snapshot".format(BASE_URL, storagebox_id)

plugins/modules/storagebox_snapshot_plan.py

@@ -18,11 +18,11 @@
 description:
   - Enable, modify, and disable the snapshot plans of a storage box.
 extends_documentation_fragment:
-  - community.hrobot.api._robot_compat_shim  # must come before api and robot
+  - community.hrobot.api._robot_compat_shim_deprecation  # must come before api and robot
   - community.hrobot.api
   - community.hrobot.robot
   - community.hrobot.attributes
-  - community.hrobot.attributes._actiongroup_robot_and_api  # must come before the other two!
+  - community.hrobot.attributes._actiongroup_robot_and_api_deprecation  # must come before the other two!
   - community.hrobot.attributes.actiongroup_api
   - community.hrobot.attributes.actiongroup_robot
 attributes:
@@ -171,7 +171,7 @@
 from ansible_collections.community.hrobot.plugins.module_utils.robot import (
     BASE_URL,
     ROBOT_DEFAULT_ARGUMENT_SPEC,
-    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT,
+    _ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED,
     fetch_url_json,
 )
 
@@ -254,7 +254,7 @@ def main():
         ),
     )
     argument_spec.update(ROBOT_DEFAULT_ARGUMENT_SPEC)
-    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT)
+    argument_spec.update(_ROBOT_DEFAULT_ARGUMENT_SPEC_COMPAT_DEPRECATED)
     argument_spec.update(API_DEFAULT_ARGUMENT_SPEC)
     argument_spec.update(_API_DEFAULT_ARGUMENT_SPEC_COMPAT)
     module = AnsibleModule(
@@ -270,6 +270,12 @@ def main():
         module.fail_json(msg='`plans` must have exactly one element')
     plan = plans[0]
 
+    if module.params["hetzner_token"] is None:
+        module.deprecate(
+            "The hetzner_token parameter will be required from community.hrobot 3.0.0 on.",
+            collection_name="community.hrobot",
+            version="3.0.0",
+        )
     if module.params["hetzner_user"] is not None:
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}/snapshotplan".format(BASE_URL, storagebox_id)