Coverage for packages/workshop/src/livery/workshop/_release_notes.py: 100%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""Release notes: the one-answer query the release train writes notes through.
2
3A release stamps a version, and a package's history says what the
4version holds. The train never writes that history itself: it asks
5the provider the listed extensions answer the ``release-notes`` query
6with for the entry the unreleased commits earn, has the provider
7record it, and has it judge the recorded notes before a tag is cut. A
8workspace whose extensions answer nothing releases without notes, and
9the train says so where it would have written them.
10
11One answer at a time: the query combines by ``nearest``, so two
12listed extensions answering, neither requiring the other, refuse
13naming both.
14"""
15
16from __future__ import annotations(empty)
17
18from typing import TYPE_CHECKING, Protocol(empty)
19
20from livery.workshop._queries import Query, answer(empty)
21
22if TYPE_CHECKING:(empty)
23 from pathlib import Path
24
25 from livery.workshop._packages import Package
26
27
28class ReleaseNotes(Protocol):(empty)
29 """What a release-notes provider answers."""
30
31 def entry(self, root: Path, package: Package, version: str = "") -> str:(empty)
32 """The notes the commits since *package*'s last release earn.
33
34 Headed by *version* when one is given, as unreleased otherwise;
35 empty when nothing unreleased touches the package.
36 """
37 ...
38
39 def record(self, package: Package, version: str, entry: str) -> list[str]:(empty)
40 """Write *version*'s *entry* into *package*'s history.
41
42 An empty *entry* records a placeholder for a person to write.
43 Returns the files changed, each with a note for the reader,
44 empty when the history already holds the version's entry.
45 """
46 ...
47
48 def verify(self, package: Package, version: str) -> list[str]:(empty)
49 """The problems with *version*'s recorded notes; empty when sound."""
50 ...
51
52
53#: The release notes' provider, a workspace-level query the base
54#: declares; the extension that writes the history answers it with a
55#: function called with the workspace root.
56RELEASE_NOTES: Query[ReleaseNotes | None] = Query("release-notes")(empty)
57
58
59def release_notes(root: Path) -> ReleaseNotes | None:(empty)
60 """The provider the extensions listed at *root* answer; None when none answers.
61
62 The answer is imported when first asked, so a mount imports none
63 of the answering extension's code.
64
65 Raises:
66 QueryError: when two listed extensions answer and neither
67 requires the other, naming both.
68 """
69 return answer(root, RELEASE_NOTES)
70
71
72#: What the train prints where it would have written notes and has no provider.
73NO_PROVIDER = "no release notes: no listed extension writes them, so none are written"(empty)