refactor: mark module_utils modules as private (#782)

##### SUMMARY

All `module_utils` are now marked as **private**. None of the modules
were intended for public use.

Similar to
https://togithub.com/ansible-collections/community.general/issues/11312

plugins/filter/all.py

@@ -5,7 +5,7 @@ from typing import Literal
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.common.text.converters import to_native
 
-from ..module_utils.vendor.hcloud.exp.zone import format_txt_record
+from ..module_utils._vendor.hcloud.exp.zone import format_txt_record
 
 
 # pylint: disable=unused-argument

plugins/inventory/hcloud.py

@@ -202,16 +202,16 @@ from ansible.plugins.inventory import BaseInventoryPlugin, Cacheable, Constructa
 from ansible.utils.display import Display
 from ansible.utils.vars import combine_vars
 
-from ..module_utils.client import (
+from ..module_utils._client import (
     Client,
     ClientException,
     client_check_required_lib,
     client_get_by_name_or_id,
 )
-from ..module_utils.vendor.hcloud import APIException
-from ..module_utils.vendor.hcloud.networks import Network
-from ..module_utils.vendor.hcloud.servers import Server
-from ..module_utils.version import version
+from ..module_utils._vendor.hcloud import APIException
+from ..module_utils._vendor.hcloud.networks import Network
+from ..module_utils._vendor.hcloud.servers import Server
+from ..module_utils._version import version
 
 if sys.version_info >= (3, 11):
     # The typed dicts are only used to help development and we prefer not requiring

plugins/module_utils/_base.py

@@ -1,7 +1,7 @@
 # Copyright: (c) 2019, Hetzner Cloud GmbH <info@hetzner-cloud.de>
 
-# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
-
+# 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 annotations
 
@@ -16,15 +16,19 @@ from ansible.module_utils.common.validation import (
     check_required_one_of,
 )
 
-from .client import ClientException, client_check_required_lib, client_get_by_name_or_id
-from .vendor.hcloud import (
+from ._client import (
+    ClientException,
+    client_check_required_lib,
+    client_get_by_name_or_id,
+)
+from ._vendor.hcloud import (
     APIException,
     Client,
     HCloudException,
     exponential_backoff_function,
 )
-from .vendor.hcloud.actions import ActionException
-from .version import version
+from ._vendor.hcloud.actions import ActionException
+from ._version import version
 
 
 class AnsibleModule(AnsibleModuleBase):

plugins/module_utils/_client.py

@@ -1,12 +1,15 @@
 # Copyright: (c) 2023, Hetzner Cloud GmbH <info@hetzner-cloud.de>
 
+# 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 annotations
 
 from contextlib import contextmanager
 
 from ansible.module_utils.basic import missing_required_lib
 
-from .vendor.hcloud import APIException, Client as ClientBase
+from ._vendor.hcloud import APIException, Client as ClientBase
 
 HAS_REQUESTS = True
 HAS_DATEUTIL = True

plugins/module_utils/_deprecation.py

@@ -1,3 +1,6 @@
+# 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 annotations
 
 import warnings
@@ -5,8 +8,8 @@ from datetime import datetime, timezone
 
 from ansible.module_utils.basic import AnsibleModule
 
-from .vendor.hcloud.locations import BoundLocation
-from .vendor.hcloud.server_types import BoundServerType, ServerTypeLocation
+from ._vendor.hcloud.locations import BoundLocation
+from ._vendor.hcloud.server_types import BoundServerType, ServerTypeLocation
 
 DEPRECATED_EXISTING_SERVERS = """
 Existing servers of that type will continue to work as before and no action is \

plugins/module_utils/_experimental.py

@@ -1,8 +1,11 @@
 # Copyright: (c) 2025, Hetzner Cloud GmbH <info@hetzner-cloud.de>
 
+# 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 annotations
 
-from .hcloud import AnsibleModule
+from ._base import AnsibleModule
 
 
 def experimental_warning_function(product: str, maturity: str, url: str):

plugins/module_utils/_floating_ip.py

@@ -1,6 +1,9 @@
+# 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 annotations
 
-from ..module_utils.vendor.hcloud.floating_ips import (
+from ._vendor.hcloud.floating_ips import (
     BoundFloatingIP,
 )
 

plugins/module_utils/_ipaddress.py

@@ -0,0 +1,10 @@
+# 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 annotations
+
+from ipaddress import ip_interface
+
+
+def normalize_ip(value: str) -> str:
+    return str(ip_interface(value))

plugins/module_utils/_primary_ip.py

@@ -1,6 +1,9 @@
+# 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 annotations
 
-from ..module_utils.vendor.hcloud.primary_ips import (
+from ._vendor.hcloud.primary_ips import (
     BoundPrimaryIP,
 )
 

plugins/module_utils/_ssh.py

@@ -1,3 +1,6 @@
+# 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 annotations
 
 from base64 import b64decode

plugins/module_utils/_storage_box.py

@@ -1,7 +1,10 @@
+# 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 annotations
 
-from ..module_utils.client import client_resource_not_found
-from ..module_utils.vendor.hcloud.storage_boxes import (
+from ._client import client_resource_not_found
+from ._vendor.hcloud.storage_boxes import (
     BoundStorageBox,
     StorageBoxesClient,
 )

plugins/module_utils/_storage_box_snapshot.py

@@ -1,6 +1,9 @@
+# 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 annotations
 
-from ..module_utils.vendor.hcloud.storage_boxes import (
+from ._vendor.hcloud.storage_boxes import (
     BoundStorageBoxSnapshot,
 )
 

plugins/module_utils/_storage_box_subaccount.py

@@ -1,6 +1,9 @@
+# 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 annotations
 
-from ..module_utils.vendor.hcloud.storage_boxes import (
+from ._vendor.hcloud.storage_boxes import (
     BoundStorageBox,
     BoundStorageBoxSubaccount,
 )

plugins/module_utils/_vendor/__init__.py

@@ -0,0 +1,2 @@
+# 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!

plugins/module_utils/_version.py

@@ -0,0 +1,6 @@
+# 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 annotations
+
+version = "6.4.0"  # x-release-please-version

plugins/module_utils/ipaddress.py

@@ -1,7 +0,0 @@
-from __future__ import annotations
-
-from ipaddress import ip_interface
-
-
-def normalize_ip(value: str) -> str:
-    return str(ip_interface(value))

plugins/module_utils/version.py

@@ -1,3 +0,0 @@
-from __future__ import annotations
-
-version = "6.4.0"  # x-release-please-version

plugins/modules/certificate.py

@@ -147,9 +147,9 @@ hcloud_certificate:
 
 from ansible.module_utils.basic import AnsibleModule
 
-from ..module_utils.hcloud import AnsibleHCloud
-from ..module_utils.vendor.hcloud import HCloudException
-from ..module_utils.vendor.hcloud.certificates import BoundCertificate
+from ..module_utils._base import AnsibleHCloud
+from ..module_utils._vendor.hcloud import HCloudException
+from ..module_utils._vendor.hcloud.certificates import BoundCertificate
 
 
 class AnsibleHCloudCertificate(AnsibleHCloud):

plugins/modules/certificate_info.py

@@ -88,9 +88,9 @@ hcloud_certificate_info:
 
 from ansible.module_utils.basic import AnsibleModule
 
-from ..module_utils.hcloud import AnsibleHCloud
-from ..module_utils.vendor.hcloud import HCloudException
-from ..module_utils.vendor.hcloud.certificates import BoundCertificate
+from ..module_utils._base import AnsibleHCloud
+from ..module_utils._vendor.hcloud import HCloudException
+from ..module_utils._vendor.hcloud.certificates import BoundCertificate
 
 
 class AnsibleHCloudCertificateInfo(AnsibleHCloud):

plugins/modules/datacenter_info.py

@@ -119,9 +119,9 @@ hcloud_datacenter_info:
 
 from ansible.module_utils.basic import AnsibleModule
 
-from ..module_utils.hcloud import AnsibleHCloud
-from ..module_utils.vendor.hcloud import HCloudException
-from ..module_utils.vendor.hcloud.datacenters import BoundDatacenter
+from ..module_utils._base import AnsibleHCloud
+from ..module_utils._vendor.hcloud import HCloudException
+from ..module_utils._vendor.hcloud.datacenters import BoundDatacenter
 
 
 class AnsibleHCloudDatacenterInfo(AnsibleHCloud):

plugins/modules/firewall.py

@@ -220,10 +220,10 @@ import time
 
 from ansible.module_utils.basic import AnsibleModule
 
-from ..module_utils.hcloud import AnsibleHCloud
-from ..module_utils.ipaddress import normalize_ip
-from ..module_utils.vendor.hcloud import APIException, HCloudException
-from ..module_utils.vendor.hcloud.firewalls import (
+from ..module_utils._base import AnsibleHCloud
+from ..module_utils._ipaddress import normalize_ip
+from ..module_utils._vendor.hcloud import APIException, HCloudException
+from ..module_utils._vendor.hcloud.firewalls import (
     BoundFirewall,
     FirewallResource,
     FirewallRule,