Deprecate and redirect the imports of ``saltfactories.utils.{ports,pr…

…ocesses}``

Fixes #106

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>

changelog/106.bugfix.rst

@@ -0,0 +1 @@
+Instead of just removing `saltfactories.utils.ports` and `saltfactories.utils.processes`, redirect the imports to the right library and show a deprecation warning.

setup.cfg

@@ -124,6 +124,14 @@ per-file-ignores =
   examples/*.py: D100,D101,D102,D103,D105,D415
   # D100 Missing docstring in public module
   src/saltfactories/utils/coverage/sitecustomize.py: D100
+  # D100
+  # F401 'pytestshellutils.utils.ports.*' imported but unused
+  # F403 'from pytestshellutils.utils.ports import *' used; unable to detect undefined names
+  src/saltfactories/utils/ports.py: D100,F401,F403
+  # D100
+  # F401 'pytestshellutils.utils.processes.*' imported but unused
+  # F403 'from pytestshellutils.utils.processes import *' used; unable to detect undefined names
+  src/saltfactories/utils/processes.py: D100,F401,F403
 
 ignore =
   # D104 Missing docstring in public package

src/saltfactories/utils/__init__.py

@@ -4,13 +4,21 @@
 ..
     PYTEST_DONT_REWRITE
 """
+import inspect
 import pathlib
 import random
 import string
+import sys
+import warnings
 from functools import lru_cache
+from typing import Optional
+from typing import Type
 
+import packaging.version
 import salt.utils.user
 
+import saltfactories
+
 
 def random_string(prefix, size=6, uppercase=True, lowercase=True, digits=True):
     """
@@ -54,3 +62,64 @@ def cast_to_pathlib_path(value):
         return pathlib.Path(value.strpath)
     except AttributeError:
         return pathlib.Path(str(value))
+
+
+def warn_until(
+    version: str,
+    message: str,
+    category: Type[Warning] = DeprecationWarning,
+    stacklevel: Optional[int] = None,
+    _dont_call_warnings: bool = False,
+    _pkg_version_: Optional[str] = None,
+) -> None:
+    """
+    Show a deprecation warning.
+
+    Helper function to raise a warning, by default, a ``DeprecationWarning``,
+    until the provided ``version``, after which, a ``RuntimeError`` will
+    be raised to remind the developers to remove the warning because the
+    target version has been reached.
+
+    :param version:
+        The version string after which the warning becomes a ``RuntimeError``.
+        For example ``2.1``.
+    :param message:
+        The warning message to be displayed.
+    :param category:
+        The warning class to be thrown, by default ``DeprecationWarning``
+    :param stacklevel:
+        There should be no need to set the value of ``stacklevel``.
+    :param _dont_call_warnings:
+        This parameter is used just to get the functionality until the actual
+        error is to be issued. When we're only after the version checks to
+        raise a ``RuntimeError``.
+    """
+    _version = packaging.version.parse(version)
+    if _pkg_version_ is None:
+        _pkg_version_ = saltfactories.__version__  # type: ignore[attr-defined]
+    _pkg_version = packaging.version.parse(_pkg_version_)
+
+    if stacklevel is None:
+        # Attribute the warning to the calling function, not to warn_until()
+        stacklevel = 3
+
+    if _pkg_version >= _version:
+        caller = inspect.getframeinfo(sys._getframe(stacklevel - 1))
+        raise RuntimeError(
+            "The warning triggered on filename '{filename}', line number "
+            "{lineno}, is supposed to be shown until version "
+            "{until_version} is released. Current version is now "
+            "{version}. Please remove the warning.".format(
+                filename=caller.filename,
+                lineno=caller.lineno,
+                until_version=_pkg_version_,
+                version=version,
+            ),
+        )
+
+    if _dont_call_warnings is False:
+        warnings.warn(
+            message.format(version=version),
+            category,
+            stacklevel=stacklevel,
+        )

src/saltfactories/utils/ports.py

@@ -0,0 +1,11 @@
+# pylint: disable=wildcard-import,unused-wildcard-import
+from pytestshellutils.utils.ports import *
+
+from saltfactories.utils import warn_until
+
+warn_until(
+    "2.0.0",
+    "The 'ports' module is deprecated and will cease to exist after "
+    "pytest-salt-factories {version}. Please import 'ports' from "
+    "'pytestshellutils.utils' instead.",
+)

src/saltfactories/utils/ports.pyi

@@ -0,0 +1 @@
+from pytestshellutils.utils.ports import *

src/saltfactories/utils/processes.py

@@ -0,0 +1,11 @@
+# pylint: disable=wildcard-import,unused-wildcard-import
+from pytestshellutils.utils.processes import *
+
+from saltfactories.utils import warn_until
+
+warn_until(
+    "2.0.0",
+    "The 'processes' module is deprecated and will cease to exist after "
+    "pytest-salt-factories {version}. Please import 'processes' from "
+    "'pytestshellutils.utils' instead.",
+)

src/saltfactories/utils/processes.pyi

@@ -0,0 +1 @@
+from pytestshellutils.utils.processes import *