1"""The configuration a step owns, composed into the files the render writes.
3A step record carries one fragment per rendered file it has
4something to say in: its tables in ``pyproject.toml``, its lines in
5``.vscode/settings.json``, its ``.clang-tidy`` in each C or C++ package.
6The render composes the base template with the registered fragments
7in step-name order, so two machines write the same bytes, and the
8drift gate judges the result. A fragment is jinja text rendered with
9the same data the template reads. A project file's fragment applies
10once per workspace, with per-package variation spelled inside it the
11tool's own way; a package file's fragment applies in each package
12whose set holds one of the extensions it names, the first step by
13name winning when two have one. A fragment leaves the render
14with its record: unregistering the step removes the section from the
15next render, and a per-package file it wrote alone goes when its
16bytes are the bytes the render last wrote.
17"""
24#: The project files a fragment may address; a fragment naming another
25#: file refuses at registration.
31 """One step's configuration for one rendered file.
33 Attributes:
34 file: The rendered file, a project file relative to the root
35 or a per-package file name.
36 text: The fragment's jinja text, rendered with the file's own
37 render data.
38 extensions: For a per-package file, the extensions whose
39 packages render it; empty for a project file.
40 """
48 """Refuse a fragment naming a file the render does not write.
50 Raises:
51 ValueError: naming the step, the file, and the files a
52 fragment may address.
53 """
54 for fragment in fragments:
55 if fragment.file in PROJECT_FILES:
56 if fragment.extensions:
57 raise ValueError(
58 f"step {step!r}: a fragment for {fragment.file} applies to"
59 " the whole workspace and names no extension"
60 )
61 continue
62 if fragment.extensions:
63 continue
64 raise ValueError(
65 f"step {step!r}: a fragment for {fragment.file!r} names a file the"
66 f" render does not write; the project files are"
67 f" {', '.join(PROJECT_FILES)}, and a fragment that names extensions is"
68 " rendered in each package whose set holds one"
69 )
73 """*text* rendered with *data*."""
74 import json
76 import minijinja
78 # Lenient on an undefined name, so a render over partial data draws
79 # the file the full data would, less the missing parts; the drift
80 # gate reads the full data and judges the bytes.
81 environment = minijinja.Environment(
82 keep_trailing_newline=True, undefined_behavior="lenient"
83 )
84 plain = json.loads(json.dumps(data, default=str))
85 return environment.render_str(text, **plain)
89 """Each project file's composed fragments, by file, in step-name order.
91 A file no step has a fragment for maps to the empty string, so a
92 template's ``{{ fragments['...'] }}`` always resolves.
93 """
94 from livery.workshop._steps import steps_by_name
96 found: dict[str, str] = {}
97 for file in PROJECT_FILES:
98 found[file] = ""
99 for name in sorted(steps_by_name()):
100 record = steps_by_name()[name]
101 for fragment in record.fragments:
102 if fragment.file in PROJECT_FILES:
103 rendered = _render(fragment.text, data)
104 if found[fragment.file] and not found[fragment.file].endswith("\n\n"):
105 found[fragment.file] += "\n"
106 found[fragment.file] += rendered
107 return found
111 """The per-package files the registered steps' fragments render, sorted.
113 A fragment that names extensions is rendered in each package whose
114 set holds one, so the files a C or C++ package carries are the
115 registered steps' to say, and leave with them.
116 """
117 from livery.workshop._steps import steps_by_name
119 return tuple(
120 sorted(
121 {
122 fragment.file
123 for record in steps_by_name().values()
124 for fragment in record.fragments
125 if fragment.extensions
126 }
127 )
128 )
132 """The fragment text a package holding *extensions* renders as *file*, and its step.
134 The first step by name whose fragment names one of *extensions*
135 wins; None when no step has one, which is what a withdrawn step
136 looks like to the apply.
137 """
138 from livery.workshop._steps import steps_by_name
140 held = set(extensions)
141 for name in sorted(steps_by_name()):
142 for fragment in steps_by_name()[name].fragments:
143 if fragment.file == file and held & set(fragment.extensions):
144 return fragment.text, name
145 return None
149 extensions: tuple[str, ...], file: str, data: dict[str, Any]
150) -> str | None:
151 """*file* rendered for a package holding *extensions*; None when no step owns it."""
152 found = package_fragment(extensions, file)
153 if found is None:153 ↛ 154line 153 didn't jump to line 154 because the condition on line 153 was never true
154 return None
155 text, _step = found
156 return _render(text, data)