codehood-cli 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. codehood/__init__.py +0 -0
  2. codehood/__main__.py +4 -0
  3. codehood/actions/__init__.py +0 -0
  4. codehood/actions/base.py +119 -0
  5. codehood/actions/resources.py +30 -0
  6. codehood/api/__init__.py +0 -0
  7. codehood/api/base.py +256 -0
  8. codehood/api/generate.py +1370 -0
  9. codehood/api/generated.py +3818 -0
  10. codehood/api/openapi.py +134 -0
  11. codehood/api/pages.py +53 -0
  12. codehood/cli/__init__.py +64 -0
  13. codehood/cli/api.py +422 -0
  14. codehood/cli/attendance.py +136 -0
  15. codehood/cli/auth.py +106 -0
  16. codehood/cli/base.py +42 -0
  17. codehood/cli/chill.py +52 -0
  18. codehood/cli/exam.py +107 -0
  19. codehood/cli/grades.py +185 -0
  20. codehood/cli/init.py +161 -0
  21. codehood/cli/push.py +609 -0
  22. codehood/cli/show.py +77 -0
  23. codehood/cli/uitils.py +26 -0
  24. codehood/functional.py +40 -0
  25. codehood/globs.py +71 -0
  26. codehood/grades.py +74 -0
  27. codehood/hypothesis.py +274 -0
  28. codehood/models/__init__.py +0 -0
  29. codehood/models/base.py +15 -0
  30. codehood/models/repo.py +187 -0
  31. codehood/models/validators.py +177 -0
  32. codehood/push/__init__.py +225 -0
  33. codehood/push/base.py +216 -0
  34. codehood/push/calendar.py +664 -0
  35. codehood/push/errors.py +136 -0
  36. codehood/push/exam.py +636 -0
  37. codehood/push/exclude.py +60 -0
  38. codehood/push/grades.py +455 -0
  39. codehood/push/hook.py +48 -0
  40. codehood/push/links.py +614 -0
  41. codehood/push/ours.py +78 -0
  42. codehood/push/plan.py +1981 -0
  43. codehood/push/project.py +272 -0
  44. codehood/push/question.py +338 -0
  45. codehood/push/report.py +244 -0
  46. codehood/push/repository.py +326 -0
  47. codehood/push/resource.py +576 -0
  48. codehood/push/run.py +1275 -0
  49. codehood/push/unconsumed.py +208 -0
  50. codehood/push/wire.py +222 -0
  51. codehood/py.typed +0 -0
  52. codehood/repo/__init__.py +62 -0
  53. codehood/repo/_config.py +28 -0
  54. codehood/repo/_layout.py +132 -0
  55. codehood/repo/_scaffold.py +244 -0
  56. codehood/repo/diff.py +71 -0
  57. codehood/repo/file_tracker.py +124 -0
  58. codehood/theme.py +101 -0
  59. codehood/widgets/__init__.py +0 -0
  60. codehood/widgets/mascot.py +76 -0
  61. codehood/widgets/questions/__init__.py +65 -0
  62. codehood/widgets/questions/base.py +119 -0
  63. codehood/widgets/questions/controls.py +194 -0
  64. codehood/widgets/questions/fill_in.py +81 -0
  65. codehood/widgets/questions/responses.py +137 -0
  66. codehood/widgets/questions/simple.py +117 -0
  67. codehood_cli-0.5.0.dist-info/METADATA +294 -0
  68. codehood_cli-0.5.0.dist-info/RECORD +71 -0
  69. codehood_cli-0.5.0.dist-info/WHEEL +4 -0
  70. codehood_cli-0.5.0.dist-info/entry_points.txt +4 -0
  71. codehood_cli-0.5.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,272 @@
1
+ """
2
+ Projects what the server returns for an entity back into the payload the CLI
3
+ sends for it.
4
+
5
+ A push compares local, base and server in the space of the payload (see
6
+ `wire.py`), so the server side needs the inverse of what the server does on
7
+ the way out: `project(GET after PUT p) == p` for every payload `p` the server
8
+ accepts. Each projection drops the fields only a read has (`createdAt`, the
9
+ embedded `id`s), turns nested objects back into the slugs a write names them
10
+ by, and undoes the rewrites of a read (a `FILE`'s link back into its hash, a
11
+ question document back into the form `mdq` normalizes to).
12
+
13
+ Pure: no HTTP, no clock. `run.fetch_server_state` is what feeds it.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import re
19
+ from collections.abc import Mapping
20
+ from dataclasses import dataclass
21
+ from datetime import UTC, datetime
22
+
23
+ import mdq
24
+ from pydantic import JsonValue, TypeAdapter, ValidationError
25
+
26
+ from ..api import generated
27
+ from .calendar import Duration, EventKey, TimeOfDay, TimeSlot
28
+ from .wire import Payload, canonical_question
29
+
30
+ __all__ = [
31
+ "Payload",
32
+ "RemoteEntry",
33
+ "project_calendar_event",
34
+ "project_course",
35
+ "project_exam",
36
+ "project_grade_column",
37
+ "project_question",
38
+ "project_resource",
39
+ "project_time_slot",
40
+ "resource_event_of",
41
+ "time_slot_of",
42
+ ]
43
+
44
+ #: Reads a question document of the server back into an `mdq` model.
45
+ _QUESTION: TypeAdapter[mdq.Question] = TypeAdapter(mdq.Question)
46
+
47
+ #: The path the server gives a `FILE` resource: `/files/<sha-256>/<filename>`.
48
+ _FILE_LINK = re.compile(r"^/files/(?P<hash>[^/]+)/")
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class RemoteEntry:
53
+ """
54
+ One entity as the server holds it: its projected payload and the two
55
+ markers that say whether it changed.
56
+
57
+ `rev` is `None` for an entity that stores none (a time slot) and
58
+ `updated_at` is the ISO timestamp as the server spelled it.
59
+ """
60
+
61
+ payload: Payload
62
+ rev: str | None = None
63
+ updated_at: str | None = None
64
+
65
+
66
+ def project_course(course: generated.Course) -> Payload:
67
+ """
68
+ The payload of the course `PUT`, read from `GET /api/course/...`.
69
+ """
70
+ return {
71
+ "discipline": course.discipline.slug,
72
+ "instructor": course.instructor.username,
73
+ "edition": course.edition.slug,
74
+ "description": course.description or "",
75
+ "startDate": course.start_date,
76
+ "endDate": course.end_date,
77
+ }
78
+
79
+
80
+ def project_resource(resource: generated.Resource) -> Payload:
81
+ """
82
+ The payload of a resource `PUT`.
83
+
84
+ A `FILE` read has a link, not a hash: the hash is the link's first
85
+ segment. A link that does not have the shape stays whole in `hash`, so it
86
+ never equals a sha-256 and shows up as a difference.
87
+ """
88
+ data: dict[str, JsonValue]
89
+ match resource.data:
90
+ case generated.DataMd(content=content):
91
+ data = {"type": "MD", "content": content}
92
+ case generated.DataCode(content=content, language=language):
93
+ data = {"type": "CODE", "content": content, "language": language}
94
+ case generated.ResourceDataFile(filename=filename, link=link):
95
+ found = _FILE_LINK.match(link)
96
+ data = {
97
+ "type": "FILE",
98
+ "filename": filename,
99
+ "hash": found["hash"] if found else link,
100
+ }
101
+ case generated.DataLink(url=url):
102
+ data = {"type": "LINK", "url": url}
103
+ event = resource.event
104
+ return {
105
+ "slug": resource.slug,
106
+ "title": resource.title,
107
+ "description": resource.description,
108
+ "event": (
109
+ {"week": event.week, "timeSlot": event.time_slot}
110
+ if event is not None
111
+ else None
112
+ ),
113
+ "data": data,
114
+ }
115
+
116
+
117
+ def project_question(item: Mapping[str, JsonValue]) -> Payload:
118
+ """
119
+ The canonical payload of one item of the question listing.
120
+
121
+ Takes the item as JSON rather than as a generated model: the models drop
122
+ the fields of a question type they do not declare. A document `mdq`
123
+ cannot read (one stored in an older format) stays as the server holds
124
+ it, so it differs from every local question. `files` shows up only when
125
+ the question holds some, as in the local payload.
126
+ """
127
+ document = item["question"]
128
+ files = item.get("files")
129
+ try:
130
+ question = _QUESTION.validate_python(document)
131
+ payload: Payload = {
132
+ "slug": item["slug"],
133
+ "question": canonical_question(question),
134
+ }
135
+ except ValidationError:
136
+ payload = {"slug": item["slug"], "question": document}
137
+ if isinstance(files, dict) and files:
138
+ payload["files"] = dict(sorted(files.items()))
139
+ return payload
140
+
141
+
142
+ def project_exam(exam: generated.Exam) -> Payload:
143
+ """
144
+ The payload of an exam `PUT`, without `status` and `rev`.
145
+
146
+ `duration` and `scheduledAt` are left out when the server holds none, the
147
+ way a file that declares none leaves them out of its payload. The
148
+ questions come back unpinned: a push never sends a version.
149
+ """
150
+ questions: list[JsonValue] = [
151
+ {"slug": item.slug, "version": None} for item in exam.questions
152
+ ]
153
+ tags: list[JsonValue] = [*sorted(exam.tags)]
154
+ attachments: list[JsonValue] = [
155
+ item.model_dump(mode="json", by_alias=True, exclude_none=True)
156
+ for item in exam.attachments or []
157
+ ]
158
+ payload: Payload = {
159
+ "slug": exam.slug,
160
+ "type": exam.type,
161
+ "title": exam.title,
162
+ "description": exam.description,
163
+ "preamble": exam.preamble,
164
+ "format": exam.format,
165
+ "tags": tags,
166
+ "allowCodeRun": exam.allow_code_run,
167
+ "questions": questions,
168
+ "attachments": attachments,
169
+ "files": dict(sorted((exam.files or {}).items())),
170
+ }
171
+ if exam.duration is not None:
172
+ minutes = (exam.duration.hours or 0) * 60 + (exam.duration.minutes or 0)
173
+ payload["duration"] = {"hours": minutes // 60, "minutes": minutes % 60}
174
+ if exam.scheduled_at is not None:
175
+ payload["scheduledAt"] = _instant(exam.scheduled_at)
176
+ return payload
177
+
178
+
179
+ def project_time_slot(slot: generated.TimeSlot) -> Payload:
180
+ """
181
+ The payload of a time slot `PUT`.
182
+ """
183
+ minutes = (slot.duration.hours or 0) * 60 + (slot.duration.minutes or 0)
184
+ return {
185
+ "slug": slot.slug,
186
+ "title": slot.title,
187
+ "day": slot.day,
188
+ "start": {"hour": slot.start.hour, "minute": slot.start.minute},
189
+ "duration": {"hours": minutes // 60, "minutes": minutes % 60},
190
+ }
191
+
192
+
193
+ def resource_event_of(payload: Payload) -> EventKey | None:
194
+ """
195
+ The lesson a resource payload is attached to, `None` for a general one.
196
+
197
+ Raises:
198
+ pydantic.ValidationError: `payload` has an `event` of another shape.
199
+ """
200
+ event = payload["event"]
201
+ if event is None:
202
+ return None
203
+ key = generated.Event.model_validate(event)
204
+ return EventKey(week=key.week, time_slot=key.time_slot)
205
+
206
+
207
+ def time_slot_of(payload: Payload) -> TimeSlot:
208
+ """
209
+ The `TimeSlot` a time slot payload describes.
210
+
211
+ Raises:
212
+ pydantic.ValidationError: `payload` is not a time slot payload.
213
+ """
214
+ body = generated.TimeSlotCreate.model_validate(payload)
215
+ return TimeSlot(
216
+ slug=body.slug,
217
+ day=body.day,
218
+ start=TimeOfDay(hour=body.start.hour, minute=body.start.minute),
219
+ duration=Duration(
220
+ hours=body.duration.hours or 0, minutes=body.duration.minutes or 0
221
+ ),
222
+ title=body.title,
223
+ )
224
+
225
+
226
+ def project_calendar_event(event: generated.CalendarEvent) -> Payload:
227
+ """
228
+ The payload of a calendar event `PUT`.
229
+
230
+ The repositories are linked by slug, and the time slot is named by its
231
+ slug rather than embedded.
232
+ """
233
+ repositories: list[JsonValue] = [
234
+ slug for slug in sorted(item.slug for item in event.repositories)
235
+ ]
236
+ return {
237
+ "kind": event.kind,
238
+ "title": event.title,
239
+ "description": event.description or "",
240
+ "week": event.week,
241
+ "timeSlot": event.time_slot.slug,
242
+ "repositories": repositories,
243
+ }
244
+
245
+
246
+ def project_grade_column(column: generated.GradeColumn) -> Payload:
247
+ """
248
+ The payload of a grade column `PUT`: `releasedAt` is the server's alone.
249
+ """
250
+ values: list[JsonValue] = [
251
+ {"username": entry.username, "value": entry.value}
252
+ for entry in sorted(column.values, key=lambda entry: entry.username)
253
+ ]
254
+ return {
255
+ "slug": column.slug,
256
+ "title": column.title,
257
+ "kind": column.kind,
258
+ "position": column.position,
259
+ "values": values,
260
+ }
261
+
262
+
263
+ #
264
+ # Utilities
265
+ #
266
+ def _instant(text: str) -> str:
267
+ """
268
+ Respell an ISO timestamp the way the server spells it back: UTC,
269
+ milliseconds, a `Z`.
270
+ """
271
+ moment = datetime.fromisoformat(text).astimezone(UTC)
272
+ return f"{moment:%Y-%m-%dT%H:%M:%S}.{moment.microsecond // 1000:03d}Z"
@@ -0,0 +1,338 @@
1
+ """
2
+ The pure core that turns files under `questions/` into `QuestionFile`s.
3
+
4
+ Nothing here touches the network or the server's idea of what it holds --
5
+ see `plan.py` for that half. `mdq` is the parser of record: the server's
6
+ `QuestionCreate.question` is a structured, discriminated union, not
7
+ Markdown, so `mdq.parse` turns a file's text into the shape the
8
+ server wants and `run.py` translates it into the generated request model.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import hashlib
14
+ from collections import defaultdict
15
+ from collections.abc import Iterator, Mapping, Sequence
16
+ from dataclasses import dataclass, field
17
+ from pathlib import Path
18
+ from typing import Literal
19
+
20
+ import mdq
21
+ from mdq.models import Attachment, CodeQuestion
22
+ from pydantic import ValidationError
23
+
24
+ from ..repo.diff import FileType
25
+ from ..repo.file_tracker import scan_files
26
+ from .errors import QuestionParseError, QuestionSourceError, SlugCollisionError
27
+ from .resource import front_matter_str, slugify, slugify_text, split_front_matter
28
+
29
+ __all__ = [
30
+ "DRAFT_MARK",
31
+ "MAX_UPLOAD_BYTES",
32
+ "AnyQuestion",
33
+ "InvalidQuestion",
34
+ "LinkedFile",
35
+ "LocalQuestionStatus",
36
+ "QuestionFile",
37
+ "QuestionStatus",
38
+ "peek_id",
39
+ "question_slug",
40
+ "question_status",
41
+ "question_version",
42
+ "read_attachments",
43
+ "resolve_exam_sources",
44
+ "resolve_test_sources",
45
+ "scan_questions",
46
+ "test_source_paths",
47
+ ]
48
+
49
+ #: The discriminated union `mdq.parse` returns for a question.
50
+ type AnyQuestion = mdq.Question
51
+
52
+ #: The statuses a push reads from the server, in the order a push only moves
53
+ #: forward through: `HIDDEN` is set on the web and no file can undo it.
54
+ type QuestionStatus = Literal["DRAFT", "PUBLISHED", "HIDDEN"]
55
+
56
+ #: The statuses a file can declare, through `DRAFT_MARK`.
57
+ type LocalQuestionStatus = Literal["DRAFT", "PUBLISHED"]
58
+
59
+ #: A leading `_` on the file or on any directory above it marks a draft, and
60
+ #: is left out of the slug.
61
+ DRAFT_MARK = "_"
62
+
63
+ #: The largest file the server takes in one upload, in bytes.
64
+ MAX_UPLOAD_BYTES = 16 * 1024 * 1024
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class QuestionFile:
69
+ """
70
+ One file under `questions/`, already parsed, slugged, and hashed.
71
+ """
72
+
73
+ slug: str
74
+ version: str
75
+ question: AnyQuestion
76
+ path: Path
77
+ status: LocalQuestionStatus = "PUBLISHED"
78
+ #: The files its linked test sources and attachments were read from.
79
+ sources: tuple[Path, ...] = ()
80
+ #: Attachment name -> sha-256 of the linked attachments' bytes.
81
+ files: Mapping[str, str] = field(default_factory=dict)
82
+ #: Sha-256 -> the file the bytes of that attachment are read from.
83
+ blobs: Mapping[str, Path] = field(default_factory=dict)
84
+
85
+
86
+ @dataclass(frozen=True)
87
+ class LinkedFile:
88
+ """
89
+ A file a question or an exam links from its `## [attachments]` section,
90
+ read off disk.
91
+ """
92
+
93
+ name: str
94
+ path: Path
95
+ data: bytes
96
+
97
+ @property
98
+ def sha256(self) -> str:
99
+ """
100
+ The hex sha-256 of the file's bytes, the name the server stores it under.
101
+ """
102
+ return hashlib.sha256(self.data).hexdigest()
103
+
104
+
105
+ @dataclass(frozen=True)
106
+ class InvalidQuestion:
107
+ """
108
+ A file under `questions/` that `mdq` refused, kept so the push reports it
109
+ as a failure and leaves what the server holds under its slug alone.
110
+ """
111
+
112
+ slug: str
113
+ path: Path
114
+ reason: str
115
+
116
+
117
+ def question_version(raw: bytes) -> str:
118
+ """
119
+ Digest a question file's raw bytes into the `version` the server
120
+ stores. For a `code` question, the bytes of its linked test files
121
+ follow the file's.
122
+
123
+ Unlike a resource's `ref`, which digests the parsed fields, a
124
+ question's `version` digests the file itself -- see
125
+ `dev/specs/to-do/push-questions.md`, "The hash rides in `version`,
126
+ not `contentHash`". The `md5:` prefix names the recipe, so changing it
127
+ later invalidates old versions loudly instead of colliding with them.
128
+ """
129
+ return f"md5:{hashlib.md5(raw).hexdigest()}"
130
+
131
+
132
+ def scan_questions(
133
+ root: Path, exclude: Sequence[str] = ()
134
+ ) -> Iterator[QuestionFile | InvalidQuestion]:
135
+ """
136
+ Walk `questions/` and yield one `QuestionFile` per file, or an
137
+ `InvalidQuestion` for a file `mdq` refuses.
138
+
139
+ Reuses the (fixed) `repo.file_tracker.scan_files` for the walk, so a
140
+ subdirectory never becomes a question of its own. Files matching an
141
+ `exclude` pattern are skipped without being read. The `id` in a
142
+ question's front matter is its slug; without one, the slug is the
143
+ flattened path, without the `_` that marks a draft.
144
+
145
+ Raises:
146
+ SlugCollisionError: two or more files want the same slug. Raised
147
+ eagerly, after reading front matter but before any file is
148
+ parsed or any network call is made.
149
+ """
150
+ base = root / "questions"
151
+ by_slug: dict[str, list[Path]] = defaultdict(list)
152
+ entries: list[tuple[str, Path]] = []
153
+
154
+ for file in scan_files(root, exclude):
155
+ if file.type is not FileType.QUESTION or file.excluded:
156
+ continue
157
+ rel_path = Path(file.name)
158
+ slug = question_slug(peek_id(base / rel_path), rel_path)
159
+ by_slug[slug].append(rel_path)
160
+ entries.append((slug, rel_path))
161
+
162
+ collisions = {slug: paths for slug, paths in by_slug.items() if len(paths) > 1}
163
+ if collisions:
164
+ raise SlugCollisionError(collisions)
165
+
166
+ for slug, rel_path in entries:
167
+ try:
168
+ yield read_question(base, slug, rel_path)
169
+ except QuestionParseError as exc:
170
+ yield InvalidQuestion(slug=slug, path=exc.path, reason=str(exc.cause))
171
+
172
+
173
+ def question_slug(question_id: str | None, rel_path: Path) -> str:
174
+ """
175
+ The slug a question file pushes under: its `id`, slugified, or else its
176
+ flattened path under `questions/` without draft marks.
177
+
178
+ `_rascunhos/_laco.md` and `rascunhos/laco.md` share the slug
179
+ `rascunhos-laco`, so publishing by renaming keeps the question.
180
+ """
181
+ if question_id:
182
+ return slugify_text(question_id)
183
+ return slugify(Path(*(part.removeprefix(DRAFT_MARK) for part in rel_path.parts)))
184
+
185
+
186
+ def question_status(rel_path: Path) -> LocalQuestionStatus:
187
+ """
188
+ `DRAFT` when the file or a directory under `questions/` starts with `_`,
189
+ `PUBLISHED` otherwise.
190
+ """
191
+ if any(part.startswith(DRAFT_MARK) for part in rel_path.parts):
192
+ return "DRAFT"
193
+ return "PUBLISHED"
194
+
195
+
196
+ def peek_id(path: Path) -> str | None:
197
+ """
198
+ The `id` in a question file's front matter, read without `mdq`; `None`
199
+ when absent or the file cannot be read as text.
200
+ """
201
+ try:
202
+ text = path.read_text(encoding="utf-8")
203
+ except (OSError, UnicodeDecodeError):
204
+ return None
205
+ front_matter, _ = split_front_matter(text)
206
+ return front_matter_str(front_matter, "id")
207
+
208
+
209
+ #
210
+ # Utilities
211
+ #
212
+ def read_question(base: Path, slug: str, rel_path: Path) -> QuestionFile:
213
+ """
214
+ Read, parse, and hash one question file off disk.
215
+
216
+ A linked test source of a `code` question is read and resolved here.
217
+
218
+ Raises:
219
+ QuestionParseError: `mdq.parse` refuses the file, or a test file
220
+ breaks the rules of the annotations.
221
+ QuestionSourceError: a linked test file cannot be read.
222
+ """
223
+ path = base / rel_path
224
+ raw = path.read_bytes()
225
+ try:
226
+ question = mdq.parse(raw.decode("utf-8"), kind="question", ids="fill")
227
+ question = resolve_test_sources(question, path.parent)
228
+ except (mdq.InvalidDocument, ValidationError) as exc:
229
+ raise QuestionParseError(path, exc) from exc
230
+ sources = test_source_paths(question, path.parent)
231
+ linked = read_attachments(question.attachments, path.parent)
232
+ # A linked test or attachment file is part of the question: editing it
233
+ # alone must change the version, or the push would skip the question.
234
+ content = raw + b"".join(
235
+ b"\0" + data
236
+ for data in (
237
+ *(source.read_bytes() for source in sources),
238
+ *(item.data for item in linked),
239
+ )
240
+ )
241
+ return QuestionFile(
242
+ slug=slug,
243
+ version=question_version(content),
244
+ question=question,
245
+ path=path,
246
+ status=question_status(rel_path),
247
+ sources=(*sources, *(item.path for item in linked)),
248
+ files={item.name: item.sha256 for item in linked},
249
+ blobs={item.sha256: item.path for item in linked},
250
+ )
251
+
252
+
253
+ def read_attachments(
254
+ attachments: Sequence[Attachment] | None, base: Path
255
+ ) -> tuple[LinkedFile, ...]:
256
+ """
257
+ Read the files the linked attachments point to, in the order of the
258
+ document; fenced attachments carry their own text and are skipped.
259
+
260
+ Links are relative to `base`, the directory of the file that holds them.
261
+
262
+ Raises:
263
+ QuestionSourceError: a linked file is missing, cannot be read, or is
264
+ over `MAX_UPLOAD_BYTES`.
265
+ """
266
+ found: list[LinkedFile] = []
267
+ for attachment in attachments or ():
268
+ if attachment.origin is None:
269
+ continue
270
+ path = base / attachment.origin
271
+ try:
272
+ data = path.read_bytes()
273
+ except OSError as exc:
274
+ raise QuestionSourceError(path, attachment.origin, exc) from exc
275
+ if len(data) > MAX_UPLOAD_BYTES:
276
+ limit = MAX_UPLOAD_BYTES // (1024 * 1024)
277
+ reason = ValueError(f"{len(data)} bytes, over the {limit} MiB limit")
278
+ raise QuestionSourceError(path, attachment.origin, reason)
279
+ found.append(LinkedFile(attachment.name, path, data))
280
+ return tuple(found)
281
+
282
+
283
+ def test_source_paths(question: AnyQuestion, base: Path) -> tuple[Path, ...]:
284
+ """
285
+ The files a `code` question links as test sources, relative to `base`
286
+ and without repeats; empty for any other question.
287
+ """
288
+ if not isinstance(question, CodeQuestion):
289
+ return ()
290
+ origins = dict.fromkeys(
291
+ source.origin for source in question.tests or [] if source.origin
292
+ )
293
+ return tuple(base / origin for origin in origins)
294
+
295
+
296
+ def resolve_test_sources(question: AnyQuestion, base: Path) -> AnyQuestion:
297
+ """
298
+ Read the linked test sources of a `code` question and resolve them with
299
+ `CodeQuestion.resolve`; any other question comes back unchanged.
300
+
301
+ Links are relative to `base`, the directory of the file that holds the
302
+ question. A source with a fenced `text` is not touched.
303
+
304
+ Raises:
305
+ QuestionSourceError: a linked file is missing or is not UTF-8 text.
306
+ pydantic.ValidationError: a file breaks the rules of the annotations.
307
+ """
308
+ if not isinstance(question, CodeQuestion):
309
+ return question
310
+ texts: dict[str, str] = {}
311
+ for source in question.tests or []:
312
+ if source.origin is None or source.text is not None:
313
+ continue
314
+ path = base / source.origin
315
+ try:
316
+ texts[source.origin] = path.read_text(encoding="utf-8")
317
+ except (OSError, UnicodeDecodeError) as exc:
318
+ raise QuestionSourceError(path, source.origin, exc) from exc
319
+ return question.resolve(texts)
320
+
321
+
322
+ def resolve_exam_sources(exam: mdq.Exam, base: Path) -> mdq.Exam:
323
+ """
324
+ Resolve the test sources of every inline question of an exam, with links
325
+ relative to `base`, the directory of the exam file.
326
+
327
+ Included questions are left alone: they come from a bank, which resolves
328
+ them against their own files.
329
+
330
+ Raises:
331
+ QuestionSourceError: a linked file is missing or is not UTF-8 text.
332
+ pydantic.ValidationError: a file breaks the rules of the annotations.
333
+ """
334
+ entries = [
335
+ resolve_test_sources(entry, base) if isinstance(entry, CodeQuestion) else entry
336
+ for entry in exam.questions
337
+ ]
338
+ return exam.model_copy(update={"questions": entries})