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

.github/workflows/vendor.yml

@@ -4,11 +4,11 @@ on:
   push:
     branches: [main, stable-1]
     paths:
-      - plugins/module_utils/vendor/**
+      - plugins/module_utils/_vendor/**
       - scripts/vendor.py
   pull_request:
     paths:
-      - plugins/module_utils/vendor/**
+      - plugins/module_utils/_vendor/**
       - scripts/vendor.py
 
 jobs:

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 ---
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
-exclude: ^plugins/module_utils/vendor/hcloud/.*$
+exclude: ^plugins/module_utils/_vendor/hcloud/.*$
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0

Makefile

@@ -29,7 +29,7 @@ clean:
 
 sanity:
 	ansible-test sanity --color --truncate 0 -v \
-		--exclude plugins/module_utils/vendor/ \
+		--exclude plugins/module_utils/_vendor/ \
 		--exclude scripts/ \
 		--exclude tests/utils/ \
 		--docker default \

changelogs/fragments/private-module-utils.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - All ``module_utils`` are now marked as **private**. None of the modules were intended for public use.

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 import APIException
-from ..module_utils.vendor.hcloud.networks import Network
+from ..module_utils._vendor.hcloud.networks import Network
-from ..module_utils.vendor.hcloud.servers import Server
+from ..module_utils._vendor.hcloud.servers import Server
-from ..module_utils.version import version
+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 ._client import (
-from .vendor.hcloud 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 ._vendor.hcloud.actions import ActionException
-from .version import version
+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.locations import BoundLocation
-from .vendor.hcloud.server_types import BoundServerType, ServerTypeLocation
+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 ._client import client_resource_not_found
-from ..module_utils.vendor.hcloud.storage_boxes import (
+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