Make each deprecated alias take its own message

README.md

@@ -194,7 +194,7 @@ object so `isinstance` keeps working through both paths:
 ```python
 from typing import TYPE_CHECKING, TypeAlias
 
-from frequenz.core.warnings import deprecated_aliases
+from frequenz.core.warnings import DeprecatedAlias, deprecated_aliases
 
 if TYPE_CHECKING:
     # Type checkers can't see the runtime `__getattr__` in the `else` branch.
@@ -209,10 +209,13 @@ else:
     # imports included.
     __getattr__ = deprecated_aliases(
         __name__,
-        {
-            "Decimal": "decimal",  # decimal.Decimal
-            "Rational": "fractions:Fraction",  # Renamed on the way out
-        },
+        # Warns "<module>.Decimal is deprecated since v1.2.0. Use
+        # decimal.Decimal instead."
+        DeprecatedAlias("Decimal", new_module="decimal", since="v1.2.0"),
+        # Renamed on the way out
+        DeprecatedAlias(
+            "Rational", new_module="fractions", new_name="Fraction", since="v1.3.0"
+        ),
     )
 ```
 

RELEASE_NOTES.md

@@ -8,4 +8,4 @@ A new `frequenz.core.warnings` module with:
 
 - `asserting_no_warnings()`, and its `asserting_no_deprecations()` shortcut, fail when the code in the block raises a matching warning/deprecation, listing each one with the place it came from. They are meant for tests, and are a better tool than an `"error"` filter, which makes `warnings.warn()` raise inside the code under test and so changes the very behaviour the test is checking.
 
-- `deprecated_aliases()` builds a module `__getattr__` that warns when a symbol that moved to another module is reached through its old import path, serving the very same object so `isinstance` keeps working through both paths.
+- `deprecated_aliases()` builds a module `__getattr__` that warns when a symbol that moved to another module, or was renamed, is reached through its old import path, serving the very same object so `isinstance` keeps working through both paths.

src/frequenz/core/warnings/__init__.py

@@ -10,7 +10,9 @@
 having to touch a symbol it deprecated itself.
 
 It also provides [`deprecated_aliases`][.deprecated_aliases], to keep the old import
-path of a symbol that moved to another module working, warning whoever uses it, and
+path of a symbol that moved to another module, or was renamed, working, warning
+whoever uses it since which version it is deprecated, as its
+[`DeprecatedAlias`][.DeprecatedAlias] entry says, and
 [`asserting_no_warnings`][.asserting_no_warnings] with its
 [`asserting_no_deprecations`][.asserting_no_deprecations] shortcut, to check in a test
 that a piece of code doesn't warn.
@@ -56,10 +58,11 @@ def convert(value: str) -> int:
 """
 
 from ._asserting import asserting_no_deprecations, asserting_no_warnings
-from ._deprecated_aliases import deprecated_aliases
+from ._deprecated_aliases import DeprecatedAlias, deprecated_aliases
 from ._ignoring import ignoring_deprecations, ignoring_warnings
 
 __all__ = [
+    "DeprecatedAlias",
     "asserting_no_deprecations",
     "asserting_no_warnings",
     "deprecated_aliases",