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
codehood/push/exam.py ADDED
@@ -0,0 +1,636 @@
1
+ """
2
+ The pure core that turns files under `exams/` into `ExamFile`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.parse` keeps `include:` and `includeAll:`
6
+ blocks unresolved, so this module resolves them against the questions the
7
+ repository holds, and sends each question of the exam as a reference by
8
+ slug. Questions written inline are returned as `QuestionFile`s of their own.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import hashlib
14
+ import json
15
+ import re
16
+ from collections import defaultdict
17
+ from collections.abc import Collection, Iterator, Mapping, Sequence
18
+ from dataclasses import dataclass, field
19
+ from datetime import UTC, date, datetime, timedelta
20
+ from pathlib import Path
21
+ from typing import TYPE_CHECKING, Literal
22
+
23
+ import mdq
24
+ from mdq.errors import IncludeNotFound
25
+ from mdq.models import Attachment, Include, IncludeAll
26
+ from mdq.models._query import QuerySyntaxError, parse_query
27
+ from pydantic import JsonValue, ValidationError
28
+
29
+ from .errors import SlugCollisionError
30
+ from .question import (
31
+ DRAFT_MARK,
32
+ InvalidQuestion,
33
+ QuestionFile,
34
+ question_status,
35
+ question_version,
36
+ read_attachments,
37
+ resolve_exam_sources,
38
+ test_source_paths,
39
+ )
40
+ from .resource import (
41
+ REF_PREFIX,
42
+ front_matter_str,
43
+ slugify_text,
44
+ split_front_matter,
45
+ title_from_filename,
46
+ )
47
+ from .wire import canonical_question, exam_payload
48
+
49
+ if TYPE_CHECKING:
50
+ from .exclude import ExcludedFile
51
+
52
+ __all__ = [
53
+ "EXAM_SUFFIXES",
54
+ "LIVE_STATUSES",
55
+ "ExamFile",
56
+ "ExamStatus",
57
+ "ExamType",
58
+ "IgnoredExamPolicy",
59
+ "InvalidExam",
60
+ "LocalBank",
61
+ "LocalExamStatus",
62
+ "exam_duration",
63
+ "exam_rev",
64
+ "exam_scheduled_at",
65
+ "exam_slug",
66
+ "exam_status",
67
+ "exam_type",
68
+ "inline_questions",
69
+ "peek_exam_slug",
70
+ "scan_exams",
71
+ ]
72
+
73
+ #: The types the server knows.
74
+ type ExamType = Literal["EXAM", "QUIZ", "PRACTICE"]
75
+
76
+ #: Every status the server reads an exam with, in the order an exam moves
77
+ #: through: `ONGOING` and `COMPLETED` are set on the server and no file can
78
+ #: undo them.
79
+ type ExamStatus = Literal["DRAFT", "SCHEDULED", "ONGOING", "COMPLETED"]
80
+
81
+ #: The statuses a file can declare.
82
+ type LocalExamStatus = Literal["DRAFT", "SCHEDULED"]
83
+
84
+ #: The statuses a push never moves an exam out of.
85
+ LIVE_STATUSES: frozenset[str] = frozenset({"ONGOING", "COMPLETED"})
86
+
87
+ #: Suffixes of an exam file, longest first so `x.mdq.md` is `x`.
88
+ EXAM_SUFFIXES = (".mdq.md", ".mdq", ".md")
89
+
90
+ #: The words that set the type of an exam, from a path.
91
+ _TYPE_WORDS: dict[str, ExamType] = {"quiz": "QUIZ", "practice": "PRACTICE"}
92
+
93
+ #: Separators of the words of a path component.
94
+ _WORD_BREAK = re.compile(r"[-_.]")
95
+
96
+ #: The inline id of an H1 such as `# [midterm] Midterm Exam`.
97
+ _H1_ID = re.compile(r"^#[ \t]+\[(?P<id>[^\]\n]+)\]", re.MULTILINE)
98
+
99
+
100
+ @dataclass(frozen=True)
101
+ class ExamFile:
102
+ """
103
+ One file under `exams/`, already parsed and slugged.
104
+
105
+ `questions` are the slugs the exam holds, in order, includes resolved.
106
+ `inline` are the questions the file writes itself, each of them among
107
+ `questions` too.
108
+ """
109
+
110
+ slug: str
111
+ path: Path
112
+ type: ExamType
113
+ status: LocalExamStatus
114
+ title: str
115
+ description: str | None
116
+ preamble: str | None
117
+ tags: tuple[str, ...]
118
+ allow_code_run: bool | None
119
+ questions: tuple[str, ...]
120
+ #: `{"hours", "minutes"}` or `None` when the file declares none.
121
+ duration: dict[str, JsonValue] | None = None
122
+ #: The start as the server spells it, or `None` when the file declares none.
123
+ scheduled_at: str | None = None
124
+ inline: tuple[QuestionFile, ...] = ()
125
+ #: The names of the `mdq` fields set to a value the server cannot hold.
126
+ ignored: tuple[str, ...] = ()
127
+ #: The attachments of the exam itself, fenced and linked.
128
+ attachments: tuple[Attachment, ...] = ()
129
+ #: Attachment name -> sha-256 of the linked attachments' bytes.
130
+ files: Mapping[str, str] = field(default_factory=dict)
131
+ #: Sha-256 -> the file the bytes of that attachment are read from.
132
+ blobs: Mapping[str, Path] = field(default_factory=dict)
133
+ #: The files its linked attachments were read from.
134
+ sources: tuple[Path, ...] = ()
135
+
136
+ @property
137
+ def rev(self) -> str:
138
+ """
139
+ The `rev` of the exam's payload.
140
+ """
141
+ return exam_rev(exam_payload(self))
142
+
143
+
144
+ @dataclass(frozen=True)
145
+ class InvalidExam:
146
+ """
147
+ A file under `exams/` that `mdq` refused or whose includes do not
148
+ resolve, kept so the push reports a failure and leaves what the server
149
+ holds under its slug alone.
150
+ """
151
+
152
+ slug: str
153
+ path: Path
154
+ reason: str
155
+
156
+
157
+ @dataclass(frozen=True)
158
+ class IgnoredExamPolicy:
159
+ """
160
+ Fields of an exam file that the server has no column for: they are not
161
+ sent.
162
+ """
163
+
164
+ slug: str
165
+ path: Path
166
+ fields: tuple[str, ...]
167
+
168
+
169
+ class LocalBank:
170
+ """
171
+ A `mdq.QuestionBank` over the questions the repository holds, by slug.
172
+ """
173
+
174
+ def __init__(self, questions: Mapping[str, mdq.Question]) -> None:
175
+ self.questions = questions
176
+
177
+ def load(self, question_id: str) -> Mapping[str, object]:
178
+ try:
179
+ question = self.questions[question_id]
180
+ except KeyError:
181
+ raise IncludeNotFound(question_id, "not a local question") from None
182
+ return question.model_dump(mode="json", by_alias=True, exclude_none=True)
183
+
184
+ def tagged(self, tag: str) -> Collection[str]:
185
+ return {
186
+ slug for slug, question in self.questions.items() if tag in question.tags
187
+ }
188
+
189
+ def ids(self) -> Collection[str]:
190
+ return set(self.questions)
191
+
192
+
193
+ def exam_slug(exam_id: str | None, rel_path: Path) -> str:
194
+ """
195
+ The slug an exam file pushes under: its `id`, slugified, or else its
196
+ flattened path under `exams/` without suffix and draft marks.
197
+
198
+ `part1/exam.md` is `part1-exam` and `_drafts/_a.mdq.md` is `drafts-a`.
199
+ """
200
+ if exam_id:
201
+ return slugify_text(exam_id)
202
+ return slugify_text("-".join(_strip_suffix(_unmark(rel_path).parts)))
203
+
204
+
205
+ def exam_type(rel_path: Path) -> ExamType:
206
+ """
207
+ The type an exam file declares: the first `quiz` or `practice` word in
208
+ its path, directories before the filename, and `EXAM` when there is none.
209
+
210
+ A word is a run of characters between `-`, `_` or `.`, so
211
+ `quizzical.md` is an `EXAM`.
212
+ """
213
+ for part in rel_path.parts:
214
+ for word in _WORD_BREAK.split(part.lower()):
215
+ if word in _TYPE_WORDS:
216
+ return _TYPE_WORDS[word]
217
+ return "EXAM"
218
+
219
+
220
+ def exam_status(rel_path: Path, *, scheduled: bool) -> LocalExamStatus:
221
+ """
222
+ `DRAFT` when the file or a directory under `exams/` starts with `_`;
223
+ otherwise `SCHEDULED` if the exam declares a start, `DRAFT` if not.
224
+ """
225
+ if any(part.startswith(DRAFT_MARK) for part in rel_path.parts) or not scheduled:
226
+ return "DRAFT"
227
+ return "SCHEDULED"
228
+
229
+
230
+ def exam_duration(value: timedelta) -> dict[str, JsonValue]:
231
+ """
232
+ A duration as the `{hours, minutes}` the server takes: a plain total,
233
+ with no 24 hour wrap and the seconds dropped.
234
+ """
235
+ minutes = int(value.total_seconds()) // 60
236
+ return {"hours": minutes // 60, "minutes": minutes % 60}
237
+
238
+
239
+ def exam_scheduled_at(start: date | datetime) -> str:
240
+ """
241
+ A start as the UTC timestamp the server spells back: a date is midnight
242
+ and a naive datetime is UTC.
243
+ """
244
+ if isinstance(start, datetime):
245
+ moment = start.replace(tzinfo=UTC) if start.tzinfo is None else start
246
+ moment = moment.astimezone(UTC)
247
+ else:
248
+ moment = datetime(start.year, start.month, start.day, tzinfo=UTC)
249
+ return f"{moment:%Y-%m-%dT%H:%M:%S}.{moment.microsecond // 1000:03d}Z"
250
+
251
+
252
+ def exam_rev(payload: Mapping[str, JsonValue]) -> str:
253
+ """
254
+ Digest an exam payload into the `rev` the server stores, the way
255
+ `resource.content_ref` digests a resource.
256
+
257
+ `attachments` and `files` count only when the exam has an attachment, so
258
+ the `rev` of an exam without one is the same as before they existed.
259
+ """
260
+ if not payload.get("attachments"):
261
+ payload = {
262
+ key: value
263
+ for key, value in payload.items()
264
+ if key not in ("attachments", "files")
265
+ }
266
+ canonical = json.dumps(
267
+ {"v": REF_PREFIX, **payload},
268
+ separators=(",", ":"),
269
+ sort_keys=True,
270
+ ensure_ascii=False,
271
+ )
272
+ digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
273
+ return f"{REF_PREFIX}:{digest}"
274
+
275
+
276
+ def inline_questions(
277
+ exams: Sequence[ExamFile | InvalidExam],
278
+ ) -> tuple[QuestionFile, ...]:
279
+ """
280
+ The questions the exams write inline, which a push sends as questions
281
+ of their own.
282
+ """
283
+ return tuple(
284
+ question
285
+ for exam in exams
286
+ if isinstance(exam, ExamFile)
287
+ for question in exam.inline
288
+ )
289
+
290
+
291
+ def scan_exams(
292
+ root: Path,
293
+ questions: Sequence[QuestionFile | InvalidQuestion],
294
+ excluded: Sequence[ExcludedFile] = (),
295
+ ) -> Iterator[ExamFile | InvalidExam]:
296
+ """
297
+ Walk `exams/` and yield an `ExamFile` per MDQ file, or an `InvalidExam`
298
+ for one `mdq` refuses or whose includes do not resolve.
299
+
300
+ `questions` are the ones scanned from `questions/` and `excluded` those
301
+ `[push] exclude` leaves out: an include may name either, but only the
302
+ first kind is sent, so naming the second is an error.
303
+
304
+ Raises:
305
+ SlugCollisionError: two exam files want the same slug, or an inline
306
+ question wants the slug of another question. Raised before any
307
+ exam is yielded.
308
+ QuestionSourceError: a test file linked by an inline `code`
309
+ question cannot be read.
310
+ """
311
+ base = root / "exams"
312
+ index = _QuestionIndex.build(root, questions, excluded)
313
+ left_out = {file.path for file in excluded if file.kind == "exam"}
314
+ found = [
315
+ _read_exam(base, path, index)
316
+ for path in _exam_paths(base)
317
+ if path.relative_to(root).as_posix() not in left_out
318
+ ]
319
+
320
+ exams: dict[str, list[Path]] = defaultdict(list)
321
+ inline: dict[str, list[Path]] = defaultdict(list)
322
+ for exam in found:
323
+ exams[exam.slug].append(exam.path)
324
+ if isinstance(exam, ExamFile):
325
+ for question in exam.inline:
326
+ inline[question.slug].append(question.path)
327
+ collisions = {slug: paths for slug, paths in exams.items() if len(paths) > 1}
328
+ for slug, paths in inline.items():
329
+ taken = [index.paths_by_slug[slug]] if slug in index.paths_by_slug else []
330
+ if len(paths) + len(taken) > 1:
331
+ collisions[slug] = [*taken, *paths]
332
+ if collisions:
333
+ raise SlugCollisionError(collisions)
334
+ yield from found
335
+
336
+
337
+ #
338
+ # Utilities
339
+ #
340
+ @dataclass(frozen=True)
341
+ class _QuestionIndex:
342
+ """
343
+ What an include can name: every question of `questions/` by slug, by
344
+ filename stem and by path.
345
+ """
346
+
347
+ root: Path
348
+ #: Slug -> why it cannot be included, `None` when it can.
349
+ state: Mapping[str, str | None]
350
+ by_stem: Mapping[str, tuple[str, ...]]
351
+ by_path: Mapping[Path, str]
352
+ paths_by_slug: Mapping[str, Path]
353
+ bank: LocalBank
354
+
355
+ @classmethod
356
+ def build(
357
+ cls,
358
+ root: Path,
359
+ questions: Sequence[QuestionFile | InvalidQuestion],
360
+ excluded: Sequence[ExcludedFile],
361
+ ) -> _QuestionIndex:
362
+ entries: list[tuple[str, Path, str | None]] = []
363
+ valid: dict[str, mdq.Question] = {}
364
+ for item in questions:
365
+ if isinstance(item, QuestionFile):
366
+ entries.append((item.slug, item.path, None))
367
+ valid[item.slug] = item.question
368
+ else:
369
+ entries.append((item.slug, item.path, f"is invalid: {item.reason}"))
370
+ for file in excluded:
371
+ if file.kind == "question":
372
+ entries.append(
373
+ (file.slug, root / file.path, "is left out by [push] exclude")
374
+ )
375
+ state: dict[str, str | None] = {}
376
+ paths: dict[str, Path] = {}
377
+ by_path: dict[Path, str] = {}
378
+ stems: dict[str, list[str]] = defaultdict(list)
379
+ for slug, path, problem in entries:
380
+ state.setdefault(slug, problem)
381
+ paths.setdefault(slug, path)
382
+ by_path[path.resolve()] = slug
383
+ stem = _strip_suffix((path.name,))[0].removeprefix(DRAFT_MARK)
384
+ stems[stem].append(slug)
385
+ return cls(
386
+ root=root,
387
+ state=state,
388
+ by_stem={s: tuple(dict.fromkeys(slugs)) for s, slugs in stems.items()},
389
+ by_path=by_path,
390
+ paths_by_slug=paths,
391
+ bank=LocalBank(valid),
392
+ )
393
+
394
+ def resolve(self, include: str, exam_path: Path) -> str:
395
+ """
396
+ The slug `include` names, by the ladder of the mapping: an exact
397
+ slug, then a unique filename stem, then a relative path.
398
+
399
+ Raises:
400
+ LookupError: nothing matches, or the match cannot be sent.
401
+ """
402
+ slug = self._find(include, exam_path)
403
+ if slug is None:
404
+ raise LookupError(f"include {include!r} matches no question")
405
+ problem = self.state[slug]
406
+ if problem is not None:
407
+ raise LookupError(
408
+ f"include {include!r} names question {slug!r}, which {problem}"
409
+ )
410
+ return slug
411
+
412
+ def _find(self, include: str, exam_path: Path) -> str | None:
413
+ if include in self.state:
414
+ return include
415
+ stems = self.by_stem.get(include.removeprefix(DRAFT_MARK), ())
416
+ if len(stems) == 1:
417
+ return stems[0]
418
+ if "/" in include or include.endswith(EXAM_SUFFIXES):
419
+ for directory in (exam_path.parent, self.root / "questions", self.root):
420
+ for candidate in _candidates(directory / include):
421
+ found = self.by_path.get(candidate.resolve())
422
+ if found is not None:
423
+ return found
424
+ return None
425
+
426
+
427
+ def _candidates(path: Path) -> Iterator[Path]:
428
+ yield path
429
+ for suffix in EXAM_SUFFIXES:
430
+ yield path.with_name(path.name + suffix)
431
+
432
+
433
+ def _strip_suffix(parts: Sequence[str]) -> tuple[str, ...]:
434
+ """
435
+ `parts` with the suffix of the last one dropped, `.mdq.md` as one.
436
+ """
437
+ *head, last = parts
438
+ for suffix in EXAM_SUFFIXES:
439
+ if last.endswith(suffix):
440
+ return (*head, last.removesuffix(suffix))
441
+ return (*head, last)
442
+
443
+
444
+ def _unmark(rel_path: Path) -> Path:
445
+ return Path(*(part.removeprefix(DRAFT_MARK) for part in rel_path.parts))
446
+
447
+
448
+ def _exam_paths(base: Path) -> list[Path]:
449
+ if not base.is_dir():
450
+ return []
451
+ return sorted(
452
+ path
453
+ for path in base.rglob("*")
454
+ if path.is_file() and path.name.endswith(EXAM_SUFFIXES)
455
+ )
456
+
457
+
458
+ def peek_exam_slug(path: Path, rel_path: Path) -> str:
459
+ """
460
+ The slug of an exam file read without `mdq`: its `id` in the front matter
461
+ or the H1, else its path under `exams/`.
462
+ """
463
+ try:
464
+ text = path.read_text(encoding="utf-8")
465
+ except (OSError, UnicodeDecodeError):
466
+ return exam_slug(None, rel_path)
467
+ return _peek_slug(text, rel_path)
468
+
469
+
470
+ def _peek_slug(text: str, rel_path: Path) -> str:
471
+ """
472
+ The slug of a file `mdq` refused: its `id` in the front matter or the
473
+ H1, else its path.
474
+ """
475
+ front_matter, body = split_front_matter(text)
476
+ exam_id = front_matter_str(front_matter, "id")
477
+ if exam_id is None and (found := _H1_ID.search(body)):
478
+ exam_id = found["id"].strip()
479
+ return exam_slug(exam_id, rel_path)
480
+
481
+
482
+ def _read_exam(base: Path, path: Path, index: _QuestionIndex) -> ExamFile | InvalidExam:
483
+ """
484
+ Read and parse one exam file.
485
+
486
+ Raises:
487
+ QuestionSourceError: a test file of an inline question is missing.
488
+ """
489
+ rel_path = path.relative_to(base)
490
+ try:
491
+ text = path.read_text(encoding="utf-8")
492
+ except (OSError, UnicodeDecodeError) as exc:
493
+ return InvalidExam(exam_slug(None, rel_path), path, str(exc))
494
+ try:
495
+ exam = mdq.parse(text, kind="exam")
496
+ exam = resolve_exam_sources(exam, path.parent)
497
+ except (mdq.InvalidDocument, ValidationError) as exc:
498
+ return InvalidExam(_peek_slug(text, rel_path), path, str(exc))
499
+ slug = exam_slug(exam.id, rel_path)
500
+ try:
501
+ return _build(slug, rel_path, path, exam, index)
502
+ except (LookupError, ValueError) as exc:
503
+ return InvalidExam(slug, path, str(exc))
504
+
505
+
506
+ def _build(
507
+ slug: str, rel_path: Path, path: Path, exam: mdq.Exam, index: _QuestionIndex
508
+ ) -> ExamFile:
509
+ """
510
+ Raises:
511
+ LookupError: an include matches no question or one that is not sent.
512
+ ValueError: `includeAll` has a `max`, a query cannot be read, the
513
+ exam holds a question twice, or `meta.codeRun` is not a boolean.
514
+ """
515
+ code_run = (exam.meta or {}).get("codeRun")
516
+ if code_run is not None and not isinstance(code_run, bool):
517
+ raise ValueError(f"meta.codeRun must be true or false, not {code_run!r}")
518
+
519
+ # Every include and inline slug first: an `includeAll` skips what the
520
+ # exam already holds, wherever in the exam that is.
521
+ slugs: dict[int, str] = {}
522
+ inline: list[QuestionFile] = []
523
+ for position, entry in enumerate(exam.questions, start=1):
524
+ if isinstance(entry, Include):
525
+ slugs[position] = index.resolve(entry.include, path)
526
+ elif not isinstance(entry, IncludeAll):
527
+ question_slug = _inline_slug(slug, entry.id, position)
528
+ slugs[position] = question_slug
529
+ inline.append(_inline_file(question_slug, entry, rel_path, path))
530
+ held = set(slugs.values())
531
+
532
+ questions: list[str] = []
533
+ for position, entry in enumerate(exam.questions, start=1):
534
+ if isinstance(entry, IncludeAll):
535
+ added = _include_all(entry, index, held)
536
+ held.update(added)
537
+ questions.extend(added)
538
+ else:
539
+ questions.append(slugs[position])
540
+ duplicates = sorted({s for s in questions if questions.count(s) > 1})
541
+ if duplicates:
542
+ raise ValueError(f"the exam holds {', '.join(map(repr, duplicates))} twice")
543
+
544
+ ignored = tuple(
545
+ name
546
+ for name, set_ in (
547
+ ("penalty", exam.penalty != "none"),
548
+ ("grading", exam.grading != "symmetric"),
549
+ ("shuffle", exam.shuffle),
550
+ )
551
+ if set_
552
+ )
553
+ if exam.duration is not None and exam_duration(exam.duration) == {
554
+ "hours": 0,
555
+ "minutes": 0,
556
+ }:
557
+ raise ValueError(f"duration {exam.duration} is under a minute")
558
+ linked = read_attachments(exam.attachments, path.parent)
559
+ stem = _strip_suffix((path.name,))[0]
560
+ return ExamFile(
561
+ slug=slug,
562
+ path=path,
563
+ type=exam_type(rel_path),
564
+ status=exam_status(rel_path, scheduled=exam.start is not None),
565
+ title=exam.title or title_from_filename(stem.removeprefix(DRAFT_MARK)),
566
+ description=exam.description,
567
+ preamble=exam.instructions,
568
+ tags=tuple(exam.tags or ()),
569
+ allow_code_run=code_run,
570
+ questions=tuple(questions),
571
+ duration=exam_duration(exam.duration) if exam.duration is not None else None,
572
+ scheduled_at=exam_scheduled_at(exam.start) if exam.start is not None else None,
573
+ inline=tuple(inline),
574
+ ignored=ignored,
575
+ attachments=tuple(exam.attachments or ()),
576
+ files={item.name: item.sha256 for item in linked},
577
+ blobs={item.sha256: item.path for item in linked},
578
+ sources=tuple(item.path for item in linked),
579
+ )
580
+
581
+
582
+ def _include_all(entry: IncludeAll, index: _QuestionIndex, held: set[str]) -> list[str]:
583
+ """
584
+ The slugs `entry`'s query selects that the exam does not hold yet, sorted.
585
+
586
+ Raises:
587
+ ValueError: the block has a `max` or a query that cannot be read.
588
+ """
589
+ if entry.max is not None:
590
+ raise ValueError(
591
+ f"includeAll {entry.include_all!r} has a max: a random pick "
592
+ "never converges, so it is not supported"
593
+ )
594
+ try:
595
+ chosen = parse_query(entry.include_all).select(index.bank)
596
+ except QuerySyntaxError as exc:
597
+ raise ValueError(f"includeAll {entry.include_all!r}: {exc}") from exc
598
+ return sorted(chosen - held)
599
+
600
+
601
+ def _inline_slug(exam: str, question_id: str | None, position: int) -> str:
602
+ part = slugify_text(question_id) if question_id else ""
603
+ return f"{exam}-{part or f'q{position}'}"
604
+
605
+
606
+ def _inline_file(
607
+ slug: str, question: mdq.Question, rel_path: Path, path: Path
608
+ ) -> QuestionFile:
609
+ """
610
+ An inline question as a `QuestionFile`, versioned by its own content so
611
+ editing one question does not change its siblings'.
612
+
613
+ Linked attachments are relative to the exam file and, when there are any,
614
+ their hashes join the canonical JSON as `files`.
615
+ """
616
+ linked = read_attachments(question.attachments, path.parent)
617
+ files = {item.name: item.sha256 for item in linked}
618
+ document = canonical_question(question)
619
+ if files:
620
+ document["files"] = {**files}
621
+ canonical = json.dumps(
622
+ document,
623
+ separators=(",", ":"),
624
+ sort_keys=True,
625
+ ensure_ascii=False,
626
+ )
627
+ return QuestionFile(
628
+ slug=slug,
629
+ version=question_version(canonical.encode("utf-8")),
630
+ question=question,
631
+ path=path,
632
+ status=question_status(rel_path),
633
+ sources=(*test_source_paths(question, path.parent), *(i.path for i in linked)),
634
+ files=files,
635
+ blobs={item.sha256: item.path for item in linked},
636
+ )
@@ -0,0 +1,60 @@
1
+ """
2
+ The files a push leaves out because of `[push] exclude` in `codehood.toml`.
3
+
4
+ Excluded files are never read, so they cannot be pushed; what the server
5
+ already holds under their slugs is protected from pruning (see
6
+ `plan.plan_sync`). `questions/`, `resources/` and `exams/` are excludable: they
7
+ are the trees whose files are pushed one by one.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import Iterator, Sequence
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+ from typing import Literal
16
+
17
+ from ..repo.diff import FileType
18
+ from ..repo.file_tracker import scan_files
19
+ from .exam import peek_exam_slug
20
+ from .question import peek_id, question_slug
21
+ from .resource import INFO_FILE, resource_slug
22
+
23
+ __all__ = ["ExcludedFile", "scan_excluded"]
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class ExcludedFile:
28
+ """
29
+ A question, exam or resource file that matched an `exclude` pattern.
30
+ """
31
+
32
+ kind: Literal["question", "resource", "exam"]
33
+ slug: str
34
+ #: Relative to the repository root, `/`-separated.
35
+ path: str
36
+
37
+
38
+ def scan_excluded(root: Path, exclude: Sequence[str]) -> Iterator[ExcludedFile]:
39
+ """
40
+ Yield every question and resource file the patterns exclude.
41
+
42
+ A question's slug may come from the `id` in its front matter, so that
43
+ much of an excluded question is read; an unreadable one falls back to
44
+ its path. An excluded `info.yaml` is metadata, not a resource, and is
45
+ not yielded.
46
+ """
47
+ for file in scan_files(root, exclude):
48
+ if not file.excluded:
49
+ continue
50
+ rel_path = Path(file.name)
51
+ if file.type is FileType.QUESTION:
52
+ slug = question_slug(peek_id(root / file.path), rel_path)
53
+ yield ExcludedFile("question", slug, file.path.as_posix())
54
+ elif file.type is FileType.EXAM:
55
+ slug = peek_exam_slug(root / file.path, rel_path)
56
+ yield ExcludedFile("exam", slug, file.path.as_posix())
57
+ elif file.type is FileType.RESOURCE and rel_path.name != INFO_FILE:
58
+ yield ExcludedFile(
59
+ "resource", resource_slug(rel_path), file.path.as_posix()
60
+ )