1"""Read an extension's declaration file, ``extension.toml``, without importing it.
3An extension declares itself in one ``extension.toml``, beside the
4package its ``workshop.extensions`` entry point names: what it does, the
5workshop API version it is written for, its plugin, the extensions it
6requires, the
7phases it declares and the steps it adds to a package's lifecycle
8phases and to the gate's phases, the queries it declares and the ones
9it answers, the tools it runs, its CI jobs, the contract keys it owns,
10what it adds to another extension while that one is listed, and the
11shipped files of the base and of the extensions it requires that it
12replaces or deletes. The file is
13a contract, read as ``workshop.toml`` is: kebab-case keys, every key
14judged, every refusal naming the file. Every extension is one kind:
15the root's ``[workspace] extensions`` and a package's ``extensions``
16both list any of them, so the file says nothing about where it is
17listed.
19A ``[phases.<phase>]`` table declares the phase when it carries
20``level``, ``gated``, ``after``, ``verb`` or ``keys``
21([livery.workshop._phases.PhaseSpec][]), in the grammar the base's own
22contract file declares its phases in; a phase no declaration names
23refuses naming the declared ones. Beside those keys the table holds
24the phase's steps, and nothing else.
26A ``[queries.<name>]`` table declares the query when it carries
27``combine``, ``level``, ``default`` or ``values``
28([livery.workshop._queries.QuerySpec][]), in the grammar the base's own
29contract file declares its queries in; a table carrying ``value`` is a
30literal answer, and ``<name> = "module:function"`` under ``[queries]``
31answers by a function. An answer to a query no declaration names
32refuses naming the declared ones. A ``[for.<target>.queries]`` table
33answers in the same grammar, asked while the target is listed, and
34declares no query. A ``[for.<target>.fragments]`` table writes its files
35while the target is listed, and so are the files the extension ships
36under ``content/for/<target>/``; a directory there for a target the file
37declares no ``[for.<target>]`` table for refuses, naming both. A
38``[for.<target>.toolroom]`` table's ``requires`` names the tools the
39workspace requires while the table applies.
41A ``[templates.<name>]`` table declares a template, which
42``fm new.package.<name>`` creates a package from: its ``doc``, the
43``extensions`` such a package lists, ``extends``, the template whose
44files come first, its creation options under
45``[templates.<name>.options.<option>]`` (``TemplateOption``), and
46``fixes``, the answers it gives options of the templates it extends
47(``DeclaredTemplate``). The base declares its own in the same grammar,
48and a ``[for.<target>]`` table declares none: a template names the
49extensions it needs in its own ``extensions``, and a workspace offers
50it while its installed set holds the extension that declares it.
52``[extension] dormant-until`` names, as a verb, what another extension
53does for this one by declaring a ``[for.<this>]`` table: until a listed
54extension does, this one is dormant
55([livery.workshop._extensions.dormancy][]).
57An ``[env.<NAME>]`` table declares an environment variable the
58extension needs (``DeclaredVariable``): its ``value``, ``always``, and
59its ``doc``. A ``[for.<target>]`` table declares none, since a variable
60an extension needs does not depend on what else is listed.
62A step table's ``deletes`` names the steps of other extensions that
63never run for a package whose set holds this one, each
64``<owner>:<phase>.<step>`` to the reason: the base's, or those of an
65extension this one requires, or, in a ``[for.<target>]`` table, the
66target's, which the mount judges. A deletion naming no step an
67installed extension or the base declares, one naming a step that runs
68once over the workspace, and one without a reason refuse here.
70A step is declared at ``[phases.<phase>.<step>]`` and reads into one
71record whatever its phase's level
72([livery.workshop._steps.StepRecord][]): a workspace-level phase's
73steps register at mount, and a package-level phase's run over each
74package whose set holds the extension. ``fm check`` runs the tree
75side, so of a gated package-level phase, the build, a step serving
76the tree side registers at mount as well, and one serving the
77isolated side alone registers nothing. A step whose verdict is its
78tool's exit code is its tool's words (``main`` as a template, with
79``fix``, ``safe-fix``, ``env`` and ``matrix``), which the engine runs
80([livery.workshop._words.Command][]). Other behaviour is a reference,
81``"module:function"``, imported when it runs. The read imports
82nothing. A reference whose module is not in the extension's package,
83or whose module does not define the name at its top level, refuses
84here, read from the module's source.
85"""
102 from collections.abc import Callable, Mapping
104 from livery.workshop._contract_keys import ContractKind, Declared, Type
105 from livery.workshop._influence import Inputs
106 from livery.workshop._phases import PhaseContext, PhaseSpec
107 from livery.workshop._points import JobContribution
108 from livery.workshop._queries import QuerySpec
109 from livery.workshop._steps import StepRecord
110 from livery.workshop._words import Words
112#: The declaration file's name, beside the package an entry point names.
115#: The workshop API version a declaration takes when it names none.
118#: The contracts an extension may declare keys in.
123 """An extension's declaration file says something the workshop cannot take.
125 The extension's own mistake, which no sync repairs: the message
126 names the file, the key, and what it takes.
127 """
132 """A function a declaration names, ``"module:function"``, imported when it runs.
134 Attributes:
135 module: The module that defines it, in the extension's package.
136 name: The name the module defines it under, at its top level.
137 """
143 """The object the reference names, its module imported now."""
144 return getattr(importlib.import_module(self.module), self.name)
147 """Call the named function with *args* and *kwargs*, importing it first."""
148 return self.resolve()(*args, **kwargs)
151 """The reference as the declaration spells it."""
152 return f"{self.module}:{self.name}"
157 """A step's rewrite in code with a safe mode of its own, run as the record's fix.
159 Attributes:
160 fix: The function run under ``--fix``.
161 safe_fix: The function run under ``--safe-fix`` instead, which
162 removes no code.
163 """
169 """Run the mode the run asks for: the safe one under ``--safe-fix``."""
170 (self.safe_fix if ctx.safe else self.fix)(ctx)
173 """Both references, as the declaration spells them."""
174 return f"{self.fix} (safe-fix: {self.safe_fix})"
179 """What a declaration adds while it is mounted.
181 Attributes:
182 steps: The steps of the ``[phases.<phase>.<step>]`` tables the
183 mount registers, as records under the extension's name:
184 those of the workspace-level phases and those of the gated
185 package-level phases, less each that serves the isolated
186 side alone.
187 jobs: The CI jobs it adds to the builtin points, with their entries.
188 """
196 """A literal answer to a query: ``[queries.<name>] value = ...``.
198 Attributes:
199 value: The answer, as the file spells it.
200 """
207 """A file an extension's code writes: a ``[fragments."<target>"]`` table.
209 The file is written while the workspace's installed set holds the
210 extension, the root's list or a package's set, and withdrawn when
211 none does.
213 Attributes:
214 target: The file's path from the workspace root; a path ending
215 in ``/`` is a directory whose files the render names.
216 render: The function the workshop calls with the workspace root.
217 For a file it answers the text, or nothing for no file; for
218 a directory, each file's path under it to its text, or to
219 the shipped file or directory the file links to.
220 local: Whether the files belong to this checkout alone and are
221 never committed.
222 """
231 """An environment variable an extension needs: an ``[env.<NAME>]`` table.
233 The workshop sets it for every ``fm`` run, in a CI job's entry, in a
234 pass of the loop and in the scale fixture.
236 Attributes:
237 name: The variable's name.
238 value: Its value, as the file spells it. ``{place}`` in it
239 stands for a directory of the variable's own, which each
240 place the variable is set in names; no other brace form is
241 taken.
242 doc: What the variable is for.
243 always: Whether the value beats one the environment already
244 carries where an environment is formed for what runs inside
245 it: a CI job's, by its entry, a loop pass's and the scale
246 fixture's. Everywhere else, and without it, the
247 environment's value wins.
248 extension: The extension that declares it.
249 """
259 """Whether the value names ``{place}``, so it is set only where one is named."""
260 from livery.workshop._variables import PLACE_WORD
262 return PLACE_WORD in self.value
265 """The value with *place* where ``{place}`` stands."""
266 from livery.workshop._variables import PLACE_WORD
268 return self.value.replace(PLACE_WORD, place)
273 """An extension's declaration file, read and judged.
275 Attributes:
276 extension: The name the extension is listed by.
277 package: The package its entry point names, where its references live.
278 path: The declaration file.
279 description: What the extension does, in a sentence or two,
280 which the agent's guidance and the site's development pages
281 open its block with; empty for none.
282 api_version: The workshop API version it is written for.
283 plugin: The footman plugin carrying its verbs; empty for none.
284 requires: The extensions it cannot work without.
285 dormant_until: What another extension does for this one by
286 declaring a ``[for.<this>]`` table, a verb; empty for an
287 extension that is never dormant.
288 tools: The tools it runs, its verbs' and its steps', as
289 requirement strings.
290 additions: What it adds whenever it is mounted.
291 targets: What it adds to each target while the target is listed.
292 target_tables: Each ``[for.<target>]`` table as the file holds it.
293 tables: The file's top-level tables but ``[extension]`` and
294 ``[for]``, as the file holds them.
295 replaces: Each shipped file of the base or of an extension it
296 requires, ``<owner>:<name>``, its own file of that name
297 replaces, to the reason.
298 deletes: Each shipped file of the base or of an extension it
299 requires that it deletes, to the reason.
300 fragments: The files its code writes, by target.
301 target_fragments: The files each ``[for.<target>]`` table's code
302 writes, by target; a target whose table writes none is left
303 out.
304 target_tools: The tools each ``[for.<target>]`` table requires
305 under ``[toolroom] requires``, by target, as requirement
306 strings; a target whose table requires none is left out.
307 phase_specs: The phases it declares, by name.
308 phases: The steps its top-level ``[phases.<phase>.<step>]``
309 tables add, by phase, each the one step record whatever
310 the phase's level: a package-level phase's run through the
311 walk of a package's phase
312 ([livery.workshop._phases.walk_steps][]), and those the
313 mount registers are among ``additions`` too.
314 query_specs: The queries it declares, by name.
315 queries: The queries it answers, each query's name to the
316 function that answers it or to its literal answer.
317 target_queries: The queries each ``[for.<target>]`` table
318 answers, by target, in the shape of ``queries``; a target
319 whose table answers none is left out.
320 categories: The categories it gives its packages' paths, each
321 category to the patterns it takes, relative to the package.
322 templates: The templates it declares, by name, in the file's
323 order.
324 env: The environment variables it needs, in the file's order.
325 """
339 default_factory=dict[str, dict[str, Any]]
340 )
346 default_factory=dict[str, tuple[DeclaredOutput, ...]]
347 )
349 default_factory=dict[str, tuple[str, ...]]
350 )
353 default_factory=dict[str, tuple["StepRecord", ...]]
354 )
357 default_factory=dict[str, "Reference | DeclaredValue"]
358 )
360 default_factory=dict[str, "dict[str, Reference | DeclaredValue]"]
361 )
364 default_factory=dict[str, "DeclaredTemplate"]
365 )
373 """Where *package* lives, found without importing it; None when it is absent.
375 The directory that carries the declaration file when several hold
376 the package's parts, as a namespace's portions do. Found once per
377 import path, since a mount asks for each extension's several times;
378 an absence is never kept, so a package installed later is found.
379 """
380 key = (package, tuple(sys.path))
381 if key in _LOCATED:
382 return _LOCATED[key]
383 found = _locate(package)
384 if found is not None:
385 _LOCATED[key] = found
386 return found
390 try:
391 spec = importlib.util.find_spec(package)
392 except (ImportError, ValueError):
393 return None
394 if spec is None or not spec.submodule_search_locations:
395 return None
396 locations = [Path(location) for location in spec.submodule_search_locations]
397 for location in locations:
398 if (location / FILE).is_file():
399 return location
400 return locations[0]
404 """*package*'s declaration file; None when the package or its file is absent."""
405 found = directory(package)
406 if found is None or not (found / FILE).is_file():
407 return None
408 return found / FILE
411#: The tables whose keys the author names, a file or a query's answer or
412#: a shipped file's reference or an environment variable: their keys are
413#: data, never judged kebab-case.
415 ("phases", "*", "*", "fragments"),
416 ("for", "*", "phases", "*", "*", "fragments"),
417 ("phases", "*", "*", "env"),
418 ("for", "*", "phases", "*", "*", "env"),
419 ("phases", "*", "*", "replaces"),
420 ("phases", "*", "*", "deletes"),
421 ("replaces",),
422 ("for", "*", "replaces"),
423 ("deletes",),
424 ("for", "*", "deletes"),
425 ("queries", "*", "default"),
426 ("queries", "*", "value"),
427 ("for", "*", "queries", "*", "value"),
428 ("fragments",),
429 ("for", "*", "fragments"),
430 ("env",),
431)
435 """Each key under *table* spelled with an underscore that is not a name."""
436 from livery.workshop._contract_keys import shown
438 named = any(
439 len(pattern) == len(parts)
440 and all(want in ("*", part) for want, part in zip(pattern, parts, strict=True))
441 for pattern in _NAMED
442 )
443 found: list[str] = []
444 for key, value in table.items():
445 path = (*parts, key)
446 if "_" in key and not named:
447 found.append(shown(path))
448 if isinstance(value, dict):
449 found += _underscored(cast("dict[str, Any]", value), path)
450 elif isinstance(value, list):
451 for item in cast("list[object]", value):
452 if isinstance(item, dict):
453 found += _underscored(cast("dict[str, Any]", item), path)
454 return found
461 """*path*'s *text* parsed, its keys judged kebab-case; refused naming the file.
463 Parsed once per content: the result is kept by the text itself,
464 since a file rewritten within one tick of the clock keeps its
465 modification time.
466 """
467 key = (path, text)
468 if key not in _PARSED:
469 _PARSED[key] = _parse(path, text)
470 return _PARSED[key]
474 try:
475 data = tomllib.loads(text)
476 except tomllib.TOMLDecodeError as error:
477 raise DeclarationError(f"{path}: not valid TOML: {error}") from error
478 wrong = _underscored(data)
479 if wrong:
480 listed = ", ".join(
481 f"{key} (spell it {key.rpartition('.')[2].replace('_', '-')})"
482 for key in wrong
483 )
484 raise DeclarationError(f"{path}: keys are kebab-case; found {listed}")
485 return data
492 """*extension*'s declaration, from the file beside *package*; None without one.
494 A ``[for.<target>]`` table is read while an installed distribution
495 ships the target's declaration, since its steps and answers name
496 what the target declares; until then it adds nothing. Judged once
497 per content and per set of targets read: the result is kept by the
498 file's text and those targets.
500 Raises:
501 DeclarationError: when the file does not parse, a key is unknown
502 or of the wrong type, or a reference does not resolve.
503 """
504 from livery.workshop._extensions import ships_declaration
506 path = declaration_file(package)
507 if path is None:507 ↛ 508line 507 didn't jump to line 508 because the condition on line 507 was never true
508 return None
509 text = path.read_text("utf-8")
510 readable = frozenset(
511 str(target)
512 for target in _parsed(path, text).get("for", {})
513 if ships_declaration(str(target))
514 )
515 key = (extension, package, path, text, readable)
516 found = _CACHE.get(key)
517 if found is None:
518 found = _read(extension, package, path, text, readable)
519 _CACHE[key] = found
520 return found
524 extension: str, package: str, path: Path, text: str, readable: frozenset[str]
525) -> Declaration:
526 from livery.workshop._contract_keys import judge
528 data = _parsed(path, text)
529 reader = _Reader(extension, package, path)
530 problems = judge(data, contract="extension", where=str(path), listed=None)
531 if problems:
532 raise DeclarationError(
533 f"{path}:\n" + "\n".join(f" {line}" for line in problems)
534 )
535 reader.shipped_for(data)
536 own = phase_specs_of(data, path, extension=extension)
537 reader.specs = _known_phases(own, path)
538 own_queries = query_specs_of(data, path, extension=extension, package=package)
539 reader.query_specs = _known_queries(own_queries, path)
540 identity = data.get("extension", {})
541 phases = reader.steps(data, ())
542 additions = reader.additions(data, (), steps=phases)
543 # A [for.<target>] table names the phases and queries the target
544 # declares, so it is read while an installed distribution ships the
545 # target's declaration; until then it adds nothing.
546 held = {
547 str(target): table
548 for target, table in data.get("for", {}).items()
549 if str(target) in readable
550 }
551 targets = {
552 target: reader.additions(table, ("for", target))
553 for target, table in held.items()
554 }
555 contract_keys_of(data, path) # judged here as well, so a mount names it
556 templates = template_specs_of(data, path, extension=extension)
557 queries = reader.answers(data, ())
558 answered = {
559 target: reader.answers(table, ("for", target)) for target, table in held.items()
560 }
561 if "executables" in queries and not phases.get("run"):
562 raise reader.refuse(
563 ("queries", "executables"),
564 "names the executables fm run starts, and no [phases.run.<step>] starts"
565 " them; add a step to the run phase",
566 )
567 return Declaration(
568 extension,
569 package,
570 path,
571 description=str(identity.get("description", "")).strip(),
572 api_version=int(identity.get("api-version", API_VERSION)),
573 plugin=str(identity.get("plugin", "")),
574 requires=tuple(str(name) for name in identity.get("requires", ())),
575 dormant_until=str(identity.get("dormant-until", "")),
576 tools=tuple(str(text) for text in data.get("toolroom", {}).get("requires", ())),
577 additions=additions,
578 targets=targets,
579 target_tables={
580 str(target): dict(table) for target, table in data.get("for", {}).items()
581 },
582 tables={
583 key: value for key, value in data.items() if key not in ("extension", "for")
584 },
585 replaces={str(ref): str(why) for ref, why in data.get("replaces", {}).items()},
586 deletes={str(ref): str(why) for ref, why in data.get("deletes", {}).items()},
587 fragments=tuple(
588 reader.output(str(target), table)
589 for target, table in data.get("fragments", {}).items()
590 ),
591 target_fragments={
592 str(target): tuple(
593 reader.output(str(written), table, ("for", str(target)))
594 for written, table in held["fragments"].items()
595 )
596 for target, held in data.get("for", {}).items()
597 if held.get("fragments")
598 },
599 target_tools={
600 str(target): tuple(str(text) for text in held["toolroom"]["requires"])
601 for target, held in data.get("for", {}).items()
602 if held.get("toolroom", {}).get("requires")
603 },
604 phase_specs=own,
605 phases=phases,
606 query_specs=own_queries,
607 queries=queries,
608 target_queries={target: found for target, found in answered.items() if found},
609 categories=tuple(
610 (str(category), tuple(str(pattern) for pattern in patterns))
611 for category, patterns in data.get("categories", {}).items()
612 ),
613 templates=templates,
614 env=reader.variables(data),
615 )
619 """Build what one declaration file declares, refusing what does not resolve."""
622 self.extension = extension
623 self.package = package
624 self.path = path
625 #: The declared phases a table of this file may name: every
626 #: installed declaration's and this file's own.
627 self.specs: dict[str, PhaseSpec] = {}
628 #: The declared queries an answer in this file may name, the
629 #: same way.
630 self.query_specs: dict[str, QuerySpec] = {}
633 from livery.workshop._contract_keys import shown
635 return DeclarationError(f"{self.path}: {shown(where)} {text}")
638 """The declared phase *name* a ``[phases.<name>]`` table names.
640 Refuses one no declaration names, naming the declared ones and
641 the nearest spelling.
642 """
643 found = self.specs.get(name)
644 if found is None:
645 near = difflib.get_close_matches(name, list(self.specs), n=1)
646 hint = f"; did you mean {near[0]!r}?" if near else ""
647 raise self.refuse(
648 (*prefix, "phases", name),
649 f"names no phase; the phases are {', '.join(self.specs)}{hint}",
650 )
651 return found
654 self,
655 data: dict[str, Any],
656 prefix: tuple[str, ...],
657 *,
658 steps: Mapping[str, tuple[StepRecord, ...]] | None = None,
659 ) -> Additions:
660 """What *data* adds: the gate phases' steps and jobs.
662 The steps are those of the workspace-level phases among
663 *steps*, read from *data* when none are given, and those of the
664 gated package-level phases: the gate builds each package on the
665 build phase's tree side, so a build step serving that side
666 registers. A package-level phase the gate does not run, the
667 release's stamp or publish, runs its steps through the walk of
668 a package's phase and registers none. A step serving a phase's
669 isolated side alone registers nothing either: the gate runs the
670 tree side, and the release train runs that step through the
671 walk of the package's phase.
672 """
673 from livery.workshop._phases import WORKSPACE_LEVEL
675 found = steps if steps is not None else self.steps(data, prefix)
676 registered = [
677 record
678 for phase, records in found.items()
679 if self.specs[phase].level == WORKSPACE_LEVEL or self.specs[phase].gated
680 for record in records
681 if record.isolated is not True
682 ]
683 jobs: list[JobContribution] = []
684 for point, named in data.get("ci", {}).get("jobs", {}).items():
685 for name, entry in named.items():
686 jobs.append(
687 self.job(
688 str(point),
689 str(name),
690 entry,
691 (*prefix, "ci", "jobs"),
692 earlier=tuple(jobs),
693 )
694 )
695 return Additions(tuple(registered), tuple(jobs))
698 self,
699 point: str,
700 name: str,
701 entry: dict[str, Any],
702 prefix: tuple[str, ...],
703 *,
704 earlier: tuple[JobContribution, ...] = (),
705 ) -> JobContribution:
706 """The job *entry* adds to the builtin *point*, its functions resolved.
708 A table naming a job the point already has, declared,
709 inherited, contributed, or declared *earlier* in this file,
710 joins that job: its entries and plumbing become the job's on
711 this point. A join that ``gates`` refuses, since the verdict's
712 needs are the job's own. A join's ``needs`` join the needs of a
713 job the point has of its own; on a job the point inherits they
714 refuse, since that job's needs are the point's it inherits
715 from, whose runs never have the joining point's jobs. A job
716 naming ``labels`` fans out to one leg per runner label the
717 function names (a ``runners`` matrix). ``judges`` names the
718 tasks that judge the run before the verdict, on a join of a
719 point's own verdict job alone; on any other job they refuse
720 ([livery.workshop._points.judges_refusal][]).
721 """
722 from livery.workshop._points import (
723 DECLARED,
724 Entry,
725 Job,
726 JobContribution,
727 contributed_jobs,
728 judges_refusal,
729 point_has_job,
730 )
732 where = (*prefix, point, name)
733 builtin = {declared.name: declared for declared in DECLARED}
734 if point not in builtin:
735 raise self.refuse(
736 where,
737 f"names the point {point!r}, which is not builtin; a job joins"
738 f" one of {', '.join(builtin)}",
739 )
740 lineage = (point, builtin[point].inherits)
741 joins = point_has_job(point, name) or any(
742 item.point in lineage and item.job.name == name for item in earlier
743 )
744 if "judges" in entry and (why := judges_refusal(point, name)):
745 raise self.refuse((*where, "judges"), why)
746 if joins and entry.get("gates"):
747 raise self.refuse(
748 (*where, "gates"),
749 f"joins the {point} point's {name} job and gates; a join adds"
750 " entries and plumbing, and the verdict's needs stay the job's own",
751 )
752 own = {job.name for job in builtin[point].jobs}
753 own |= {item.job.name for item in contributed_jobs(point)}
754 own |= {
755 item.job.name
756 for item in earlier
757 if item.point == point and not item.job.joins
758 }
759 if joins and "needs" in entry and name not in own:
760 parent = builtin[point].inherits
761 raise self.refuse(
762 (*where, "needs"),
763 f"joins the {name} job the {point} point inherits from the"
764 f" {parent} point; that job waits for the {parent} point's jobs"
765 " alone, so a join of it names no needs",
766 )
767 labels = (
768 self.reference(entry["labels"], (*where, "labels"))
769 if "labels" in entry
770 else None
771 )
772 job = Job(
773 name,
774 matrix="runners" if labels is not None else "",
775 labels=labels,
776 needs=tuple(str(need) for need in entry.get("needs", ())),
777 fetch=str(entry.get("fetch", "")),
778 token=str(entry.get("token", "")),
779 installs=self.reference(entry["installs"], (*where, "installs"))
780 if "installs" in entry
781 else None,
782 conan_cache=bool(entry.get("conan-cache", False)),
783 deploy=self.reference(entry["deploy"], (*where, "deploy"))
784 if "deploy" in entry
785 else None,
786 publishes=str(entry.get("publishes", "")),
787 paths=tuple(str(path) for path in entry.get("paths", ())),
788 collects=str(entry.get("collects", "")),
789 inputs=self.inputs(entry["inputs"], (*where, "inputs"))
790 if "inputs" in entry
791 else None,
792 note=str(entry.get("note", "")),
793 joins=joins,
794 )
795 return JobContribution(
796 point,
797 job,
798 entries=tuple(
799 Entry(point, name, str(task), source=self.extension)
800 for task in entry.get("entries", ())
801 )
802 + tuple(
803 Entry(point, name, str(task), source=self.extension, judges=True)
804 for task in entry.get("judges", ())
805 ),
806 gates=bool(entry.get("gates", False)),
807 extension=self.extension,
808 )
811 self, data: dict[str, Any], prefix: tuple[str, ...]
812 ) -> dict[str, tuple[StepRecord, ...]]:
813 """Every step *data*'s ``[phases.<phase>.<step>]`` tables declare, by phase.
815 A phase with no step is left out. A step of a package-level
816 phase runs over the packages whose set holds the extension.
817 """
818 found: dict[str, tuple[StepRecord, ...]] = {}
819 for phase, table in data.get("phases", {}).items():
820 self.spec(str(phase), prefix)
821 named = _step_tables(table)
822 if not named:
823 continue
824 found[str(phase)] = tuple(
825 self.step(str(phase), step, entry, (*prefix, "phases"))
826 for step, entry in named.items()
827 )
828 return found
831 self, phase: str, step: str, entry: dict[str, Any], prefix: tuple[str, ...]
832 ) -> StepRecord:
833 """The step ``[phases.<phase>.<step>]`` declares: a record placing its paths.
835 ``main`` is the body: a template, the tool's name as ``tools``
836 names it then its arguments, or a reference to its code,
837 ``module:function``; ``fix`` and ``safe-fix`` take the body's
838 shape. A template narrows by the paths the run reaches when
839 ``{paths}`` stands among its words and runs whole without it,
840 and takes the words after ``--`` where ``{arguments}`` stands.
841 A step in code places neither, so its record says what its code
842 does: a workspace step that declares no ``inputs`` narrows by
843 the packages the run reaches, which its code asks
844 [livery.workshop.scoped_packages][] for, and one with ``inputs``
845 is selected by them and judges the whole; a step that names
846 ``tools`` wraps them and takes the words after ``--``, and one
847 that names none refuses them. ``isolated`` names the side of the
848 phase the step serves, and refuses on a step of a phase whose
849 declaration gives no ``isolated`` key.
850 """
851 from dataclasses import replace
853 from livery.workshop._phases import ISOLATED, PACKAGE_LEVEL
854 from livery.workshop._steps import NONE, PACKAGE, PACKAGES, PATHS, WORKSPACE
856 where = (*prefix, phase, step)
857 if ISOLATED in entry and ISOLATED not in self.specs[phase].keys:
858 raise self.refuse(
859 (*where, ISOLATED),
860 f"is not read on a step of the {phase} phase, which has one side:"
861 " its declaration gives no isolated key",
862 )
863 run, fix, words = self.step_bodies(entry, where)
864 provides, reads = self.context_keys(entry, where, "another step")
865 others = {
866 key: self.other_steps(entry.get(key, {}), (*where, key))
867 for key in ("replaces", "deletes")
868 }
869 for address, _reason in others["deletes"]:
870 self.deletion(address, (*where, "deletes", address))
871 record = self.record(step, phase, entry, where, run, fix, words)
872 if self.specs[phase].level == PACKAGE_LEVEL:
873 # The phase's level says how often the step runs: once per
874 # package whose set holds the extension.
875 for key in ("scope", "extensions"):
876 if key in entry:
877 raise self.refuse(
878 (*where, key),
879 f"is not read on a step of the {phase} phase, which runs"
880 " once per package whose set holds the extension, as the"
881 " phase's level says",
882 )
883 record = replace(record, scope=PACKAGE, extensions=(self.extension,))
884 if words is not None:
885 named = words.placeholders()
886 narrowing = PATHS if "paths" in named else NONE
887 arguments = "arguments" in named
888 else:
889 narrowing = (
890 PACKAGES
891 if record.scope == WORKSPACE and record.inputs is None
892 else NONE
893 )
894 arguments = bool(record.tools)
895 return replace(
896 record,
897 narrowing=narrowing,
898 arguments=arguments,
899 enabled=bool(entry.get("enabled", True)),
900 provides=tuple(provides.items()),
901 reads=reads,
902 isolated=None if "isolated" not in entry else bool(entry["isolated"]),
903 replaces=others["replaces"],
904 deletes=others["deletes"],
905 )
908 self, table: dict[str, Any], where: tuple[str, ...]
909 ) -> tuple[tuple[str, str], ...]:
910 """The steps of other extensions *table* names, each to the reason it states.
912 A step is ``<owner>:<phase>.<step>``, and the reason is a line
913 of text; a step named with no reason refuses.
914 """
915 found: list[tuple[str, str]] = []
916 for text, reason in table.items():
917 if not _step_address(text):
918 raise self.refuse(
919 where,
920 f"names {text!r}; a step of another extension is"
921 " <owner>:<phase>.<step>",
922 )
923 if not str(reason).strip():
924 raise self.refuse(
925 (*where, text),
926 "states no reason; a step names each step it replaces or"
927 " deletes with the reason",
928 )
929 found.append((text, str(reason)))
930 return tuple(found)
933 """Refuse a deletion of a step nothing installed declares, or of a workspace's.
935 A deletion takes a step off each package whose set holds this
936 extension, so it names a step that runs once per package.
937 """
938 from livery.workshop._steps import PACKAGE
940 steps = installed_steps()
941 scope = steps.get(address)
942 if scope is None:
943 phase = address.partition(":")[2].partition(".")[0]
944 held = sorted(
945 other
946 for other in steps
947 if other.partition(":")[2].partition(".")[0] == phase
948 )
949 listed = (
950 f"the {phase} phase's are {', '.join(held)}"
951 if held
952 else f"the {phase} phase has none"
953 )
954 raise self.refuse(
955 where,
956 f"names no step an installed extension or the base declares; {listed}",
957 )
958 if scope != PACKAGE:
959 raise self.refuse(
960 where,
961 "names a step that runs once over the workspace; a deletion takes"
962 " a step off each package whose set holds this extension, so it"
963 " names a step that runs once per package",
964 )
967 self,
968 step: str,
969 phase: str,
970 entry: dict[str, Any],
971 where: tuple[str, ...],
972 run: Callable[[PhaseContext], None],
973 fix: Callable[[PhaseContext], None] | None,
974 words: Words | None,
975 ) -> StepRecord:
976 """The record from a step table's shared keys, its body resolved.
978 ``scope``, ``claims``, ``extensions``, ``options``, ``fragments``,
979 ``inputs``, ``after``, ``tools``, ``tests-only``, ``flags`` and
980 ``outputs``;
981 ``step`` sets the step's own fields after.
982 """
983 from livery.workshop._fragments import verify
984 from livery.workshop._steps import Claim, Option, StepRecord
986 claims: list[Claim] = []
987 for index, claim in enumerate(entry.get("claims", ())):
988 if "category" not in claim:
989 raise self.refuse(
990 (*where, f"claims[{index}]"), "names no category: a claim has one"
991 )
992 claims.append(
993 Claim(
994 str(claim["category"]),
995 ignore=tuple(claim.get("ignore", ())),
996 suffixes=tuple(claim.get("suffixes", ())),
997 )
998 )
999 inputs = (
1000 self.inputs(entry["inputs"], (*where, "inputs"))
1001 if "inputs" in entry
1002 else None
1003 )
1004 record = StepRecord(
1005 step,
1006 phase,
1007 run,
1008 scope=str(entry.get("scope", "workspace")),
1009 fix=fix,
1010 words=words,
1011 extensions=tuple(str(name) for name in entry.get("extensions", ())),
1012 tests_only=bool(entry.get("tests-only", False)),
1013 after=tuple(entry.get("after", ())),
1014 extension=self.extension,
1015 tools=tuple(entry.get("tools", ())),
1016 options=tuple(
1017 Option(
1018 str(name),
1019 str(option.get("type", "")),
1020 option.get("default"),
1021 str(option.get("doc", "")),
1022 )
1023 for name, option in entry.get("options", {}).items()
1024 ),
1025 fragments=self.fragments(entry.get("fragments", {}), (*where, "fragments")),
1026 claims=tuple(claims),
1027 flags=tuple(entry.get("flags", ())),
1028 inputs=inputs,
1029 outputs=self.outputs(entry.get("outputs", ()), (*where, "outputs")),
1030 )
1031 for option in record.options:
1032 if option.kind not in ("bool", "str", "int", "strs"):1032 ↛ 1033line 1032 didn't jump to line 1033 because the condition on line 1032 was never true
1033 raise self.refuse(
1034 (*where, "options", option.name, "type"),
1035 "is required: bool, str, int or strs",
1036 )
1037 try:
1038 verify(record.fragments, record.name)
1039 except ValueError as error:
1040 raise self.refuse((*where, "fragments"), f"refuses: {error}") from error
1041 return record
1044 """The paths a step declares it writes, each below the root and never docs/.
1046 Refuses an output that leaves the root, names the root or a
1047 package itself, or names ``docs/`` itself, which holds the
1048 authored pages.
1049 """
1050 from livery.workshop._phases import output_refusal
1052 for output in listed:
1053 refusal = output_refusal(output)
1054 if refusal:
1055 raise self.refuse(where, refusal)
1056 return tuple(listed)
1059 self, entry: dict[str, Any], where: tuple[str, ...]
1060 ) -> tuple[
1061 Callable[[PhaseContext], None],
1062 Callable[[PhaseContext], None] | None,
1063 Words | None,
1064 ]:
1065 """A step's main and fix, from its template or from references to its code.
1067 ``main`` is a list, the template, or a string, the reference;
1068 ``fix`` and ``safe-fix`` take its shape, and ``env`` and
1069 ``matrix`` vary a template's calls alone. ``{paths}`` and
1070 ``{arguments}`` each stand alone as one word of a template.
1071 """
1072 from livery.workshop._words import PATHS_WORD, PLACED, Command
1074 if "main" not in entry:
1075 raise self.refuse(
1076 where,
1077 "names no main: a step's body is a template, the tool's name then"
1078 " its arguments, or a reference to its code, module:function",
1079 )
1080 if isinstance(entry["main"], list):
1081 words = self.words(entry, where)
1082 spelled = [
1083 ("main", words.judge),
1084 ("fix", words.fix),
1085 ("safe-fix", words.safe_fix),
1086 ("env", tuple(value for _name, value in words.env)),
1087 ]
1088 for key, texts in spelled:
1089 for text in texts:
1090 for placed in PLACED:
1091 if placed in text and text != placed:
1092 goes = (
1093 "the run's paths"
1094 if placed == PATHS_WORD
1095 else "the words after --"
1096 )
1097 raise self.refuse(
1098 (*where, key),
1099 f"names {placed} in {text!r}; it stands alone as one"
1100 f" word, where {goes} go",
1101 )
1102 name = f"{where[-2]}.{where[-1]}"
1103 fixing = Command(words, name, fixing=True) if words.fix else None
1104 return Command(words, name), fixing, words
1105 for key in ("env", "matrix"):
1106 if key in entry:
1107 raise self.refuse(
1108 (*where, key),
1109 "belongs to a step in words, and this one runs code; declare"
1110 " main as words, the tool's name then its arguments, or drop"
1111 " the key",
1112 )
1113 for key in ("fix", "safe-fix"):
1114 if key in entry and not isinstance(entry[key], str):
1115 raise self.refuse(
1116 (*where, key),
1117 "is words, and main is a reference to code: a step that runs"
1118 " code fixes with code, module:function",
1119 )
1120 if "safe-fix" in entry and "fix" not in entry:
1121 raise self.refuse(
1122 (*where, "safe-fix"),
1123 "is declared without fix: a step that fixes safely fixes too",
1124 )
1125 coded: Callable[[PhaseContext], None] | None = None
1126 if "fix" in entry:
1127 fix = self.reference(entry["fix"], (*where, "fix"))
1128 coded = fix
1129 if "safe-fix" in entry:
1130 coded = CodedFix(
1131 fix, self.reference(entry["safe-fix"], (*where, "safe-fix"))
1132 )
1133 return self.reference(entry["main"], (*where, "main")), coded, None
1136 """The words *entry* declares: its main, fix, safe-fix, env and matrix."""
1137 from livery.workshop._words import Words
1139 def argv(key: str) -> tuple[str, ...]:
1140 value = entry.get(key, [])
1141 if isinstance(value, str):
1142 raise self.refuse(
1143 (*where, key),
1144 f"is {value!r}, a reference to code; in a step in words,"
1145 f" {key} is words: the tool's name, then its arguments",
1146 )
1147 return tuple(str(word) for word in value)
1149 judge, fix, safe_fix = argv("main"), argv("fix"), argv("safe-fix")
1150 if not judge:
1151 raise self.refuse((*where, "main"), "is empty: the tool's name comes first")
1152 if safe_fix and not fix:
1153 raise self.refuse(
1154 (*where, "safe-fix"),
1155 "is declared without fix: a step that fixes safely fixes too",
1156 )
1157 for key, value in (("fix", fix), ("safe-fix", safe_fix)):
1158 if value and value[0] != judge[0]:
1159 raise self.refuse(
1160 (*where, key),
1161 f"runs {value[0]}, and main runs {judge[0]}: a step runs one tool",
1162 )
1163 matrix: list[tuple[str, tuple[str, ...]]] = []
1164 for key, values in entry.get("matrix", {}).items():
1165 if not values:
1166 raise self.refuse(
1167 (*where, "matrix", key),
1168 "has no values: a matrix key runs one call per value",
1169 )
1170 matrix.append((str(key), tuple(str(value) for value in values)))
1171 env = tuple(
1172 (str(name), str(value)) for name, value in entry.get("env", {}).items()
1173 )
1174 return Words(judge, fix, safe_fix, env, tuple(matrix))
1177 self, table: dict[str, Any], where: tuple[str, ...]
1178 ) -> tuple[Any, ...]:
1179 """A project file's fragment from its text; a package file's, its extensions."""
1180 from livery.workshop._fragments import Fragment
1182 found: list[Fragment] = []
1183 for file, value in table.items():
1184 if isinstance(value, str):
1185 found.append(Fragment(file, value))
1186 continue
1187 entry = cast("dict[str, Any]", value)
1188 if "text" not in entry or not entry.get("extensions"):
1189 raise self.refuse(
1190 (*where, file),
1191 "is a package file's fragment: its text, and the extensions"
1192 " whose packages render it",
1193 )
1194 extensions = tuple(str(name) for name in entry["extensions"])
1195 found.append(Fragment(file, str(entry["text"]), extensions=extensions))
1196 return tuple(found)
1199 self, target: str, table: dict[str, Any], prefix: tuple[str, ...] = ()
1200 ) -> DeclaredOutput:
1201 """The file *target* names, written by the render its table references.
1203 *prefix* is the ``[for.<target>]`` table the fragment is under,
1204 empty for the top level.
1205 """
1206 where = (*prefix, "fragments", target)
1207 if "render" not in table:
1208 raise self.refuse(
1209 where,
1210 "names no render; a fragment's code is render = 'module:function'",
1211 )
1212 return DeclaredOutput(
1213 target,
1214 self.reference(table["render"], (*where, "render")),
1215 local=bool(table.get("local", False)),
1216 )
1219 """The environment variables *data*'s ``[env]`` table declares, in its order.
1221 The schema judged the types of ``value``, ``doc`` and ``always``
1222 before this read. Refuses a name no shell exports, a missing
1223 ``value`` or ``doc``, an empty ``doc``, a value holding a line
1224 break, and a brace form in the value other than ``{place}``,
1225 naming it: so a later placeholder never changes what a declared
1226 value means.
1227 """
1228 from livery.workshop._variables import NAME, PLACE_WORD, unanswered
1230 found: list[DeclaredVariable] = []
1231 for name, table in data.get("env", {}).items():
1232 where = ("env", str(name))
1233 if not NAME.fullmatch(str(name)):
1234 raise self.refuse(
1235 where,
1236 "is no variable name: letters, digits and underscores, not"
1237 " starting with a digit, as a shell exports one",
1238 )
1239 entry = cast("dict[str, Any]", table)
1240 for key, what in (
1241 ("value", "the variable's value"),
1242 ("doc", "what the variable is for"),
1243 ):
1244 if key not in entry:
1245 raise self.refuse((*where, key), f"is missing: {what}")
1246 value, doc = str(entry["value"]), str(entry["doc"]).strip()
1247 if not doc:
1248 raise self.refuse(
1249 (*where, "doc"), "is empty: say what the variable is for"
1250 )
1251 if "\n" in value or "\r" in value:
1252 raise self.refuse(
1253 (*where, "value"), "holds a line break, which no export can carry"
1254 )
1255 wrong = unanswered(value)
1256 if wrong:
1257 raise self.refuse(
1258 (*where, "value"),
1259 f"names {', '.join(wrong)}, which an [env] value does not"
1260 f" answer; it answers {PLACE_WORD} alone, a directory of the"
1261 " variable's own",
1262 )
1263 found.append(
1264 DeclaredVariable(
1265 str(name),
1266 value,
1267 doc,
1268 always=bool(entry.get("always", False)),
1269 extension=self.extension,
1270 )
1271 )
1272 return tuple(found)
1275 """Refuse ``content/for/<target>/`` for a target with no ``[for]`` table.
1277 The files under it are delivered while the extension contributes
1278 to the target, which a ``[for.<target>]`` table declares, so a
1279 directory for a target the file declares nothing for would never
1280 be delivered: a misspelled target, or a table that went.
1281 """
1282 from livery.workshop._contract_keys import shown
1284 shipped = self.path.parent / "content" / "for"
1285 if not shipped.is_dir():
1286 return
1287 declared = data.get("for", {})
1288 for held in sorted(shipped.iterdir()):
1289 if held.is_dir() and held.name not in declared:
1290 raise DeclarationError(
1291 f"{self.path}: content/for/{held.name}/ ships files for"
1292 f" {held.name}, and the file declares no"
1293 f" [{shown(('for', held.name))}] table; declare one, or"
1294 " move the files"
1295 )
1298 self, table: dict[str, Any], where: tuple[str, ...], provider: str
1299 ) -> tuple[dict[str, str], tuple[str, ...]]:
1300 """The context keys *table* provides, each to its type, and reads.
1302 A key in both refuses, naming *provider* as who provides what a
1303 step reads.
1304 """
1305 provides = {
1306 str(key): str(kind) for key, kind in table.get("provides", {}).items()
1307 }
1308 reads = tuple(str(key) for key in table.get("reads", ()))
1309 both = sorted(set(provides) & set(reads))
1310 if both:
1311 raise self.refuse(
1312 (*where, "reads"),
1313 f"names {', '.join(both)}, which its provides names too; a step"
1314 f" reads what {provider} provides",
1315 )
1316 return provides, reads
1319 self, data: dict[str, Any], prefix: tuple[str, ...]
1320 ) -> dict[str, Reference | DeclaredValue]:
1321 """The queries *data*'s ``[queries]`` table answers, each to its answer.
1323 Under a ``[for.<target>]`` table, *prefix*, a table that declares
1324 a query refuses: a declaration holds whatever is listed, so it
1325 belongs to the file's top level.
1326 """
1327 from livery.workshop._contract_keys import shown
1329 found: dict[str, Reference | DeclaredValue] = {}
1330 for name, value in data.get("queries", {}).items():
1331 if not _declares_query(value):
1332 found[str(name)] = self.query(str(name), value, prefix)
1333 elif prefix:
1334 raise self.refuse(
1335 (*prefix, "queries", str(name)),
1336 "declares a query, and a [for] table only answers one; declare"
1337 f" it at the top level, [{shown(('queries', str(name)))}]",
1338 )
1339 return found
1342 self, name: str, value: object, prefix: tuple[str, ...] = ()
1343 ) -> Reference | DeclaredValue:
1344 """The answer to the query *name*: a function, resolved, or a literal.
1346 The name is a declared query. A workspace-level query is asked
1347 of every extension the workspace mounts, a package-level one of
1348 each extension a package's set holds, so any extension answers
1349 either. A literal answer is one of the query's values when it
1350 declares them. *prefix* is the ``[for.<target>]`` table the
1351 answer is under, empty for the top level.
1352 """
1353 where = (*prefix, "queries", name)
1354 spec = self.query_specs.get(name)
1355 if spec is None:
1356 near = difflib.get_close_matches(name, list(self.query_specs), n=1)
1357 hint = f"; did you mean {near[0]!r}?" if near else ""
1358 raise self.refuse(
1359 where,
1360 f"names no query; the queries are {', '.join(self.query_specs)}{hint}",
1361 )
1362 if isinstance(value, dict):
1363 table = cast("dict[str, Any]", value)
1364 if "value" not in table:
1365 raise self.refuse(
1366 where,
1367 "is a table without value; an answer is 'module:function', or"
1368 " a table with value alone",
1369 )
1370 held: object = table["value"]
1371 if spec.values is not None and held not in spec.values:
1372 listed = ", ".join(repr(known) for known in spec.values)
1373 raise self.refuse(
1374 (*where, "value"),
1375 f"is {held!r}; the query's values are {listed}",
1376 )
1377 return DeclaredValue(held)
1378 return self.reference(value, where)
1381 """The files a workspace step or a job reads, from its ``inputs`` table."""
1382 from livery.workshop._influence import Inputs
1384 if "reads" not in table:
1385 raise self.refuse(where, "names no reads: inputs name the files it reads")
1386 return Inputs(
1387 reads=tuple(table["reads"]),
1388 per_file=bool(table.get("per-file", True)),
1389 widens=tuple(table.get("widens", ())),
1390 on_removal=bool(table.get("on-removal", False)),
1391 widen=self.reference(table["widen"], (*where, "widen"))
1392 if "widen" in table
1393 else None,
1394 ignores=tuple(table.get("ignores", ())),
1395 )
1398 """The reference *text* spells, resolved against the package's sources."""
1399 module, colon, name = str(text).partition(":")
1400 if not colon or not module or not name.isidentifier():
1401 raise self.refuse(where, f"is {text!r}; a reference is 'module:function'")
1402 if module != self.package and not module.startswith(f"{self.package}."):
1403 raise self.refuse(
1404 where,
1405 f"names {module}, outside the extension's package {self.package};"
1406 " a reference names the extension's own code",
1407 )
1408 source = self.source(module)
1409 if source is None:
1410 raise self.refuse(
1411 where, f"names {module}, which {self.package} does not contain"
1412 )
1413 defined = top_level_names(source)
1414 if name not in defined:
1415 near = difflib.get_close_matches(name, sorted(defined), n=1)
1416 hint = f"; did you mean {near[0]!r}?" if near else ""
1417 raise self.refuse(
1418 where,
1419 f"names {name}, which {module} does not define at its top level{hint}",
1420 )
1421 return Reference(module, name)
1424 """*module*'s source file beside the declaration; None when it is absent."""
1425 parts = [part for part in module[len(self.package) :].split(".") if part]
1426 base = self.path.parent.joinpath(*parts)
1427 candidates = [base / "__init__.py"]
1428 if parts:1428 ↛ 1430line 1428 didn't jump to line 1430 because the condition on line 1428 was always true
1429 candidates.insert(0, base.with_suffix(".py"))
1430 return next((path for path in candidates if path.is_file()), None)
1433#: The keys that declare a phase in its ``[phases.<phase>]`` table,
1434#: beside which a sub-table is a step.
1439 data: dict[str, Any], path: Path, *, extension: str
1440) -> dict[str, PhaseSpec]:
1441 """The phases *data*'s ``[phases.<phase>]`` tables declare, judged, by name.
1443 A table declares its phase when it carries ``level``, ``gated``,
1444 ``after``, ``verb`` or ``keys``; one that adds steps alone declares
1445 nothing. The same reader serves the base's contract file and an
1446 extension's declaration file, *extension* naming the declarer.
1448 Raises:
1449 DeclarationError: when a declaration is off its shape: a level
1450 that is not ``package`` or ``workspace``, a key of a type
1451 no context value has, or a value of the wrong type.
1452 """
1453 from livery.workshop._contract_keys import shown
1454 from livery.workshop._phases import LEVELS, PACKAGE_LEVEL, TYPES, PhaseSpec
1456 def refuse(where: tuple[str, ...], text: str) -> DeclarationError:
1457 return DeclarationError(f"{path}: {shown(where)} {text}")
1459 found: dict[str, PhaseSpec] = {}
1460 phases = data.get("phases")
1461 if not isinstance(phases, dict):
1462 return found
1463 for name, table in cast("dict[str, Any]", phases).items():
1464 if not isinstance(table, dict):1464 ↛ 1465line 1464 didn't jump to line 1465 because the condition on line 1464 was never true
1465 continue
1466 entry = cast("dict[str, Any]", table)
1467 if not any(key in entry for key in _DECLARATION_KEYS):
1468 continue
1469 where = ("phases", name)
1470 level = entry.get("level", PACKAGE_LEVEL)
1471 if level not in LEVELS:
1472 raise refuse(
1473 (*where, "level"),
1474 f"is {level!r}; a phase runs at one of {', '.join(LEVELS)}",
1475 )
1476 for key in ("gated", "verb"):
1477 if not isinstance(entry.get(key, False), bool):
1478 raise refuse((*where, key), "is true or false")
1479 after = entry.get("after", [])
1480 if not isinstance(after, list) or not all(
1481 isinstance(item, str) for item in cast("list[object]", after)
1482 ):
1483 raise refuse((*where, "after"), "is a list of the phases this one follows")
1484 keys = entry.get("keys", {})
1485 if not isinstance(keys, dict):1485 ↛ 1486line 1485 didn't jump to line 1486 because the condition on line 1485 was never true
1486 raise refuse(
1487 (*where, "keys"), "is a table of the engine's keys, each to its type"
1488 )
1489 typed = cast("dict[str, Any]", keys)
1490 for key, kind in typed.items():
1491 if kind not in TYPES:
1492 raise refuse(
1493 (*where, "keys", key),
1494 f"is {kind!r}; a key's type is one of {', '.join(TYPES)}",
1495 )
1496 found[name] = PhaseSpec(
1497 name,
1498 keys={key: str(kind) for key, kind in typed.items()},
1499 level=str(level),
1500 gated=bool(entry.get("gated", False)),
1501 after=tuple(str(item) for item in cast("list[object]", after)),
1502 verb=bool(entry.get("verb", False)),
1503 extension=extension,
1504 )
1505 return found
1509 """The phases the declaration beside *package* declares, for *extension*.
1511 Empty without a declaration file. Read without judging the rest of
1512 the file, and without importing anything, so every installed
1513 extension's phases are known before any declaration is judged.
1515 Raises:
1516 DeclarationError: when the file does not parse or a phase's
1517 declaration is off its shape.
1518 """
1519 path = declaration_file(package)
1520 if path is None:1520 ↛ 1521line 1520 didn't jump to line 1521 because the condition on line 1520 was never true
1521 return ()
1522 data = _parsed(path, path.read_text("utf-8"))
1523 return tuple(phase_specs_of(data, path, extension=extension).values())
1526#: The keys that declare a query in its ``[queries.<name>]`` table.
1531 """Whether a ``[queries.<name>]`` entry declares the query, not answers it."""
1532 return isinstance(entry, dict) and any(
1533 key in cast("dict[str, Any]", entry) for key in _QUERY_KEYS
1534 )
1538 data: dict[str, Any], path: Path, *, extension: str, package: str
1539) -> dict[str, QuerySpec]:
1540 """The queries *data*'s ``[queries.<name>]`` tables declare, judged, by name.
1542 A table declares its query when it carries ``combine``, ``level``,
1543 ``default`` or ``values``; one carrying ``value`` answers a query
1544 instead. The same reader serves the base's contract file and an
1545 extension's declaration file, *extension* naming the declarer and
1546 *package* the package a ``combine`` function lives in.
1548 Raises:
1549 DeclarationError: when a declaration is off its shape: a
1550 ``combine`` that is no rule and no reference, a level that
1551 is not ``package`` or ``workspace``, ``values`` that are no
1552 list, or a table that declares and answers at once.
1553 """
1554 from livery.workshop._queries import LEVELS, PACKAGE_LEVEL, RULES, UNION, QuerySpec
1556 reader = _Reader(extension, package, path)
1557 found: dict[str, QuerySpec] = {}
1558 queries = data.get("queries")
1559 if not isinstance(queries, dict):
1560 return found
1561 for name, table in cast("dict[str, Any]", queries).items():
1562 if not _declares_query(table):
1563 continue
1564 entry = cast("dict[str, Any]", table)
1565 where = ("queries", name)
1566 if "value" in entry:
1567 raise reader.refuse(
1568 where,
1569 "declares the query and answers it in one table; a declaration"
1570 " takes default for the answer while nobody answers",
1571 )
1572 rule = entry.get("combine", UNION)
1573 if isinstance(rule, str) and rule in RULES:
1574 combine: str | Reference = rule
1575 elif isinstance(rule, str) and ":" in rule:
1576 combine = reader.reference(rule, (*where, "combine"))
1577 else:
1578 rules = ", ".join(repr(known) for known in RULES)
1579 raise reader.refuse(
1580 (*where, "combine"),
1581 f"is {rule!r}; a query combines its answers by {rules}, or a"
1582 " function 'module:name'",
1583 )
1584 level = entry.get("level", PACKAGE_LEVEL)
1585 if level not in LEVELS:
1586 raise reader.refuse(
1587 (*where, "level"),
1588 f"is {level!r}; a query is asked at one of {', '.join(LEVELS)}",
1589 )
1590 values = entry.get("values")
1591 if values is not None and not isinstance(values, list):
1592 raise reader.refuse(
1593 (*where, "values"), "is a list of the answers the query takes"
1594 )
1595 found[name] = QuerySpec(
1596 name,
1597 combine,
1598 level=str(level),
1599 default=entry.get("default"),
1600 values=tuple(cast("list[object]", values)) if values is not None else None,
1601 extension=extension,
1602 )
1603 return found
1607 """The queries the declaration beside *package* declares, for *extension*.
1609 Empty without a declaration file. Read without judging the rest of
1610 the file, and without importing anything, so every installed
1611 extension's queries are known before any declaration is judged.
1613 Raises:
1614 DeclarationError: when the file does not parse or a query's
1615 declaration is off its shape.
1616 """
1617 path = declaration_file(package)
1618 if path is None:1618 ↛ 1619line 1618 didn't jump to line 1619 because the condition on line 1618 was never true
1619 return ()
1620 data = _parsed(path, path.read_text("utf-8"))
1621 return tuple(
1622 query_specs_of(data, path, extension=extension, package=package).values()
1623 )
1626#: A template's name: the last word of its verb, ``fm new.package.<name>``.
1629#: The keys a ``[templates.<name>]`` table takes.
1632#: The keys a ``[templates.<name>.options.<option>]`` table takes.
1635#: The types a template's option takes in place of choices, each to the
1636#: Python type of its answer.
1639#: The option names a template's verb cannot take, each to the reason:
1640#: the verb's positional, and the flag footman reads on every line.
1642 "name": "the package's name, the word every template's verb takes first",
1643 "help": "footman's own flag, which shows the verb's help on any line",
1644}
1652 """A creation option: a ``[templates.<name>.options.<option>]`` table.
1654 ``fm new.package.<template> <name> --<option>=<answer>`` answers it,
1655 and the answer renders the template's files as the variable
1656 `variable`. A template that extends this one's template takes the
1657 option too, unless it fixes the answer under ``fixes``.
1659 Attributes:
1660 name: The option's name on the command line, in kebab-case.
1661 doc: One line saying what the answer decides.
1662 choices: The answers it takes; empty for an option with a type.
1663 type: The type of its answer, ``str``, ``int`` or ``bool``;
1664 ``str`` for an option with choices.
1665 default: The answer when the command line gives none; None for
1666 a required option.
1667 """
1677 """The template variable the answer renders as: the name, snake-cased."""
1678 return self.name.replace("-", "_")
1682 """Whether a birth needs an answer: an option without a default does."""
1683 return self.default is None
1686 """Why *answer* does not answer this option; empty when it does."""
1687 if self.choices:
1688 if answer in self.choices:
1689 return ""
1690 return (
1691 f"--{self.name} is {answer!r}, which is not one of its choices:"
1692 f" {', '.join(self.choices)}"
1693 )
1694 wanted = OPTION_TYPES[self.type]
1695 if isinstance(answer, wanted) and (wanted is bool or type(answer) is not bool):
1696 return ""
1697 return f"--{self.name} is {answer!r}, which is no {self.type}"
1702 """A template a declaration file declares under ``[templates.<name>]``.
1704 ``fm new.package.<name> <package>`` creates a package from it: the
1705 files of the template it extends first, then its own, which live
1706 under ``content/templates/<name>/`` beside the file that declares it.
1708 Attributes:
1709 name: The template's name, the last word of its verb.
1710 extension: The extension that declares it, or the base.
1711 doc: One line saying what a package born from it is.
1712 extensions: The extensions a package born from it lists.
1713 extends: The template whose files a birth writes first; empty
1714 for none.
1715 path: The file that declares it.
1716 options: The creation options it declares beside those of the
1717 templates it extends.
1718 fixes: Each option of a template it extends to the answer it
1719 gives it, in declaration order: a birth from this template
1720 takes no answer for it.
1721 """
1734 reader: _Reader, where: tuple[str, ...], table: object
1735) -> tuple[TemplateOption, ...]:
1736 """The options a template's ``options`` table declares, judged.
1738 Raises:
1739 DeclarationError: for an option off its shape: a name that is not
1740 kebab-case, or that is a Python keyword as a variable, or that
1741 the template's verb takes for itself, a key it
1742 does not take, a missing or blank ``doc``, ``choices`` and
1743 ``type`` both or neither, choices that are not distinct
1744 strings, a type outside ``OPTION_TYPES``, and a ``default``
1745 that does not answer the option.
1746 """
1747 if table is None:
1748 return ()
1749 if not isinstance(table, dict):1749 ↛ 1750line 1749 didn't jump to line 1750 because the condition on line 1749 was never true
1750 raise reader.refuse(
1751 (*where, "options"),
1752 "is a table of the template's creation options, each"
1753 " [templates.<name>.options.<option>]",
1754 )
1755 found: list[TemplateOption] = []
1756 for name, spec in cast("dict[str, Any]", table).items():
1757 at = (*where, "options", name)
1758 if not _TEMPLATE_NAME.fullmatch(name):
1759 raise reader.refuse(
1760 at,
1761 "is no option name: lower-case letters, digits and hyphens,"
1762 " starting with a letter, as --<option> spells it",
1763 )
1764 if keyword.iskeyword(name.replace("-", "_")):
1765 raise reader.refuse(
1766 at,
1767 "is a Python keyword once its hyphens are underscores, which"
1768 " the template variable it renders as cannot be",
1769 )
1770 if name in _TAKEN_OPTIONS:
1771 raise reader.refuse(
1772 at,
1773 f"is taken: --{name} is {_TAKEN_OPTIONS[name]}; rename the option",
1774 )
1775 if not isinstance(spec, dict):1775 ↛ 1776line 1775 didn't jump to line 1776 because the condition on line 1775 was never true
1776 raise reader.refuse(at, "is a table: doc, choices or type, and default")
1777 entry = cast("dict[str, Any]", spec)
1778 for key in entry:
1779 if key not in _OPTION_KEYS:1779 ↛ 1780line 1779 didn't jump to line 1780 because the condition on line 1779 was never true
1780 raise reader.refuse(
1781 (*at, key),
1782 "is not a key of a template's option: it takes doc, choices,"
1783 " type and default",
1784 )
1785 doc = entry.get("doc")
1786 if not isinstance(doc, str) or not doc.strip():
1787 raise reader.refuse(
1788 (*at, "doc"),
1789 "is one line of text saying what the answer decides, which"
1790 " the template's verb shows in its help and completion",
1791 )
1792 choices = entry.get("choices")
1793 kind = entry.get("type")
1794 if (choices is None) == (kind is None):
1795 raise reader.refuse(
1796 at,
1797 "takes choices, the answers it takes, or type, one of"
1798 f" {', '.join(OPTION_TYPES)}: one of the two",
1799 )
1800 answer_type = "str"
1801 if choices is not None:
1802 listed = cast("list[object]", choices) if isinstance(choices, list) else []
1803 if (
1804 not listed
1805 or not all(isinstance(item, str) and item for item in listed)
1806 or len(set(map(str, listed))) != len(listed)
1807 ):
1808 raise reader.refuse(
1809 (*at, "choices"), "is a list of the answers it takes, each once"
1810 )
1811 elif isinstance(kind, str) and kind in OPTION_TYPES:1811 ↛ 1814line 1811 didn't jump to line 1814 because the condition on line 1811 was always true
1812 answer_type = kind
1813 else:
1814 raise reader.refuse((*at, "type"), f"is one of {', '.join(OPTION_TYPES)}")
1815 option = TemplateOption(
1816 name,
1817 doc.strip(),
1818 tuple(cast("list[str]", choices or [])),
1819 answer_type,
1820 None,
1821 )
1822 if "default" in entry:
1823 default: object = entry["default"]
1824 if refusal := option.refusal(default):
1825 raise reader.refuse((*at, "default"), f"does not answer it: {refusal}")
1826 option = TemplateOption(
1827 option.name,
1828 option.doc,
1829 option.choices,
1830 option.type,
1831 cast("Answer", default),
1832 )
1833 found.append(option)
1834 return tuple(found)
1838 reader: _Reader, where: tuple[str, ...], table: object
1839) -> tuple[tuple[str, Answer], ...]:
1840 """The answers a template's ``fixes`` table gives, judged.
1842 Raises:
1843 DeclarationError: for a ``fixes`` that is not a table of option
1844 names to answers.
1845 """
1846 if table is None:
1847 return ()
1848 if not isinstance(table, dict):1848 ↛ 1849line 1848 didn't jump to line 1849 because the condition on line 1848 was never true
1849 raise reader.refuse(
1850 (*where, "fixes"),
1851 "is a table: each option of a template this one extends, to the"
1852 " answer a package born from this one takes",
1853 )
1854 found: list[tuple[str, Answer]] = []
1855 for name, answer in cast("dict[str, Any]", table).items():
1856 if not isinstance(answer, str | int | bool):1856 ↛ 1857line 1856 didn't jump to line 1857 because the condition on line 1856 was never true
1857 raise reader.refuse(
1858 (*where, "fixes", name),
1859 "is an answer: a string, an integer or a boolean",
1860 )
1861 found.append((name, answer))
1862 return tuple(found)
1866 data: dict[str, Any], path: Path, *, extension: str
1867) -> dict[str, DeclaredTemplate]:
1868 """The templates *data*'s ``[templates.<name>]`` tables declare, judged, by name.
1870 The same reader serves the base's contract file and an extension's
1871 declaration file, *extension* naming the declarer. ``doc`` and
1872 ``extensions`` are required; ``extends``, ``options`` and ``fixes``
1873 are optional, and a table takes nothing else.
1875 Raises:
1876 DeclarationError: when a template is off its shape: a name that
1877 is not lower-case letters, digits and hyphens, a key it does
1878 not take, a missing ``doc`` or ``extensions``, a value of the
1879 wrong type, or an option or a fixed answer off its shape.
1880 """
1881 reader = _Reader(extension, extension, path)
1882 found: dict[str, DeclaredTemplate] = {}
1883 templates = data.get("templates")
1884 if templates is None:
1885 return found
1886 if not isinstance(templates, dict):1886 ↛ 1887line 1886 didn't jump to line 1887 because the condition on line 1886 was never true
1887 raise reader.refuse(
1888 ("templates",), "is a table of templates, each [templates.<name>]"
1889 )
1890 for name, table in cast("dict[str, Any]", templates).items():
1891 where = ("templates", name)
1892 if not _TEMPLATE_NAME.fullmatch(name):
1893 raise reader.refuse(
1894 where,
1895 "is no template name: lower-case letters, digits and hyphens,"
1896 " starting with a letter, as fm new.package.<template> spells it",
1897 )
1898 if not isinstance(table, dict):1898 ↛ 1899line 1898 didn't jump to line 1899 because the condition on line 1898 was never true
1899 raise reader.refuse(
1900 where, "is a table: doc, extensions, extends, options and fixes"
1901 )
1902 entry = cast("dict[str, Any]", table)
1903 for key in entry:
1904 if key not in _TEMPLATE_KEYS:1904 ↛ 1905line 1904 didn't jump to line 1905 because the condition on line 1904 was never true
1905 raise reader.refuse(
1906 (*where, key),
1907 "is not a key of a template: it takes doc, extensions,"
1908 " extends, options and fixes",
1909 )
1910 doc = entry.get("doc")
1911 if doc is None:
1912 raise reader.refuse(
1913 (*where, "doc"),
1914 "is missing: one line saying what a package born from the"
1915 " template is, which the template's verb shows as its help",
1916 )
1917 if not isinstance(doc, str) or not doc.strip():1917 ↛ 1918line 1917 didn't jump to line 1918 because the condition on line 1917 was never true
1918 raise reader.refuse(
1919 (*where, "doc"),
1920 "is one line of text saying what a package born from the template is",
1921 )
1922 listed = entry.get("extensions")
1923 if listed is None:
1924 raise reader.refuse(
1925 (*where, "extensions"),
1926 "is missing: the extensions a package born from the template"
1927 " lists, [] for none",
1928 )
1929 if not isinstance(listed, list) or not all(1929 ↛ 1932line 1929 didn't jump to line 1932 because the condition on line 1929 was never true
1930 isinstance(item, str) for item in cast("list[object]", listed)
1931 ):
1932 raise reader.refuse((*where, "extensions"), "is a list of extensions")
1933 extends = entry.get("extends", "")
1934 if not isinstance(extends, str):1934 ↛ 1935line 1934 didn't jump to line 1935 because the condition on line 1934 was never true
1935 raise reader.refuse((*where, "extends"), "is a template's name")
1936 found[name] = DeclaredTemplate(
1937 name,
1938 extension,
1939 doc.strip(),
1940 tuple(cast("list[str]", listed)),
1941 extends,
1942 path,
1943 _option_specs(reader, where, entry.get("options")),
1944 _fix_specs(reader, where, entry.get("fixes")),
1945 )
1946 return found
1950 """The templates the declaration beside *package* declares, for *extension*.
1952 Empty without a declaration file. Read without judging the rest of
1953 the file, and without importing anything, so an installed
1954 extension's templates are known whether a workspace lists it or not.
1956 Raises:
1957 DeclarationError: when the file does not parse or a template is
1958 off its shape.
1959 """
1960 path = declaration_file(package)
1961 if path is None:1961 ↛ 1962line 1961 didn't jump to line 1962 because the condition on line 1961 was never true
1962 return ()
1963 data = _parsed(path, path.read_text("utf-8"))
1964 return tuple(template_specs_of(data, path, extension=extension).values())
1968 """Every declared query an answer in a file may name: the installed ones and *own*.
1970 Raises:
1971 DeclarationError: when *own* declares a query another extension
1972 declares.
1973 """
1974 from livery.workshop import _queries
1975 from livery.workshop._contract_keys import shown
1977 known = dict(_queries.declared_queries())
1978 for name, spec in own.items():
1979 held = known.get(name)
1980 if held is not None and held.extension != spec.extension:
1981 raise DeclarationError(
1982 f"{path}: {shown(('queries', name))} declares the {name} query, which"
1983 f" {held.extension} declares; one extension declares a query"
1984 )
1985 known[name] = spec
1986 return known
1990 """Every declared phase a file may name: the installed declarations' and *own*.
1992 Raises:
1993 DeclarationError: when *own* declares a phase another extension
1994 declares.
1995 """
1996 from livery.workshop import _phases
1998 known = dict(_phases.declared_phases())
1999 for name, spec in own.items():
2000 held = known.get(name)
2001 if held is not None and held.extension != spec.extension:2001 ↛ 2002line 2001 didn't jump to line 2002 because the condition on line 2001 was never true
2002 raise DeclarationError(
2003 f"{path}: phases.{name} declares the {name} phase, which"
2004 f" {held.extension} declares; one extension declares a phase"
2005 )
2006 known[name] = spec
2007 return known
2011 """The steps under a phase's table: its sub-tables beside the declaration keys."""
2012 return {
2013 key: cast("dict[str, Any]", value)
2014 for key, value in table.items()
2015 if key not in _DECLARATION_KEYS and isinstance(value, dict)
2016 }
2020 """Whether *text* is ``<owner>:<phase>.<step>``, its step one word."""
2021 owner, colon, address = text.partition(":")
2022 phase, dot, step = address.partition(".")
2023 return bool(owner and colon and phase and dot and step) and "." not in step
2027 """Every installed step, ``<owner>:<phase>.<step>``, to the scope it runs at.
2029 The base's own steps, then each installed extension's
2030 ``[phases.<phase>.<step>]`` tables, its ``[for.<target>]`` tables'
2031 among them, read without judging the rest of the file and without
2032 importing anything. A step of a package-level phase runs once per
2033 package; a step of a workspace-level phase at the scope its table
2034 names, the workspace when it names none.
2036 Raises:
2037 DeclarationError: when a declaration file does not parse.
2038 """
2039 from livery.footman import installed_entry_points
2040 from livery.workshop._phases import PACKAGE_LEVEL, declared_phases
2041 from livery.workshop._steps import PACKAGE, WORKSPACE, snapshot
2043 builtin = snapshot(initial=True)
2044 found = {
2045 f"{record.extension}:{record.name}": record.scope for record in builtin.values()
2046 }
2047 phases = declared_phases()
2048 for entry in installed_entry_points("workshop.extensions"):
2049 path = declaration_file(entry.value.partition(":")[0])
2050 if path is None:2050 ↛ 2051line 2050 didn't jump to line 2051 because the condition on line 2050 was never true
2051 continue
2052 data = _parsed(path, path.read_text("utf-8"))
2053 targets = data.get("for", {})
2054 tables = [data]
2055 if isinstance(targets, dict):2055 ↛ 2061line 2055 didn't jump to line 2061 because the condition on line 2055 was always true
2056 tables += [
2057 cast("dict[str, Any]", table)
2058 for table in cast("dict[str, Any]", targets).values()
2059 if isinstance(table, dict)
2060 ]
2061 for table in tables:
2062 held = table.get("phases", {})
2063 if not isinstance(held, dict):2063 ↛ 2064line 2063 didn't jump to line 2064 because the condition on line 2063 was never true
2064 continue
2065 for phase, steps in cast("dict[str, Any]", held).items():
2066 if not isinstance(steps, dict):2066 ↛ 2067line 2066 didn't jump to line 2067 because the condition on line 2066 was never true
2067 continue
2068 spec = phases.get(phase)
2069 per_package = spec is not None and spec.level == PACKAGE_LEVEL
2070 for step, declared in _step_tables(
2071 cast("dict[str, Any]", steps)
2072 ).items():
2073 scope = (
2074 PACKAGE
2075 if per_package
2076 else str(declared.get("scope", WORKSPACE))
2077 )
2078 found[f"{entry.name}:{phase}.{step}"] = scope
2079 return found
2086 """The names *path*'s module defines at its top level, read from its source.
2088 Its functions, classes, assignments and imports, those inside a
2089 top-level ``if`` or ``try`` among them. Parsed once per content.
2090 """
2091 text = path.read_text("utf-8")
2092 key = (path, text)
2093 found = _DEFINED.get(key)
2094 if found is None:
2095 tree = ast.parse(text, filename=str(path))
2096 found = frozenset(_defined(tree.body))
2097 _DEFINED[key] = found
2098 return found
2102 names: set[str] = set()
2103 for node in body:
2104 if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
2105 names.add(node.name)
2106 elif isinstance(node, ast.Assign):
2107 for target in node.targets:
2108 names |= {n.id for n in ast.walk(target) if isinstance(n, ast.Name)}
2109 elif isinstance(node, (ast.AnnAssign, ast.AugAssign)) and isinstance(
2110 node.target, ast.Name
2111 ):
2112 names.add(node.target.id)
2113 elif isinstance(node, (ast.Import, ast.ImportFrom)):
2114 names |= {
2115 alias.asname or alias.name.partition(".")[0] for alias in node.names
2116 }
2117 elif isinstance(node, ast.If):
2118 names |= _defined(node.body) | _defined(node.orelse)
2119 elif isinstance(node, ast.Try):2119 ↛ 2120line 2119 didn't jump to line 2120 because the condition on line 2119 was never true
2120 names |= _defined(node.body) | _defined(node.orelse)
2121 for handler in node.handlers:
2122 names |= _defined(handler.body)
2123 return names
2127 """The tasks the modules under *directory* define, ``<group>.<task>``, read by AST.
2129 The names `task_docs` reads, without their doc lines.
2130 """
2131 return frozenset(task_docs(directory))
2135 """Each task the modules under *directory* define to its doc line, read by AST.
2137 A task is named ``<group>.<task>``. Its doc line is the first line
2138 of the function's docstring, which footman shows as the verb's
2139 help; empty for a function without one. A module-level
2140 ``<name> = group("<group>")`` defines a group, and
2141 ``<name> = <parent>.group("<sub>")`` one beneath another. A function
2142 decorated ``@<name>.task`` defines a task in that group, named by
2143 the decorator's ``name=`` or else as footman names it: the
2144 function's name, a trailing underscore dropped, underscores as
2145 dashes. A group another module defines is followed through
2146 ``from ... import``. Nothing is imported.
2147 """
2148 package = ".".join(directory.parts[-1:])
2149 modules: dict[str, ast.Module] = {}
2150 for path in sorted(directory.rglob("*.py")):
2151 relative = path.relative_to(directory).with_suffix("")
2152 dotted = ".".join(part for part in relative.parts if part != "__init__")
2153 modules[dotted] = ast.parse(path.read_text("utf-8"), filename=str(path))
2154 groups: dict[tuple[str, str], str] = {}
2155 for _round in range(2):
2156 for dotted, tree in modules.items():
2157 for node in tree.body:
2158 found = _group_assigned(node, dotted, groups)
2159 if found is not None:
2160 groups[(dotted, found[0])] = found[1]
2161 for dotted, tree in modules.items():
2162 for node in tree.body:
2163 if isinstance(node, ast.ImportFrom) and node.module is not None:
2164 source = node.module.rpartition(f"{package}.")[2]
2165 for alias in node.names:
2166 group = groups.get((source, alias.name))
2167 if group is not None:
2168 groups.setdefault((dotted, alias.asname or alias.name), group)
2169 tasks: dict[str, str] = {}
2170 for dotted, tree in modules.items():
2171 for node in tree.body:
2172 if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
2173 continue
2174 for decorator in node.decorator_list:
2175 call = decorator if isinstance(decorator, ast.Call) else None
2176 target = call.func if call is not None else decorator
2177 if not (
2178 isinstance(target, ast.Attribute)
2179 and target.attr == "task"
2180 and isinstance(target.value, ast.Name)
2181 ):
2182 continue
2183 group = groups.get((dotted, target.value.id))
2184 if group is None:2184 ↛ 2185line 2184 didn't jump to line 2185 because the condition on line 2184 was never true
2185 continue
2186 named = next(
2187 (
2188 keyword.value.value
2189 for keyword in (call.keywords if call is not None else ())
2190 if keyword.arg == "name"
2191 and isinstance(keyword.value, ast.Constant)
2192 and isinstance(keyword.value.value, str)
2193 ),
2194 node.name.rstrip("_").replace("_", "-"),
2195 )
2196 doc = (ast.get_docstring(node) or "").strip()
2197 tasks[f"{group}.{named}"] = doc.splitlines()[0] if doc else ""
2198 return tasks
2202 node: ast.stmt, module: str, groups: dict[tuple[str, str], str]
2203) -> tuple[str, str] | None:
2204 """The variable and the group *node* assigns: ``group("x")``, ``<g>.group("y")``."""
2205 if not (
2206 isinstance(node, ast.Assign)
2207 and len(node.targets) == 1
2208 and isinstance(node.targets[0], ast.Name)
2209 and isinstance(node.value, ast.Call)
2210 and node.value.args
2211 and isinstance(node.value.args[0], ast.Constant)
2212 and isinstance(node.value.args[0].value, str)
2213 ):
2214 return None
2215 name = node.value.args[0].value
2216 func = node.value.func
2217 if isinstance(func, ast.Name) and func.id == "group":
2218 return node.targets[0].id, name
2219 if (
2220 isinstance(func, ast.Attribute)
2221 and func.attr == "group"
2222 and isinstance(func.value, ast.Name)
2223 and (module, func.value.id) in groups
2224 ):
2225 return node.targets[0].id, f"{groups[(module, func.value.id)]}.{name}"
2226 return None
2230 """The contract keys the declaration beside *package* owns; empty without one.
2232 Read without judging the rest of the file, and without importing
2233 anything: the contract judge asks every installed extension.
2235 Raises:
2236 DeclarationError: when the file does not parse or a key's
2237 declaration is malformed.
2238 """
2239 path = declaration_file(package)
2240 if path is None:
2241 return ()
2242 return contract_keys_of(_parsed(path, path.read_text("utf-8")), path)
2246 data: dict[str, Any], path: Path, *, contracts: tuple[str, ...] = CONTRACTS
2247) -> tuple[Declared, ...]:
2248 """The contract keys *data*'s ``[contract]`` tables declare, judged.
2250 *contracts* are the contracts the file may declare keys in: a
2251 workspace's for an extension; the base's own file declares the keys
2252 of ``extension.toml`` as well.
2253 """
2254 found: list[Declared] = []
2255 for contract, table in data.get("contract", {}).items():
2256 if contract not in contracts:
2257 raise DeclarationError(
2258 f"{path}: [contract.{contract}] names no contract; an extension"
2259 f" declares keys in {', '.join(contracts)}"
2260 )
2261 found += _keys(cast("ContractKind", contract), table, (), path)
2262 return tuple(found)
2265#: The keys a contract key's own declaration holds. Under one of these
2266#: names a table is a key of its own, declared beneath: a query's
2267#: ``values`` is a key of ``extension.toml``, and its declaration is a
2268#: table.
2273 contract: ContractKind, table: dict[str, Any], parts: tuple[str, ...], path: Path
2274) -> list[Declared]:
2275 from livery.workshop._contract_keys import TYPES, Declared
2277 where = f"[contract.{contract}{''.join('.' + part for part in parts)}]"
2278 found: list[Declared] = []
2279 own = {key for key in _OWN if key in table and not isinstance(table[key], dict)}
2280 if own:
2281 types = table.get("types") if "types" in own else None
2282 if not (
2283 isinstance(types, list)
2284 and types
2285 and all(kind in TYPES for kind in cast("list[object]", types))
2286 ):
2287 raise DeclarationError(
2288 f"{path}: {where} types is {types!r}; it lists one or more of"
2289 f" {', '.join(TYPES)}"
2290 )
2291 values = table.get("values", []) if "values" in own else []
2292 doc = table.get("doc", "") if "doc" in own else ""
2293 if not isinstance(values, list) or not isinstance(doc, str):2293 ↛ 2294line 2293 didn't jump to line 2294 because the condition on line 2293 was never true
2294 raise DeclarationError(
2295 f"{path}: {where}: values is a list of strings, doc a string"
2296 )
2297 found.append(
2298 Declared(
2299 contract,
2300 ".".join(parts),
2301 cast(
2302 "tuple[Type, ...]",
2303 tuple(str(kind) for kind in cast("list[object]", types)),
2304 ),
2305 tuple(str(value) for value in cast("list[object]", values)),
2306 doc,
2307 )
2308 )
2309 for key, value in table.items():
2310 if key in own:
2311 continue
2312 if not isinstance(value, dict) or "." in key:2312 ↛ 2313line 2312 didn't jump to line 2313 because the condition on line 2312 was never true
2313 raise DeclarationError(
2314 f"{path}: {where} {key} is not a key's declaration; a key is a"
2315 " table with types, and values and doc where it has them"
2316 )
2317 found += _keys(contract, cast("dict[str, Any]", value), (*parts, key), path)
2318 return found