Coverage for packages/workshop/src/livery/workshop/_registries.py: 99%

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"""Where each artifact kind's registry lives: the resolution ladder.
2
3One resolution for every artifact kind the ecosystem publishes or
4probes, so no caller derives a registry address on its own. The
5ladder, per kind: the declaration wins (the env cascade's variables
6first, machine truth over committed; then the contract's
7``[registries]`` table), else the forge's own hosted registry of
8that kind, else the ecosystem default where one exists (pypi.org
9for python), else a refusal naming the kind and the rungs it tried.
10A declaration may be a local folder or share: every kind publishes
11to a path, so a workspace can work with no registry server at all.
12"""
13
14from __future__ import annotations
15
16import os
17from dataclasses import MISSING, dataclass, fields
18from pathlib import Path
19from typing import TYPE_CHECKING, cast
20
21from livery.footman import fail
22from livery.workshop._contract import load_contract
23
24if TYPE_CHECKING:
25 from collections.abc import Mapping
26
27 from livery.forge import RegistryKind
28
29#: The env cascade's declaration variables, per kind. The python
30#: pair predates the ladder and stays: addresses in the committed
31#: env are the machine-facing declaration the CI rung materialises.
32_ENV_VARS = {
33 "python": ("PYTHON_REGISTRY_URL", "PYTHON_PUBLISH_INDEX"),
34 "conan": ("CONAN_REMOTE_URL",),
35 "container": ("CONTAINER_REGISTRY",),
36}
37
38#: The ecosystem default, where one exists: the read index and the
39#: upload endpoint. The publish step refuses an empty address, so a
40#: deliberate PyPI publish arrives there as this rung's explicit URL;
41#: trusted publishing or a token carries the credential.
42_ECOSYSTEM = {
43 "python": ("https://pypi.org/simple", "https://upload.pypi.org/legacy/"),
44}
45
46#: The env cascade's credential variable, per kind. Read on every
47#: rung, because the credential is independent of where the address
48#: came from: a declared or default URL may still need auth. Secrets
49#: never ride the contract's [registries] table.
50_CREDENTIAL_VARS = {
51 "python": "PYTHON_REGISTRY_TOKEN",
52}
53
54
55@dataclass(frozen=True)
56class RegistryTarget:
57 """One resolved registry for one artifact kind.
58
59 Attributes:
60 kind: Which artifact registry this is.
61 url: The registry's address: the read index for python (the
62 publish endpoint is ``publish_url``), the remote for
63 conan, the reference prefix for container. A local path
64 when the declaration was a folder.
65 publish_url: Where python dists upload; empty means the
66 publisher's own default resolution (uv publish and
67 trusted publishing on pypi.org). Unused by other kinds.
68 local: True when the target is a folder or share rather
69 than a server.
70 releases: True when the artifacts ride the forge's own
71 releases, attached to each member's receipt tag. The
72 route a conan package takes on a forge that hosts no
73 conan registry; `url` is then the repository's page, for
74 printing.
75 token: The registry credential, for reads and uploads alike:
76 the kind's credential variable when set, else the forge
77 lane's token when the forge rung answered. Empty reads
78 anonymously and lets the publisher's own resolution
79 decide.
80 """
81
82 kind: str
83 url: str
84 publish_url: str = ""
85 local: bool = False
86 token: str = ""
87 releases: bool = False
88
89 @classmethod
90 def from_table(cls, table: Mapping[str, object]) -> RegistryTarget:
91 """The target a ``registry-target`` table holds.
92
93 The engine gives each step of the ``publish`` phase the registry
94 it resolved as the ``registry-target`` key: a table of this
95 class's fields by name, which the step reads back with this
96 constructor. The table holds ``kind`` and ``url``, and a field
97 it leaves out takes its default.
98
99 Args:
100 table: Each field of the target by its name.
101
102 Returns:
103 The target the table holds.
104
105 Raises:
106 ValueError: when the table is not a registry target: it has
107 no ``kind`` or no ``url``, a value has another type than
108 its field, or a key names no field. The message names
109 the field and what it takes, and never a value, since
110 ``token`` is a credential.
111 """
112 names = tuple(field.name for field in fields(cls))
113 unknown = [name for name in table if name not in names]
114 if unknown:
115 raise ValueError(
116 f"not a registry target: the table holds {', '.join(unknown)};"
117 f" a registry target holds {', '.join(names)}"
118 )
119 for field in fields(cls):
120 if field.default is MISSING and field.name not in table:
121 raise ValueError(
122 f"not a registry target: the table has no {field.name},"
123 " which every registry target holds"
124 )
125 return cls(
126 kind=_text(table, "kind"),
127 url=_text(table, "url"),
128 publish_url=_text(table, "publish_url"),
129 local=_flag(table, "local"),
130 token=_text(table, "token"),
131 releases=_flag(table, "releases"),
132 )
133
134
135def _text(table: Mapping[str, object], name: str) -> str:
136 """*table*'s string at *name*; empty when the table has none."""
137 value = table.get(name, "")
138 if not isinstance(value, str):
139 raise ValueError(_wrong_type(name, "str", value))
140 return value
141
142
143def _flag(table: Mapping[str, object], name: str) -> bool:
144 """*table*'s boolean at *name*; false when the table has none."""
145 value = table.get(name, False)
146 if not isinstance(value, bool):
147 raise ValueError(_wrong_type(name, "bool", value))
148 return value
149
150
151def _wrong_type(name: str, wanted: str, value: object) -> str:
152 """The refusal of a field whose value is not a *wanted*, naming no value."""
153 return (
154 f"not a registry target: {name} takes a {wanted}, and the table's"
155 f" {name} is of type {type(value).__name__}"
156 )
157
158
159def target_table(target: RegistryTarget) -> dict[str, object]:
160 """*target* as the ``publish`` phase's ``registry-target``: its fields by name."""
161 return {
162 "kind": target.kind,
163 "url": target.url,
164 "publish_url": target.publish_url,
165 "local": target.local,
166 "token": target.token,
167 "releases": target.releases,
168 }
169
170
171def _is_local(value: str) -> bool:
172 if value.startswith("file://"):
173 return True
174 return "://" not in value and (value.startswith(("/", "./", "~")) or ":\\" in value)
175
176
177def _normalise(value: str) -> str:
178 if value.startswith("file://"):
179 return value.removeprefix("file://")
180 return value
181
182
183def registry(root: Path, kind: str) -> RegistryTarget:
184 """The registry the workspace at *root* reads and publishes *kind* artifacts at.
185
186 *kind* is ``python``, ``conan`` or ``container``. The first rung
187 that names one wins: the environment's variables for the kind, the
188 contract's ``[registries]`` table, the forge's own registry of the
189 kind, then the ecosystem's default.
190
191 Raises:
192 Failed: when *kind* is not an artifact registry kind, naming
193 the three.
194 """
195 return resolve_registry(root, kind)
196
197
198def resolve_registry(root: Path, kind: str) -> RegistryTarget:
199 """The registry for *kind*, through the ladder; refusal teaches.
200
201 The rungs, in order: the env cascade's variables (machine truth
202 over committed declarations), the contract's ``[registries]``
203 table, the forge's own registry of the kind, the ecosystem
204 default. A python declaration may split read and publish
205 addresses; the other kinds carry one.
206 """
207 env_vars = _ENV_VARS.get(kind)
208 if env_vars is None:
209 fail(f"{kind!r} is not an artifact registry kind: python, conan, container")
210 token = os.environ.get(_CREDENTIAL_VARS.get(kind, ""), "")
211 declared_read = os.environ.get(env_vars[0], "")
212 declared_publish = os.environ.get(env_vars[1], "") if len(env_vars) > 1 else ""
213 if not declared_read and not declared_publish:
214 contract = load_contract(root / "workshop.toml")
215 table = contract.get("registries") or {}
216 entry = table.get(kind) if isinstance(table, dict) else None
217 if isinstance(entry, str):
218 declared_read = entry
219 elif isinstance(entry, dict):
220 declared_read = str(entry.get("url", ""))
221 declared_publish = str(entry.get("publish", ""))
222 if declared_read or declared_publish:
223 read = declared_read or declared_publish
224 if not token:
225 # A declaration naming the forge's own registry keeps the
226 # forge lane token: committing the address must not lose
227 # the credential the forge rung would have carried. A
228 # foreign address never inherits it.
229 resolved = _forge_registry(root, kind)
230 if resolved is not None:
231 forge_url, lane_token = resolved
232 if forge_url and (
233 read.startswith(forge_url) or declared_publish.startswith(forge_url)
234 ):
235 token = lane_token
236 return RegistryTarget(
237 kind=kind,
238 url=_normalise(read),
239 publish_url=_normalise(declared_publish),
240 local=_is_local(read),
241 token=token,
242 )
243 resolved = _forge_registry(root, kind)
244 if resolved is None and kind == "conan":
245 # A forge with no conan registry still has releases, and a
246 # conan package is a file: each member's caches ride its own
247 # receipt tag. The consumer reads them back through the same
248 # forge, so nothing outside the repository is involved.
249 return _forge_releases(root)
250 if resolved is not None:
251 forge_url, lane_token = resolved
252 if kind == "python":
253 # The forge-registry shape: the base takes uploads and
254 # serves the simple index under /simple.
255 return RegistryTarget(
256 kind=kind,
257 url=f"{forge_url}/simple",
258 publish_url=forge_url,
259 token=token or lane_token,
260 )
261 return RegistryTarget(kind=kind, url=forge_url, token=token or lane_token)
262 default = _ECOSYSTEM.get(kind)
263 if default is not None:263 ↛ 267line 263 didn't jump to line 267 because the condition on line 263 was always true
264 return RegistryTarget(
265 kind=kind, url=default[0], publish_url=default[1], token=token
266 )
267 fail(
268 f"no {kind} registry resolves: nothing declared (env or the"
269 " [registries] table), this forge hosts none, and the kind has"
270 " no ecosystem default. Declare one, a local folder included."
271 )
272
273
274def _forge_releases(root: Path) -> RegistryTarget:
275 """The conan target on a forge whose releases carry the caches.
276
277 The address is the repository itself: the publisher attaches each
278 host's saved cache to the member's release, and the probe reads
279 the same listing. The refusal names what to declare when this
280 workspace has no forge either.
281 """
282 from livery.workshop._forge_lane import this_repository
283 from livery.workshop._tokens import forge_token
284
285 contract = load_contract(root / "workshop.toml")
286 forge_table = contract.get("forge") or {}
287 try:
288 repository = this_repository(root)
289 except BaseException as error:
290 fail(
291 f"no conan registry resolves: nothing declared (env or the"
292 f" [registries] table), and this forge's releases did not"
293 f" answer either ({error}). Declare [registries.conan] in"
294 " workshop.toml, a local folder included."
295 )
296 token, _ = forge_token(
297 str(forge_table.get("kind", "")), str(forge_table.get("url", ""))
298 )
299 return RegistryTarget(
300 kind="conan",
301 url=repository.web_url(),
302 releases=True,
303 token=token,
304 )
305
306
307def _forge_registry(root: Path, kind: str) -> tuple[str, str] | None:
308 """The forge's registry of *kind* and the lane token, or None.
309
310 The token is the lane's own (``FORGE_TOKEN``, host-qualified
311 first), because the forge's registry authenticates with the same
312 credential as its API. It can be empty: a backend that resolves
313 its token through its own dialect never surfaces it here, and the
314 read then rides anonymously, which a public owner serves.
315 """
316 from livery.forge import Unsupported
317 from livery.workshop._forge_lane import this_forge
318 from livery.workshop._tokens import forge_token
319
320 contract = load_contract(root / "workshop.toml")
321 forge_table = contract.get("forge") or {}
322 owner = str(forge_table.get("owner", ""))
323 if not owner:
324 return None
325 try:
326 forge = this_forge(root)
327 except BaseException as error:
328 # No reachable forge is a rung that does not answer, not a
329 # resolution failure: the ladder continues, and the reason is
330 # printed rather than swallowed.
331 print(f" the forge rung did not answer: {error}")
332 return None
333 # resolve_registry validated the kind at its boundary; the cast
334 # states that proof for the checkers.
335 registry_kind = cast("RegistryKind", kind)
336 try:
337 url = forge.registry_url(registry_kind, owner)
338 except Unsupported:
339 return None
340 forge_kind = str(forge_table.get("kind", ""))
341 lane_token, _ = forge_token(forge_kind, str(forge_table.get("url", "")))
342 if not lane_token:
343 # The connection is the one source of the resolved
344 # credential: the backend read its own dialect variable at
345 # connect time, and the registry authenticates with the same
346 # lane.
347 lane_token = forge.token
348 return url, lane_token