chore: add deprecation suppression, pull in deprecated dependency

This change adds a runtime dep of the 'deprecated' package- this
https://pypi.org/project/Deprecated/ .

However, being that snakeoil can be used by critical code, the
internal snakeoil usage of it explicitly can fallback to py3.13
deprecated implementation, and if it's <py3.13 it just suppresses
the deprecations in full.

By "can fallback", this includes ImportError- broken import, and missing.

It's not optimal, but this is sane enough frankly.

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

Author: ferringb

pyproject.toml

@@ -28,6 +28,7 @@ dynamic = ["version"]
 
 dependencies = [
     "lazy-object-proxy",
+    "deprecated~=1.2.18",
 ]
 
 [project.optional-dependencies]

src/snakeoil/deprecation.py

@@ -1,39 +1,59 @@
+"""
+Deprecation functionally which gracefully degrades if degraded is missing, or <py3.13
+
+All snakeoil code must use this module for deprecation functionality.
+
+Snakeoil *must* work, thus the external dependency on 'degraded' module is desirable but
+shouldn't be strictly required- if that module doesn't exist (for whatever reason, despite
+deps), warn, and degrade back to >=py3.13 warning.degraded, and if <py3.13, do nothing.
+
+Libraries using snakeoil should decide if they want this or not; pkgcore for example
+must use this library for similar 'must work' reasons, but non system critical software
+*should* use the degraded module directly for their own code, or use warning.degraded.
+
+That's up to the author.  This exists to allow having the degraded dep but not strictly
+require it, while providing shims that look like degraded.degraded if it's not available.
+"""
+
 __all__ = ("deprecated",)
 
+import functools
+import sys
 import warnings
 from contextlib import contextmanager
 
-_import_failed = False
 try:
-    from warnings import deprecated  # pyright: ignore[reportAssignmentType]
-except ImportError:
-    _import_failed = True
+    from deprecated import deprecated as _deprecated_module_func
 
-    def deprecated(_message):
-        """
-        This is a noop; deprecation warnings are disabled for pre python
-        3.13.
-        """
+    @functools.wraps(_deprecated_module_func)
+    def deprecated(message, *args, **kwargs):  # pyright: ignore[reportRedeclaration]
+        """Shim around deprecated.deprecated enforcing that message is always the first argument"""
+        return _deprecated_module_func(*args, **kwargs)
+except ImportError:
+    warnings.warn(
+        "deprecated module could not be imported.  Deprecation messages may not be shown"
+    )
+    if sys.version_info >= (3, 12, 0):
+        # shim it, but drop the deprecated.deprecated metadata.
+        def deprecated(message, *args, **kwargs):
+            return warnings.deprecated(message)
+    else:
+        # stupid shitty python 3.11/3.12...
+        def deprecated(_message, *args, **kwargs):
+            """
+            This is disabled in full due to the deprecated module failing to import, and
+            inability to fallback since the python version is less than 3.13
+            """
 
-        def f(thing):
-            return thing
+            def f(thing):
+                return thing
 
-        return f
+            return f
 
 
 @contextmanager
 def suppress_deprecation_warning():
-    """
-    Used for suppressing all deprecation warnings beneath this
-
-    Use this for known deprecated code that is already addressed, but
-    just waiting to die.  Deprecated code calling deprecated code, specifically.
-    """
-    if _import_failed:
-        # noop.
+    # see https://docs.python.org/3/library/warnings.html#temporarily-suppressing-warnings
+    with warnings.catch_warnings():
+        warnings.simplefilter(action="ignore", category=DeprecationWarning)
         yield
-    else:
-        # see https://docs.python.org/3/library/warnings.html#temporarily-suppressing-warnings
-        with warnings.catch_warnings():
-            warnings.simplefilter(action="ignore", category=DeprecationWarning)
-            yield

tests/klass/test_init.py

@@ -150,7 +150,7 @@ class c(dict):
 class Test_chained_getter:
     @staticmethod
     def kls(*args, **kwargs):
-        with deprecated_call():
+        with pytest.deprecated_call():
             kwargs.setdefault("disable_inst_caching", True)
             return klass.chained_getter(*args, **kwargs)
 
@@ -161,7 +161,7 @@ def test_hash(self):
     def test_caching(self):
         # since it caches, it'll only trigger the warning the *first* time, thus
         # invoke this ourselves directly
-        with deprecated_call():
+        with pytest.deprecated_call():
             assert klass.chained_getter(
                 "asdf", disable_inst_caching=False
             ) is klass.chained_getter("asdf", disable_inst_caching=False)
@@ -518,12 +518,12 @@ class cls2:
 
 class TestImmutableInstance:
     def test_metaclass(self):
-        with deprecated_call():
+        with pytest.deprecated_call():
             self.common_test(lambda x: x, metaclass=klass.immutable_instance)
 
     def test_injection(self):
         def f(scope):
-            with deprecated_call():
+            with pytest.deprecated_call():
                 klass.inject_immutable_instance(scope)
 
         self.common_test(f)