Style deprecation notices in the API reference by llucax · Pull Request #288 · frequenz-floss/frequenz-client-common-python

llucax · 2026-09-21T12:47:16Z

Preparation for the client-common 0.4.1 update, so deprecation notices already look right by the time it adds more of them.

First, the styling: a CSS rule for the deprecated admonition class (gravestone icon, its own colour, otherwise like a warning), and the griffe-warnings-deprecated extension wired into the mkdocstrings handler so symbols decorated with typing_extensions.deprecated get an admonition generated for them. The extension's kind is set to deprecated rather than the default warning, so what it emits is markup-identical to a hand-written Deprecated: admonition, and one rule styles both.

Then a third commit brings every deprecation in the repo in line with the deprecations guide, because most of them were not reaching the rendered documentation at all.

The nine Warning: Deprecated blocks on symbols the decorator already marks are removed rather than converted, since the extension generates one for those and a hand-written copy would show the notice twice.

Two things worth a reviewer's eye:

ElectricalComponentCategory now spells its decorator message out as a literal instead of reusing the module constant. griffe renders the admonition only when it can read the message statically, so built from a module-level name it produced nothing.
docs/wrapping-guide/deprecation-and-compatibility.md was updated to describe the new deprecation style..

Style the `deprecated` admonition class like a warning, but with the `material/grave-stone` icon and its own colour, so deprecation notices read as deprecation notices and not as generic warnings. That class is what a hand-written `Deprecated:` admonition in a docstring produces, and also what the griffe extension added next will emit, so a single rule covers both sources. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Wire the `griffe-warnings-deprecated` extension into the mkdocstrings handler options, so every symbol decorated with `typing_extensions.deprecated` gets a "Deprecated" admonition in the API reference with no docstring edit at all. The extension's `kind` is set to `deprecated` rather than the default `warning`, so it emits `class="deprecated"`, which is exactly what a hand-written `Deprecated:` admonition produces. The CSS rule added in the previous commit then styles both, and the two are visually indistinguishable. That matters because the decorator cannot reach everything: module-level aliases, a single function argument, enum members and whole modules still need the admonition written by hand. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax · 2026-09-21T12:48:28Z

Example of how it looks.

llucax · 2026-09-21T16:59:25Z

Updated: pushed 3013200 and rewrote the description.

The PR originally only added the styling and deliberately left existing notices alone, which meant it landed a styling rule that almost nothing in this repo used. It now also brings every deprecation in line with the deprecations guide, which turned out to be most of them:

The 26 enum members using frequenz.core.enum.deprecated_member said nothing at all in the docs. The helper predates PEP 702, so griffe generates no admonition for it. They now have hand-written ones, matching what client-microgrid already does.
MetricSample.sample_time and .bounds carry the decorator, but griffe does not see it underneath @property, so they generated nothing either.
The delivery-area code field and invalid DeliveryArea construction used Warning: admonitions, which render as ordinary warnings.
The nine Warning: Deprecated blocks on symbols the decorator does mark are removed, since the extension now generates those and a hand-written copy would show the notice twice. Their extra explanation stays as prose in the docstring body.
The decorator messages are rewritten to the guide's form: fully qualified plain names, the replacement as a bare [name][] cross-reference, and "since v0.4.1" in the sentence.

That takes the rendered count from 0 to 43.

Two things I would like a second opinion on:

ElectricalComponentCategory now spells its decorator message out as a literal instead of reusing the module constant. griffe renders the admonition only when it can read the message statically, so built from a module-level name it produced nothing. The duplication is the price of the notice appearing at all.
docs/wrapping-guide/deprecation-and-compatibility.md was updated to describe the new style.

Two tests asserted a full message and were updated; the rest match a substring. nox is green (2052 tests, mypy, pylint, flake8/pydoclint, black, isort) and the strict docs build passes.

cmd:skip-release-notes is applied: docstrings and warning text change, the API does not.

Copilot

Copilot review overview

🟡 Changes recommended

Decorated properties currently render duplicate notices, and several messages and tests do not follow the newly documented exact format.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 4 · 1

Open (5)

Remove duplicate hand-written deprecation notice · New
Move returned-type guidance into the docstring · New
Remove extra guidance from decorator warning · New
Strengthen warning test to verify replacement link · New
Correct generated admonition placement documentation · New

What changed in this PR

Adds consistent deprecation notices to generated API documentation.

Changes:

Adds and styles generated Deprecated admonitions.
Standardizes deprecation messages and documentation.
Updates warning-message tests.

File	Description
`pyproject.toml`	Adds the Griffe deprecation extension.
`mkdocs.yml`	Configures generated deprecation admonitions.
`docs/_css/mkdocstrings.css`	Styles deprecated notices.
`docs/wrapping-guide/deprecation-and-compatibility.md`	Documents the new convention.
`src/frequenz/client/common/streaming/_event.py`	Documents enum-member deprecation.
`src/frequenz/client/common/proto/_datetime.py`	Updates converter deprecation.
`src/frequenz/client/common/pagination/proto/v1alpha8/_pagination_info.py`	Updates converter deprecation.
`src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_category.py`	Updates legacy converter notices.
`src/frequenz/client/common/microgrid/electrical_components/_state_code.py`	Documents enum-member deprecation.
`src/frequenz/client/common/microgrid/electrical_components/_diagnostic_code.py`	Documents enum-member deprecation.
`src/frequenz/client/common/microgrid/electrical_components/_category.py`	Documents category and member deprecations.
`src/frequenz/client/common/microgrid/components/__init__.py`	Updates `ComponentId` deprecation.
`src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py`	Updates legacy converter notices.
`src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py`	Updates bounds converter notices.
`src/frequenz/client/common/metrics/_sample.py`	Updates property and enum deprecations.
`src/frequenz/client/common/metrics/_metric.py`	Documents enum-member deprecation.
`src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py`	Updates converter deprecation.
`src/frequenz/client/common/grid/_delivery_area.py`	Documents delivery-area deprecations.
`tests/proto/test_datetime.py`	Updates exact warning assertion.
`tests/pagination/proto/v1alpha8/test_pagination_info.py`	Updates exact warning assertion.
`tests/metrics/test_sample_metric_sample.py`	Updates property warning assertion.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

daniel-zullo-frequenz

LGTM, there are a few comments from Copilot but I think most of them can be ignored. I'll approve it again once you've assessed/resolved the existing comments

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

The previous commit changed every deprecation notice in the repo but left the wrapping guide describing the old message form, `"<old FQCN> is deprecated. Use <new FQCN> instead."`, with no version and no cross-reference brackets. The guide is what a contributor reads before writing a new deprecation, so leaving it behind would reintroduce the old form. It now describes the form the code uses and why: the version in the sentence because a separate "since" line cannot be expressed through the decorator, the replacement as a bare `[name][]` cross-reference so the generated admonition links to it, no backticks because the same string is printed as a runtime warning, and implicit concatenation of single-line strings because a triple-quoted message carries its indentation into both the cross-reference and the terminal. The worked example is updated to match, and now escapes the brackets and dots in its `pytest.deprecated_call()` regex. That is easy to get wrong silently, because `match` is a search and an unescaped `[...]` is a character class that still matches something. Also added is the hand-written `Deprecated:` admonition for the cases the decorator cannot reach, which the guide never mentioned: an argument, an enum member, or construction being made stricter, all of which the repo now has. The `deprecated_member` paragraph says outright that the helper produces no admonition on its own, since that is the whole reason the members need one written by hand. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax · 2026-09-22T13:54:50Z

Updated, but I'm exploring an mkdocs extension so some of the fixes here are not necessary (like the duplicated deprecated_member() in enums requiring a duplicate Deprecated: admonition for the docs.

llucax added 2 commits September 21, 2026 12:41

llucax requested a review from a team as a code owner September 21, 2026 12:47

llucax requested review from Marenz and removed request for a team September 21, 2026 12:47

llucax self-assigned this Sep 21, 2026

llucax enabled auto-merge September 21, 2026 12:48

github-actions Bot added part:docs Affects the documentation part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) labels Sep 21, 2026

llucax disabled auto-merge September 21, 2026 12:54

llucax added the cmd:skip-release-notes It is not necessary to update release notes for this PR label Sep 21, 2026

llucax enabled auto-merge September 21, 2026 17:16

llucax requested a review from daniel-zullo-frequenz September 22, 2026 08:34

daniel-zullo-frequenz requested a balanced review from Copilot September 22, 2026 08:44

Copilot started reviewing on behalf of daniel-zullo-frequenz September 22, 2026 08:45 View session

Copilot AI reviewed Sep 22, 2026

View reviewed changes

daniel-zullo-frequenz reviewed Sep 22, 2026

View reviewed changes

llucax force-pushed the deprecated-admonitions branch from 8ef0237 to 9e5cd51 Compare September 22, 2026 13:47

llucax added 2 commits September 22, 2026 15:49

docs: Make every deprecation notice follow the deprecations guide

e57a2f1

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

llucax force-pushed the deprecated-admonitions branch from 9e5cd51 to 441e8ef Compare September 22, 2026 13:53

llucax disabled auto-merge September 22, 2026 13:54

llucax marked this pull request as draft September 22, 2026 13:55

Navigation Menu

Style deprecation notices in the API reference - #288

Style deprecation notices in the API reference#288
llucax wants to merge 4 commits into
frequenz-floss:v0.x.xfrom
llucax:deprecated-admonitions

llucax commented Sep 21, 2026 •

edited

Loading

Uh oh!

llucax commented Sep 21, 2026

Uh oh!

llucax commented Sep 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

daniel-zullo-frequenz left a comment

Uh oh!

llucax commented Sep 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

llucax commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

llucax commented Sep 21, 2026

Uh oh!

llucax commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

daniel-zullo-frequenz left a comment

Choose a reason for hiding this comment

Uh oh!

llucax commented Sep 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

llucax commented Sep 21, 2026 •

edited

Loading

llucax commented Sep 21, 2026 •

edited

Loading