Deprecate old return values.

Author: felixfontein

changelogs/fragments/173-storagebox.yml

@@ -2,5 +2,11 @@ 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)."
+  - "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/173)."
+  - "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/173)."
+  - "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/173)."
+  - "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/173)."
+  - "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/173)."
+  - "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/173)."
 minor_changes:
   - "storagebox* modules - the code for the old API (that has been removed by Hetzner) has been replaced by hard-coding the result of the API, namely that no storagebox of this ID exists (https://github.com/ansible-collections/community.hrobot/pull/173)."

plugins/module_utils/_tagging.py

@@ -0,0 +1,37 @@
+# -*- 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
+    return _deprecate_value(
+        value,
+        msg,
+        collection_name="community.hrobot",
+        version=version,
+        help_text=help_text,
+    )

plugins/modules/storagebox_info.py

@@ -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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       type: bool
       sample: false
       returned: when O(full_info=true), or O(hetzner_token) is specified
@@ -531,6 +551,10 @@
     api_fetch_url_json_list,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 
 _CONVERT = {
     "login": ["username"],
@@ -552,7 +576,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
 
 

plugins/modules/storagebox_snapshot_info.py

@@ -71,34 +71,44 @@
       description:
         - The timestamp of snapshot in UTC.
         - Note that this is copied from RV(snapshots[].created) 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.
       type: str
       sample: "2025-01-21T13:40:38+00:00"
       returned: success
     size:
       description:
         - The Snapshot size in MB.
         - Note that this is copied from RV(snapshots[].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.
       type: int
       sample: 400
       returned: success
     filesystem_size:
       description:
         - The size of the Storage Box at creation time of the snapshot in MB.
         - Note that this is computed from RV(snapshots[].stats.size_filesystem) 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.
       type: int
       sample: 12345
       returned: success
     automatic:
       description:
         - Whether the snapshot was created automatically.
         - Note that this is computed from RV(snapshots[].is_automatic) 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.
       type: bool
       sample: false
       returned: success
     comment:
       description:
         - The comment for the snapshot.
         - Note that this is copied from RV(snapshots[].description) 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.
       type: str
       sample: "This is a snapshot"
       returned: success
@@ -176,14 +186,38 @@
     api_fetch_url_json,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 
 def adjust_legacy(snapshot):
     result = dict(snapshot)
-    result["timestamp"] = result["created"]
-    result["size"] = result["stats"]["size"] // (1024 * 1024)
-    result["filesystem_size"] = result["stats"]["size_filesystem"] // (1024 * 1024)
-    result["automatic"] = result["is_automatic"]
-    result["comment"] = result["description"]
+    result["timestamp"] = deprecate_value(
+        result["created"],
+        "The return value `timestamp` is deprecated; use `created` instead.",
+        version="3.0.0",
+    )
+    result["size"] = deprecate_value(
+        result["stats"]["size"] // (1024 * 1024),
+        "The return value `size` is deprecated; use `stats.size / (1024*1024)` instead.",
+        version="3.0.0",
+    )
+    result["filesystem_size"] = deprecate_value(
+        result["stats"]["size_filesystem"] // (1024 * 1024),
+        "The return value `filesystem_size` is deprecated; use `stats.size_filesystem / (1024*1024)` instead.",
+        version="3.0.0",
+    )
+    result["automatic"] = deprecate_value(
+        result["is_automatic"],
+        "The return value `automatic` is deprecated; use `is_automatic` instead.",
+        version="3.0.0",
+    )
+    result["comment"] = deprecate_value(
+        result["description"],
+        "The return value `comment` is deprecated; use `description` instead.",
+        version="3.0.0",
+    )
     return result
 
 

plugins/modules/storagebox_snapshot_plan.py

@@ -155,6 +155,8 @@
         - The month of execution of the plan. V(1) is January, V(12) is December.
         - If set to V(null), the plan is run every month.
         - Always V(null) if O(hetzner_token) is provided.
+        - 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.
       type: int
       sample: null
       returned: success
@@ -182,6 +184,10 @@
     api_fetch_url_json,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 
 def extract(result):
     sb = result['storage_box']
@@ -193,7 +199,7 @@ def extract(result):
             'hour': None,
             'day_of_week': None,
             'day_of_month': None,
-            'month': None,
+            'month': deprecate_value(None, "The return value `month` is deprecated; it is always null.", version="3.0.0"),
             'max_snapshots': None,
         }
 
@@ -203,7 +209,7 @@ def extract(result):
         'hour': sp['hour'],
         'day_of_week': sp['day_of_week'],
         'day_of_month': sp['day_of_month'],
-        'month': None,
+        'month': deprecate_value(None, "The return value `month` is deprecated; it is always null.", version="3.0.0"),
         'max_snapshots': sp['max_snapshots'],
     }
 

plugins/modules/storagebox_snapshot_plan_info.py

@@ -101,6 +101,8 @@
         - The month of execution of the plan. V(1) is January, V(12) is December.
         - If set to V(null), the plan is run every month.
         - Always V(null) if O(hetzner_token) is provided.
+        - 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.
       type: int
       sample: null
       returned: success
@@ -126,6 +128,10 @@
     api_fetch_url_json,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 
 def extract(result):
     sb = result['storage_box']
@@ -137,7 +143,7 @@ def extract(result):
             'hour': None,
             'day_of_week': None,
             'day_of_month': None,
-            'month': None,
+            'month': deprecate_value(None, "The return value `month` is deprecated; it is always null.", version="3.0.0"),
             'max_snapshots': None,
         }
 
@@ -147,7 +153,7 @@ def extract(result):
         'hour': sp['hour'],
         'day_of_week': sp['day_of_week'],
         'day_of_month': sp['day_of_month'],
-        'month': None,
+        'month': deprecate_value(None, "The return value `month` is deprecated; it is always null.", version="3.0.0"),
         'max_snapshots': sp['max_snapshots'],
     }
 

plugins/modules/storagebox_subaccount.py

@@ -270,6 +270,10 @@
   description:
     - The subaccount object returned by the API.
     - If O(hetzner_token) is provided, some extra fields are added to make this more compatible with the format returned by O(hetzner_user).
+    - B(This extra return values are 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 these return values.
+      These return values are RV(ignore:homedirectory), RV(ignore:samba), RV(ignore:ssh), RV(ignore:webdav), RV(ignore:external_reachability),
+      RV(ignore:readonly), RV(ignore:createtime), and RV(ignore:comment).
   type: dict
   returned: if O(state=present)
 """
@@ -291,6 +295,10 @@
     api_fetch_url_json,
 )
 
+from ansible_collections.community.hrobot.plugins.module_utils._tagging import (
+    deprecate_value,
+)
+
 
 def create_subaccount(module, storagebox_id, subaccount):
     action_url = "{0}/v1/storage_boxes/{1}/subaccounts".format(API_BASE_URL, storagebox_id)
@@ -483,7 +491,11 @@ def adjust_legacy(subaccount):
     }.items():
         value, exists = get_value_opt(subaccount, path)
         if exists:
-            result[key] = value
+            result[key] = deprecate_value(
+                value,
+                "The return value `{0}` is deprecated; use `{1}` instead.".format(key, ".".join(path)),
+                version="3.0.0",
+            )
     return result