Storagebox: deprecate hetzner_user, deprecate compatibility shim return values (#178)

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

* Add new rate limiting tests.

* Deprecate old return values.

* Work around bug in ansible-test's pylint check.

Ref: ansible/ansible#85614

Author: felixfontein

changelogs/fragments/178-storagebox.yml

@@ -0,0 +1,10 @@
+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/178)."
+  - "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/178)."
+  - "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/178)."
+  - "storagebox_info - the ``storageboxes[].login``, ``storageboxes[].disk_quota``, ``storageboxes[].disk_usage``, ``storageboxes[].disk_usage_data``, ``storageboxes[].disk_usage_snapshot``, ``storageboxes[].webdav``, ``storageboxes[].samba``, ``storageboxes[].ssh``, ``storageboxes[].external_reachability``, and ``storageboxes[].zfs`` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178)."
+  - "storagebox_snapshot_info - the ``snapshots[].timestamp``, ``snapshots[].size``, ``snapshots[].filesystem_size``, ``snapshots[].automatic``, and ``snapshots[].comment`` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178)."
+  - "storagebox_snapshot_plan - the ``plans[].month`` return value is deprecated, since it only returns ``null`` with the new API and cannot be set to any other value (https://github.com/ansible-collections/community.hrobot/pull/178)."
+  - "storagebox_snapshot_plan_info - the ``plans[].month`` return value is deprecated, since it only returns ``null`` with the new API and cannot be set to any other value (https://github.com/ansible-collections/community.hrobot/pull/178)."
+  - "storagebox_subaccount - the ``subaccount.homedirectory``, ``subaccount.samba``, ``subaccount.ssh``, ``subaccount.external_reachability``, ``subaccount.webdav``, ``subaccount.readonly``, ``subaccount.createtime``, and ``subaccount.comment`` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178)."
+  - "storagebox_subaccount_info - the ``subaccounts[].accountid``, ``subaccounts[].homedirectory``, ``subaccounts[].samba``, ``subaccounts[].ssh``, ``subaccounts[].external_reachability``, ``subaccounts[].webdav``, ``subaccounts[].readonly``, ``subaccounts[].createtime``, and ``subaccounts[].comment`` return values are deprecated and will be removed from community.routeros. Check out the documentation to find out their new names according to the new API (https://github.com/ansible-collections/community.hrobot/pull/178)."

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/_tagging.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2025 Felix Fontein <[email protected]>
+# This code is licensed under the following two licenses:
+# - Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
+# - GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: BSD-2-Clause OR GPL-3.0-or-later
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+try:
+    from ansible.module_utils.datatag import deprecate_value as _deprecate_value
+    HAS_DEPRECATE_VALUE = True
+except ImportError:
+    HAS_DEPRECATE_VALUE = False
+
+
+def deprecate_value(value, msg, version, help_text=None):
+    """
+    Given a value, tag it as deprecated (with message, removal version, and optional help text).
+
+    For ansible-core versions that do not support data tagging, simply returns the value as-is.
+    """
+    if not HAS_DEPRECATE_VALUE:
+        return value
+    # Assign this to a variable to work around a bug in ansible-test's pylint check (https://github.com/ansible/ansible/issues/85614)
+    collection_name = "community.hrobot"
+    return _deprecate_value(
+        value,
+        msg,
+        collection_name=collection_name,
+        version=version,
+        help_text=help_text,
+    )

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(
@@ -216,6 +216,11 @@ def main():
     changes = {}
 
     if module.params["hetzner_user"] is not 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",
+        )
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}".format(BASE_URL, storagebox_id)
         result, error = fetch_url_json(module, url, accept_errors=['STORAGEBOX_NOT_FOUND'])

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
@@ -88,6 +88,8 @@
       description:
         - The storage box's login name.
         - Note that this is copied from RV(storageboxes[].username) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: str
       sample: u12345
       returned: success
@@ -200,62 +202,80 @@
       description:
         - Total amount of MB available.
         - Note that this is copied from RV(storageboxes[].storage_box_type.size) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: int
       sample: 10240000
       returned: when O(full_info=true), or O(hetzner_token) is specified
     disk_usage:
       description:
         - The amount of MB in use.
         - Note that this is copied from RV(storageboxes[].stats.size) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: int
       sample: 900
       returned: when O(full_info=true), or O(hetzner_token) is specified
     disk_usage_data:
       description:
         - The amount of MB used by files.
         - Note that this is copied from RV(storageboxes[].stats.size_data) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: int
       sample: 500
       returned: when O(full_info=true), or O(hetzner_token) is specified
     disk_usage_snapshots:
       description:
         - The amount of MB used by snapshots.
         - Note that this is copied from RV(storageboxes[].stats.size_snapshots) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: int
       sample: 400
       returned: when O(full_info=true), or O(hetzner_token) is specified
     webdav:
       description:
         - Whether WebDAV is active.
         - Note that this is copied from RV(storageboxes[].access_settings.webdav_enabled) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: bool
       sample: true
       returned: when O(full_info=true), or O(hetzner_token) is specified
     samba:
       description:
         - Whether SAMBA is active.
         - Note that this is copied from RV(storageboxes[].access_settings.samba_enabled) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: bool
       sample: true
       returned: when O(full_info=true), or O(hetzner_token) is specified
     ssh:
       description:
         - Whether SSH is active.
         - Note that this is copied from RV(storageboxes[].access_settings.ssh_enabled) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: bool
       sample: true
       returned: when O(full_info=true), or O(hetzner_token) is specified
     external_reachability:
       description:
         - Whether the storage box is reachable externally.
         - Note that this is copied from RV(storageboxes[].access_settings.reachable_externally) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: bool
       sample: true
       returned: when O(full_info=true), or O(hetzner_token) is specified
     zfs:
       description:
         - Shows whether the ZFS directory is visible.
         - Note that this is copied from RV(storageboxes[].access_settings.zfs_enabled) in case O(hetzner_token) is specified.
+        - B(This return value is deprecated and will be removed from community.hrobot 3.0.0.)
+          If you are using ansible-core 2.19 or newer, you will see a deprecation message when using this return value when using O(hetzner_token).
       type: bool
       sample: false
       returned: when O(full_info=true), or O(hetzner_token) is specified
@@ -521,7 +541,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,
 )
 
@@ -533,6 +553,10 @@
     api_fetch_url_json_list,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 try:
     from urllib.parse import urlencode
 except ImportError:
@@ -560,7 +584,11 @@ def add_hrobot_compat_shim(storagebox):
         value = storagebox
         for src in source:
             value = value[src]
-        result[dest] = value
+        result[dest] = deprecate_value(
+            value,
+            "The return value `{0}` is deprecated; use `{1}` instead.".format(dest, ".".join(source)),
+            version="3.0.0",
+        )
     return result
 
 
@@ -571,7 +599,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(
@@ -588,6 +616,11 @@ def main():
 
     storageboxes = []
     if module.params["hetzner_user"] is not 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",
+        )
         # DEPRECATED: old API
         if storagebox_id is not None:
             storagebox_ids = [storagebox_id]

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(
@@ -123,6 +123,11 @@ def main():
     password = module.params.get("password")
 
     if module.params["hetzner_user"] is not 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",
+        )
         # DEPRECATED: old API
         url = "{0}/storagebox/{1}/password".format(BASE_URL, id)
         accepted_errors = ["STORAGEBOX_NOT_FOUND", "STORAGEBOX_INVALID_PASSWORD"]