docs: Explain the frequenz.core.warnings helpers in the wrapping guide

The previous commits moved the library and its tests to the
`frequenz.core.warnings` helpers, but the guide still told contributors
to silence inner deprecations with `warnings.catch_warnings()`, which is
the exact bug they fix. Anyone following it would bring the warning
amplification back.

The deprecation guide gets two new sections and an updated one:

* Keeping a moved symbol importable with `deprecated_aliases()`,
  including the `TYPE_CHECKING`/`else` structure it needs, a message
  carrying the version, and when a deprecated class is the better fit,
  as with `ComponentId`.
* Silencing only the deprecations the library raises itself, with
  `ignoring_deprecations()` around the one statement, and why
  `catch_warnings()` must not be used for it.
* Testing that a replacement doesn't warn with
  `asserting_no_deprecations()` instead of an "error" filter.

The testing guide points at both helpers. The helpers are mentioned as
plain code rather than cross-references because the frequenz-core
inventory will only have them once v1.5.0 is released.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

docs/wrapping-guide/deprecation-and-compatibility.md

@@ -120,6 +120,80 @@ class Event(Enum):
     """Event when a new resource is created."""
 ```
 
+## Keep a moved symbol importable
+
+When a public symbol moves to another module, keep its old import path working
+with `frequenz.core.warnings.deprecated_aliases()` instead of writing a module
+`__getattr__` by hand. The alias is the very same object, so
+[`isinstance()`][isinstance] keeps working through both paths, and the
+documentation build generates the admonition and label for every alias in the
+table, as long as the table and the message are literals in the call.
+
+```python
+from typing import TYPE_CHECKING, TypeAlias
+
+from frequenz.core.warnings import deprecated_aliases
+
+if TYPE_CHECKING:
+    from example.new import Thing as _Thing
+
+    Thing: TypeAlias = _Thing
+    """A thing, now living in `example.new`."""
+else:
+    __getattr__ = deprecated_aliases(
+        __name__,
+        {"Thing": "example.new"},
+        message="{old} is deprecated since v0.5.0. Use {new} instead.",
+    )
+```
+
+Keep that structure exactly: without the `else:`, type checkers see the
+`__getattr__` and treat every name in the module as `Any`. Pass `message` so
+the warning carries the version like every other deprecation here. `{old}` and
+`{new}` become the two fully qualified names, and the documentation turns
+`{new}` into a link, so leave out the cross-reference brackets.
+
+An alias only fits when the old name can be the same object as the new one.
+When the old type has to stay distinct, as
+[`ComponentId`][frequenz.client.common.microgrid.components.ComponentId] does
+next to
+[`ElectricalComponentId`][frequenz.client.common.microgrid.electrical_components.ElectricalComponentId],
+keep a deprecated class instead.
+
+## Silence only the deprecations you raise yourself
+
+Sometimes library code has to touch a symbol it deprecated itself, such as a
+converter comparing a value against a deprecated `UNSPECIFIED` member. The
+caller did nothing deprecated, so the warning is noise. Silence it with
+`frequenz.core.warnings.ignoring_deprecations()`, around the statement that
+raises it and nothing more, so deprecations from anywhere else still get
+through:
+
+```python
+from frequenz.core.warnings import ignoring_deprecations
+
+from example import Event
+
+
+def event_to_str(event: Event | int) -> str:
+    with ignoring_deprecations():
+        unspecified = Event.UNSPECIFIED
+    if event in (0, unspecified):
+        return "<invalid:0>"
+    return event.name if isinstance(event, Event) else f"<unknown:{event}>"
+```
+
+The same applies to a deprecated function calling another deprecated symbol:
+its caller gets the one public warning of the outer function, and the inner one
+is silenced.
+
+Do not use [`warnings.catch_warnings()`][warnings.catch_warnings] for this.
+Entering and leaving it resets the warnings deduplication history of the whole
+program ([python/cpython#73858](https://github.com/python/cpython/issues/73858)),
+so every warning that was already shown, by this library or any other code, is
+shown again after each call. In an application converting data in a loop, that
+turns a handful of warnings into tens of thousands.
+
 ## Tighten invariants in stages
 
 When you tighten a rule, do not always reject old input immediately. First,
@@ -137,11 +211,26 @@ can test the stricter behavior before it becomes required and migrate on purpose
 
 Test every public deprecation with
 [`pytest.deprecated_call()`][pytest.deprecated_call]. Check the exact message
-and the replacement behavior. If deprecated code correctly calls another
-deprecated symbol, suppress only that expected inner
-[`DeprecationWarning`][]
-in a small [`warnings.catch_warnings()`][warnings.catch_warnings] block. The
-outer API must still emit its one public warning.
+and the replacement behavior. The outer API must still emit its one public
+warning, even when it silences inner ones as described above.
+
+Check that the replacement doesn't go through anything deprecated with
+`frequenz.core.warnings.asserting_no_deprecations()`, rather than with an
+`"error"` filter. The filter turns the warning into an exception inside the
+code under test, where a broad `except` can swallow it; the helper records the
+warnings instead and fails when the block ends, listing each one and where it
+came from:
+
+```python
+from frequenz.core.warnings import asserting_no_deprecations
+
+from example import thing_from_proto2
+
+
+def test_thing_from_proto2_does_not_warn() -> None:
+    with asserting_no_deprecations():
+        assert thing_from_proto2(3) == "3"
+```
 
 Add `RELEASE_NOTES.md` migration bullets that state the old behavior, the
 replacement, what changes, and the planned removal version. Remove the

docs/wrapping-guide/index.md

@@ -30,7 +30,7 @@ wrappers.
   `*_from_proto` and `*_to_proto` functions that translate protobuf messages
   to wrapper types.
 - [Deprecation and compatibility](deprecation-and-compatibility.md) — Describes
-  how to replace public functions and tighten validation without surprising
-  callers.
+  how to replace or move public symbols and tighten validation without
+  surprising callers, and how to keep the library's own deprecations quiet.
 - [Testing](testing.md) — Shows how to place tests, check enum parity, and make
   documentation examples and warnings part of the test suite.

docs/wrapping-guide/testing.md

@@ -43,6 +43,10 @@ Assert each expected deprecation with
 [`pytest.deprecated_call()`][pytest.deprecated_call]. This records the public
 warning and stops an unrelated warning from being hidden. When deprecated code
 correctly calls another deprecated symbol, suppress only that inner
-`DeprecationWarning` in a small warning block to avoid duplicate messages. In a
-test, use the same small suppression only for a warning that a dedicated
-assertion already checks. Never suppress warnings globally.
+`DeprecationWarning` in a small `frequenz.core.warnings.ignoring_deprecations()`
+block to avoid duplicate messages. In a test, use the same small suppression
+only for a warning that a dedicated assertion already checks, and check that a
+replacement doesn't warn with `frequenz.core.warnings.asserting_no_deprecations()`.
+Never suppress warnings globally, and never with
+[`warnings.catch_warnings()`][warnings.catch_warnings]; [Deprecation and
+compatibility](deprecation-and-compatibility.md) explains both helpers and why.