mark protect_imports as just for tests

protect_imports is not thread safe and shouldn't be used in actual
runtime code; the python_namespaces module now provides other
ways to do thread safe imports of modules outside of sys.path
which address what this was used for.

This is left in place for tests since that scenario is always
thread safe for our sync code, and the shorthand is useful.

Signed-off-by: Brian Harring <ferringb@gmail.com>

Author: ferringb

src/snakeoil/delayed/__init__.py

@@ -1,11 +1,13 @@
-__all__ = ("regexp",)
+__all__ = ("regexp", "import_module", "is_delayed")
 
 import functools
 import importlib
 import re
+import sys
 import types
+import typing
 
-from ..obj import DelayedInstantiation
+from ..obj import BaseDelayedObject, DelayedInstantiation
 
 
 @functools.wraps(re.compile)
@@ -14,6 +16,19 @@ def regexp(pattern: str, flags: int = 0):
     return DelayedInstantiation(re.Pattern, re.compile, pattern, flags)
 
 
-def import_module(target: str) -> types.ModuleType:
-    """Import a module at time of access.  This is a shim for python's lazy import in 3.15"""
+def import_module(target: str, force_proxy=False) -> types.ModuleType:
+    """Import a module at time of access if it's not already imported.  This is a shim for python's lazy import in 3.15
+
+    :param target: the python namespace path of what to import.  `snakeoil.klass` for example.
+    :param force_proxy: Even if the module is in sys.modules, still return a proxy.  This is a break glass
+      control only relevant for hard cycle breaking.
+    """
+    if not force_proxy and (module := sys.modules.get(target, None)) is not None:
+        return module
     return DelayedInstantiation(types.ModuleType, importlib.import_module, target)
+
+
+# Convert this to a type guard when py3.14 is min.
+def is_delayed(obj: typing.Any) -> bool:
+    cls = object.__getattribute__(obj, "__class__")
+    return isinstance(cls, BaseDelayedObject)

src/snakeoil/deprecation/registry.py

@@ -3,7 +3,7 @@
 import typing
 import warnings
 
-from ..delayed import import_module
+from ..delayed import import_module, is_delayed
 from .util import suppress_deprecations
 
 python_namespaces = import_module("snakeoil.python_namespaces")
@@ -137,6 +137,13 @@ def __call__(
         """Decorate a callable with a deprecation notice, registering it in the internal list of deprecations"""
 
         def f(functor):
+            # Catch mistakes that force proxy objects to realize immediately
+            if is_delayed(functor):
+                raise ValueError(
+                    "deprecation of lazy instantiation objects (`snakeoil.obj.DelayedInstantation` for example) are not possible.  `warnings.deprecated` will immediately reify them.  "
+                    "You must interpose a *real* functor that internally invokes the delayed object when accessed; this is the only way to shield the delayed object `from warnings.deprecated` triggering it."
+                )
+
             if not self.is_enabled:
                 return functor
 

src/snakeoil/python_namespaces.py

@@ -1,16 +1,32 @@
 __all__ = ("import_submodules_of", "get_submodules_of")
 
-import contextlib
 import os
-import sys
 import types
 import typing
-from importlib import import_module, invalidate_caches, machinery
+from importlib import import_module, machinery
 from importlib import util as import_util
 from pathlib import Path
 
+from . import delayed
+from ._internals import deprecated
+
 T_class_filter = typing.Callable[[str], bool]
 
+# Delayed to avoid triggering all test crap- pytest for example- and cycle breaking
+# while the deprecation is being moved out.  There is a cycle for all of this
+# that is due to klass needing the deprecated registry whilst having it's own deprecations.
+_test = delayed.import_module("snakeoil.test")
+
+
+@deprecated(
+    "use `snakeoil.tests.protect_imports`; this should only be used for tests.  Runtime usage should use `import_module_from_path`",
+    removal_in=(0, 12, 0),
+    qualname="snakeoil.python_namespaces.protect_imports",
+)
+def protect_imports():
+    # isolate the access so only when this is invoked, does _test reify.
+    return _test.protect_imports()
+
 
 def get_submodules_of(
     root: types.ModuleType | str,
@@ -111,33 +127,6 @@ def remove_py_extension(path: Path | str) -> str | None:
     return None
 
 
-@contextlib.contextmanager
-def protect_imports() -> typing.Generator[
-    tuple[list[str], dict[str, types.ModuleType]], None, None
-]:
-    """
-    Non threadsafe mock.patch of internal imports to allow revision
-
-    This should used in tests or very select scenarios.  Assume that underlying
-    c extensions that hold internal static state (curse module) will reimport, but
-    will not be 'clean'.  Any changes an import inflicts on the other modules in
-    memory, etc, this cannot block that.  Nor is this intended to do so; it's
-    for controlled tests or very specific usages.
-    """
-    orig_content = sys.path[:]
-    orig_modules = sys.modules.copy()
-    with contextlib.nullcontext():
-        yield sys.path, sys.modules
-
-    sys.path[:] = orig_content
-    # This is explicitly not thread safe, but manipulating sys.path fundamentally isn't thus this context
-    # isn't thread safe.  TL;dr: nuke it, and restore, it's the only way to be sure (to paraphrase)
-    sys.modules.clear()
-    sys.modules.update(orig_modules)
-    # Out of paranoia, force loaders to reset their caches.
-    invalidate_caches()
-
-
 def import_module_from_path(
     path: str | Path, module_name: str | None = None
 ) -> types.ModuleType:

src/snakeoil/test/__init__.py

@@ -7,16 +7,21 @@
     "Modules",
     "NamespaceCollector",
     "protect_process",
+    "protect_imports",
     "random_str",
     "Slots",
 )
 
 
+import contextlib
 import os
 import random
 import string
 import subprocess
 import sys
+import types
+import typing
+from importlib import invalidate_caches
 from unittest.mock import patch
 
 from .abstract import AbstractTest
@@ -113,3 +118,31 @@ def mock_import(name, *args, **kwargs):
         return orig_import(name, *args, **kwargs)
 
     return patch("builtins.__import__", side_effect=mock_import)
+
+
+@contextlib.contextmanager
+def protect_imports() -> typing.Generator[
+    tuple[list[str], dict[str, types.ModuleType]], None, None
+]:
+    """
+    Non threadsafe mock.patch of internal imports to allow revision
+
+    This should used in tests or very select scenarios.  Assume that underlying
+    c extensions that hold internal static state (curse module) will reimport, but
+    will not be 'clean'.  Any changes an import inflicts on the other modules in
+    memory, etc, this cannot block that.  Nor is this intended to do so; it's
+    for controlled tests or very specific usages.
+    """
+    # Do not change this code without changing python_namespaces.protect_imports.  We have two implementations due to cycle issues.
+    orig_content = sys.path[:]
+    orig_modules = sys.modules.copy()
+    with contextlib.nullcontext():
+        yield sys.path, sys.modules
+
+    sys.path[:] = orig_content
+    # This is explicitly not thread safe, but manipulating sys.path fundamentally isn't thus this context
+    # isn't thread safe.  TL;dr: nuke it, and restore, it's the only way to be sure (to paraphrase)
+    sys.modules.clear()
+    sys.modules.update(orig_modules)
+    # Out of paranoia, force loaders to reset their caches.
+    invalidate_caches()

tests/test_delayed.py

@@ -27,3 +27,8 @@ def test_import_module(tmp_path):
         assert "blah" in modules
         assert 1 == f.x
         assert modules["blah"] is not f
+
+        shortcircuited = delayed.import_module("blah")
+        assert modules["blah"] is shortcircuited, (
+            "import_module must return the module if it already is in sys.modules rather than a proxy"
+        )