Coverage for packages/workshop/src/livery/workshop/_composition.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"""Compose extensions on one package: its set, order, list and name.
2
3A package lists the extensions it is made of in its own
4``workshop.toml``. Its set is that list and every extension the list
5requires, transitively, whatever those extensions declare: requires
6alone composes a package. Two extensions that cannot share one are
7refused by the rules of the phase they both add steps to, two
8providers of one key or two owners of one executable, never by a rule
9over the pair.
10
11Composition order is the order a set mounts in and is named in: an
12extension comes after the extensions it requires, and ties go
13alphabetically. A package writes its set as the canonical list, the
14minimal one: no extension another member requires, in composition
15order. A combination is a set, named by its canonical list joined with
16``+``.
17
18Every function here but `extension_set` reads declarations through a
19lookup and imports nothing: [livery.workshop._extensions][] answers the
20lookup from what is installed, and a test from what it declares.
21[livery.workshop.extension_set][] is a package's set as the installed
22declarations compose it, which the base's readers and the extensions
23ask.
24"""
25
26from __future__ import annotations(empty)
27
28import heapq(empty)
29from collections.abc import Callable, Iterable(empty)
30from typing import TYPE_CHECKING, cast(empty)
31
32if TYPE_CHECKING:(empty)
33 from livery.workshop._declaration import Declaration
34 from livery.workshop._packages import Package
35
36#: How a name's declaration is found: None for an extension that no
37#: installed distribution declares.
38Lookup = Callable[[str], "Declaration | None"](empty)
39
40
41class OrderCycle(ValueError):(empty)
42 """A declared order with no first member: each one comes after another.
43
44 Attributes:
45 members: The extensions on the cycle, each before the next and
46 the last before the first.
47 """
48
49 def __init__(self, members: tuple[str, ...]) -> None:(empty)
50 self.members = members
51 super().__init__(
52 "the extensions' declared order has no start: "
53 + " before ".join((*members, members[0]))
54 + "; remove one requires among them"
55 )
56
57
58def requirements(name: str, lookup: Lookup) -> tuple[str, ...]:(empty)
59 """The extensions *name* declares it requires; none when nothing declares it."""
60 declared = lookup(name)
61 return declared.requires if declared is not None else ()
62
63
64def closure(names: Iterable[str], lookup: Lookup) -> tuple[str, ...]:(empty)
65 """*names* and every extension they require, transitively, first met first.
66
67 A list's set. A name the lookup finds no declaration for stays in
68 it and requires nothing: a sync installs it, and the mount names it
69 until then.
70 """
71 found: dict[str, None] = {}
72 pending = list(names)
73 while pending:
74 name = pending.pop(0)
75 if name not in found:
76 found[name] = None
77 pending.extend(requirements(name, lookup))
78 return tuple(found)
79
80
81#: Each list a package names, to the scan of the installed extensions it
82#: was composed against and the set it composed to.
83_SETS: dict[tuple[str, ...], tuple[object, tuple[str, ...]]] = {}(empty)
84
85
86def extension_set(package: Package) -> tuple[str, ...]:(empty)
87 """The extensions *package* holds: its list and every extension the list requires.
88
89 In composition order, as the installed declarations declare it:
90 each extension after the ones it requires, ties alphabetical, and
91 alphabetical while the declared order has no start. The list's own
92 order means nothing. Empty for a package that lists none. The
93 workspace's own tests ([livery.workshop.workspace_suite][]) hold the
94 root's set: the extensions ``[workspace] extensions`` lists and
95 every one they require, read from the root's contract on each call.
96 A step that names extensions judges a package whose set holds one
97 of them.
98
99 A list is composed once for each scan of the installed extensions,
100 so a scan taken after an install composes it again.
101 """
102 from livery.workshop._packages import WORKSPACE_TESTS
103
104 if package.path == WORKSPACE_TESTS:
105 from livery.workshop._extensions import root_set
106
107 return root_set(package.root)
108 listed = package.extensions
109 if not listed:
110 return ()
111 from livery.footman import installed_entry_points
112 from livery.workshop._extensions import installed_declaration
113
114 scan = installed_entry_points()
115 held = _SETS.get(listed)
116 if held is not None and held[0] is scan:
117 return held[1]
118 found = order_or_sorted(
119 closure(listed, installed_declaration), installed_declaration
120 )
121 _SETS[listed] = (scan, found)
122 return found
123
124
125def implied(names: Iterable[str], lookup: Lookup) -> frozenset[str]:(empty)
126 """Of the extensions *names* require, transitively, every one."""
127 found: set[str] = set()
128 for name in names:
129 found.update(closure(requirements(name, lookup), lookup))
130 return frozenset(found)
131
132
133def nearest_extensions(names: Iterable[str], lookup: object) -> tuple[str, ...]:(empty)
134 """Of the extensions *names*, the ones no other of them requires: the nearest.
135
136 The rule a query's ``nearest`` combine applies, for a combine
137 function that decides between answers by what each answering
138 extension requires, transitively. *lookup* is the one such a
139 function is called with, passed on as it came. The nearest come in
140 the order of *names*; two of them means neither requires the other.
141 Answers whose requires close a cycle leave none nearest, and
142 ``layering.graph`` names the cycle.
143 """
144 named = tuple(dict.fromkeys(names))
145 required = implied(named, cast("Lookup", lookup))
146 return tuple(name for name in named if name not in required)
147
148
149def order((empty)
150 names: Iterable[str],
151 lookup: Lookup,
152 *,
153 requires: bool = True,
154 edges: Iterable[tuple[str, str]] = (),
155) -> tuple[str, ...]:
156 """*names* in order: after what each requires and the *edges*, ties alphabetical.
157
158 A name outside *names* orders nothing.
159
160 Args:
161 names: The extensions to order.
162 lookup: Where each one's declaration is found.
163 requires: Whether a requirement comes first. A phase orders by
164 its context keys alone.
165 edges: Further ``(earlier, later)`` pairs, such as a phase's
166 context keys from provider to reader.
167
168 Raises:
169 OrderCycle: when the declared order has no start, naming the
170 members of one cycle.
171 """
172 members = sorted(set(names))
173 present = set(members)
174 waiting: dict[str, set[str]] = {name: set() for name in members}
175 if requires:
176 for name in members:
177 waiting[name].update(
178 other for other in requirements(name, lookup) if other in present
179 )
180 for earlier_name, later_name in edges:
181 if earlier_name in present and later_name in present:
182 waiting[later_name].add(earlier_name)
183 for name in members:
184 waiting[name].discard(name)
185 ready = [name for name in members if not waiting[name]]
186 heapq.heapify(ready)
187 done: list[str] = []
188 while ready:
189 name = heapq.heappop(ready)
190 done.append(name)
191 for other in members:
192 if name in waiting[other]:
193 waiting[other].discard(name)
194 if not waiting[other]:
195 heapq.heappush(ready, other)
196 if len(done) < len(members):
197 left = {name: waiting[name] for name in members if name not in done}
198 raise OrderCycle(cycle_of(left))
199 return tuple(done)
200
201
202def order_or_sorted(names: Iterable[str], lookup: Lookup) -> tuple[str, ...]:(empty)
203 """*names* in composition order, alphabetical when the order has no start.
204
205 For a reader that answers while a cycle in the declared order
206 stands: the sync that lets a person remove the cycle still runs, and
207 ``layering.graph`` names it.
208 """
209 members = tuple(dict.fromkeys(names))
210 try:
211 return order(members, lookup)
212 except OrderCycle:
213 return tuple(sorted(members))
214
215
216def cycle_of(waiting: dict[str, set[str]]) -> tuple[str, ...]:(empty)
217 """One cycle among *waiting*, each member before the next, the first alphabetical.
218
219 Every member left waits on another member left, so walking from
220 each to one it waits on returns to a name already walked.
221 """
222 walked: list[str] = []
223 name = min(waiting)
224 while name not in walked:
225 walked.append(name)
226 name = min(waiting[name])
227 cycle = walked[walked.index(name) :]
228 # The walk went from each member to one it comes after.
229 cycle.reverse()
230 start = cycle.index(min(cycle))
231 return tuple(cycle[start:] + cycle[:start])
232
233
234def canonical(listed: Iterable[str], lookup: Lookup) -> tuple[str, ...]:(empty)
235 """The minimal list of *listed*'s set, in composition order.
236
237 Raises:
238 OrderCycle: when the set's declared order has no start.
239 """
240 members = closure(listed, lookup)
241 required = implied(members, lookup)
242 return tuple(name for name in order(members, lookup) if name not in required)
243
244
245def combination(listed: Iterable[str], lookup: Lookup) -> str:(empty)
246 """The name of *listed*'s set: its canonical list joined with ``+``.
247
248 Raises:
249 OrderCycle: when the set's declared order has no start.
250 """
251 return "+".join(canonical(listed, lookup))