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/plan.py ADDED
@@ -0,0 +1,1981 @@
1
+ """
2
+ The pure core of `codehood push`: diff a repository against the server's
3
+ current state into a `Plan`, the writes to run and the notices that explain
4
+ what was left alone.
5
+
6
+ No client, no ids, no `run()` -- see `dev/specs/to-do/push.md`,
7
+ "Architecture". `run.py` is the only thing in `codehood/push/` that
8
+ executes a `Write`.
9
+
10
+ The two inputs are whole values, `LocalState` and `ServerState`, rather
11
+ than a dozen loose mappings: `slug -> ref` and `slug -> version` are the
12
+ same type and mean different things, and naming them as fields is what
13
+ stops a caller from swapping them silently.
14
+
15
+ Each entity is decided by `three_way` from its local payload, its base entry
16
+ and the server's, and `plan_sync` collects the decisions into a `Plan`.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import hashlib
22
+ import json
23
+ from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
24
+ from dataclasses import dataclass, field, replace
25
+ from datetime import date
26
+ from fnmatch import fnmatchcase
27
+ from functools import partial
28
+ from pathlib import Path
29
+ from typing import Literal
30
+
31
+ from ..models.repo import CourseKey
32
+ from .base import BaseEntry, BaseState
33
+ from .calendar import Event, EventKey, TimeSlot
34
+ from .exam import (
35
+ LIVE_STATUSES,
36
+ ExamFile,
37
+ ExamStatus,
38
+ IgnoredExamPolicy,
39
+ InvalidExam,
40
+ LocalExamStatus,
41
+ exam_rev,
42
+ inline_questions,
43
+ )
44
+ from .exclude import ExcludedFile
45
+ from .grades import GradeColumn
46
+ from .project import RemoteEntry, resource_event_of
47
+ from .question import AnyQuestion, InvalidQuestion, QuestionFile, QuestionStatus
48
+ from .repository import RepositoryTree
49
+ from .resource import ResourceData, ResourceFile
50
+ from .wire import (
51
+ Payload,
52
+ course_payload,
53
+ event_payload,
54
+ exam_payload,
55
+ grade_column_payload,
56
+ question_payload,
57
+ resource_payload,
58
+ time_slot_payload,
59
+ )
60
+
61
+ __all__ = [
62
+ "COURSE_KEY",
63
+ "STATUS_ORDER",
64
+ "BaseUpdate",
65
+ "Confirmation",
66
+ "Conflict",
67
+ "ConflictReason",
68
+ "Decision",
69
+ "DeleteCalendarEvent",
70
+ "DeleteExam",
71
+ "DeleteGradeColumn",
72
+ "DeleteQuestion",
73
+ "DeleteRepository",
74
+ "DeleteResource",
75
+ "DeleteRollCall",
76
+ "DeleteTimeSlot",
77
+ "EntityKind",
78
+ "IgnoredExamPolicy",
79
+ "Keep",
80
+ "KeptCancelled",
81
+ "KeptDraftPublished",
82
+ "KeptExamLive",
83
+ "KeptForRollCall",
84
+ "KeptPinnedSlot",
85
+ "KeptRepository",
86
+ "LocalState",
87
+ "Notice",
88
+ "OtherCli",
89
+ "Plan",
90
+ "Prune",
91
+ "Pull",
92
+ "Put",
93
+ "Rejected",
94
+ "ServerDrifted",
95
+ "ServerEvent",
96
+ "ServerExam",
97
+ "ServerQuestion",
98
+ "ServerState",
99
+ "Skip",
100
+ "UpsertCalendarEvent",
101
+ "UpsertCourse",
102
+ "UpsertExam",
103
+ "UpsertGradeColumn",
104
+ "UpsertQuestion",
105
+ "UpsertRepository",
106
+ "UpsertResource",
107
+ "UpsertTimeSlot",
108
+ "Write",
109
+ "course_ref",
110
+ "diff_fields",
111
+ "diff_keyed",
112
+ "event_key",
113
+ "join_status",
114
+ "merge_event",
115
+ "merge_repository",
116
+ "order_decisions",
117
+ "order_writes",
118
+ "parse_event_key",
119
+ "plan_repositories",
120
+ "plan_sync",
121
+ "three_way",
122
+ "write_rank",
123
+ ]
124
+
125
+
126
+ #: The order a question's status moves through on a push.
127
+ STATUS_ORDER: tuple[QuestionStatus, ...] = ("DRAFT", "PUBLISHED", "HIDDEN")
128
+
129
+
130
+ #
131
+ # Inputs
132
+ #
133
+ @dataclass(frozen=True)
134
+ class LocalState:
135
+ """
136
+ Everything a repository holds that a push can write.
137
+
138
+ `start` and `end` come from `calendar.md`, not from the edition: the
139
+ edition is an institutional term shared across courses, and a course's
140
+ own span is the instructor's to set -- see the mapping's "Course".
141
+
142
+ `grade_columns` is `None` when the columns could not be computed, which
143
+ leaves the server's columns alone. An empty tuple is a course that
144
+ declares none, and prunes whatever the server holds.
145
+ """
146
+
147
+ key: CourseKey
148
+ description: str
149
+ start: date
150
+ end: date
151
+ slots: tuple[TimeSlot, ...] = ()
152
+ events: tuple[Event, ...] = ()
153
+ resources: tuple[ResourceFile, ...] = ()
154
+ questions: tuple[QuestionFile | InvalidQuestion, ...] = ()
155
+ #: The exam files. Their inline questions join `questions` in the plan.
156
+ exams: tuple[ExamFile | InvalidExam, ...] = ()
157
+ grade_columns: tuple[GradeColumn, ...] | None = ()
158
+ repositories: tuple[RepositoryTree, ...] = ()
159
+ #: Files left out by `[push] exclude`: never written, never pruned.
160
+ excluded: tuple[ExcludedFile, ...] = ()
161
+ #: Versionable files no push stage read, sorted. Reported, never pushed.
162
+ unconsumed: tuple[str, ...] = ()
163
+ #: Problems found while reading that do not stop a push, for the shell to print.
164
+ warnings: tuple[str, ...] = ()
165
+
166
+ @property
167
+ def discipline(self) -> str:
168
+ return self.key.discipline
169
+
170
+ @property
171
+ def course(self) -> str:
172
+ return self.key.slug
173
+
174
+
175
+ @dataclass(frozen=True)
176
+ class ServerEvent:
177
+ """
178
+ What the sync preflight reports about one calendar event.
179
+
180
+ `ref` decides whether to rewrite it and `kind` whether to touch it at
181
+ all -- see the mapping's "Sync preflight". `entry` is the event as the
182
+ server holds it, projected to the payload.
183
+ """
184
+
185
+ ref: str
186
+ kind: Literal["REGULAR", "HOLIDAY", "CANCELLED"]
187
+ entry: RemoteEntry
188
+ attendances: int | None = None
189
+
190
+
191
+ @dataclass(frozen=True)
192
+ class ServerQuestion:
193
+ """
194
+ What the sync preflight reports about one question.
195
+
196
+ `entry` is the question as the server holds it, projected to the
197
+ payload: its `rev` is the server's own, and the version label stays in
198
+ `version`.
199
+ """
200
+
201
+ version: str
202
+ entry: RemoteEntry
203
+ status: QuestionStatus = "DRAFT"
204
+
205
+
206
+ @dataclass(frozen=True)
207
+ class ServerExam:
208
+ """
209
+ What the sync preflight reports about one exam.
210
+
211
+ `entry` is the exam as the server holds it, projected to the payload;
212
+ `status` stays out of it, as for questions.
213
+ """
214
+
215
+ entry: RemoteEntry
216
+ status: ExamStatus = "DRAFT"
217
+
218
+
219
+ @dataclass(frozen=True)
220
+ class ServerState:
221
+ """
222
+ What the server currently holds for a course.
223
+
224
+ Each entity carries a `RemoteEntry`: its payload, projected back from
225
+ what the server returned, and the `rev` and `updatedAt` it carries.
226
+ """
227
+
228
+ course_exists: bool = False
229
+ #: The course row. Its `rev` is the `course_ref` of its last push.
230
+ course: RemoteEntry | None = None
231
+ resources: Mapping[str, RemoteEntry] = field(default_factory=dict)
232
+ questions: Mapping[str, ServerQuestion] = field(default_factory=dict)
233
+ exams: Mapping[str, ServerExam] = field(default_factory=dict)
234
+ time_slots: Mapping[str, RemoteEntry] = field(default_factory=dict)
235
+ calendar_events: Mapping[tuple[int, str], ServerEvent] = field(default_factory=dict)
236
+ grade_columns: Mapping[str, RemoteEntry] = field(default_factory=dict)
237
+ #: Slug -> sha1 of the head commit's root tree, `None` before the first
238
+ #: commit.
239
+ repositories: Mapping[str, str | None] = field(default_factory=dict)
240
+
241
+
242
+ #
243
+ # Operations
244
+ #
245
+ @dataclass(frozen=True)
246
+ class UpsertCourse:
247
+ """
248
+ The course row to `PUT`, keyed by `(discipline, course)`.
249
+ """
250
+
251
+ key: CourseKey
252
+ description: str
253
+ start_date: str
254
+ end_date: str
255
+ #: The `course_ref` the row is stored with, as its `rev`.
256
+ ref: str
257
+
258
+ @property
259
+ def discipline(self) -> str:
260
+ return self.key.discipline
261
+
262
+ @property
263
+ def course(self) -> str:
264
+ return self.key.slug
265
+
266
+
267
+ @dataclass(frozen=True)
268
+ class UpsertResource:
269
+ """
270
+ One resource to `PUT`, whole, whatever its type.
271
+
272
+ `data` is the same tagged union the server stores, so the shell has
273
+ nothing left to infer -- see `push.md`, "Architecture". `ref` is the
274
+ digest the server hands back on the next read, which is what makes a
275
+ second push of an unchanged resource a no-op.
276
+ """
277
+
278
+ slug: str
279
+ title: str
280
+ description: str | None
281
+ data: ResourceData
282
+ ref: str
283
+ path: Path
284
+ event: EventKey | None = None
285
+
286
+
287
+ @dataclass(frozen=True)
288
+ class DeleteResource:
289
+ """
290
+ A resource to delete by slug: its local file is gone.
291
+ """
292
+
293
+ slug: str
294
+
295
+
296
+ @dataclass(frozen=True)
297
+ class UpsertQuestion:
298
+ """
299
+ One question to `PUT`, parsed but untranslated.
300
+
301
+ `question` is the same `mdq` union `question.scan_questions` yields;
302
+ `run.py` is the only place that turns it into the generated request
303
+ model, dropping the fields the server's schema rejects.
304
+ """
305
+
306
+ slug: str
307
+ version: str
308
+ question: AnyQuestion
309
+ path: Path
310
+ status: QuestionStatus = "PUBLISHED"
311
+ #: Attachment name -> sha-256 of its bytes, for the linked attachments.
312
+ files: Mapping[str, str] = field(default_factory=dict)
313
+ #: Sha-256 -> the file its bytes are read from when the server lacks them.
314
+ blobs: Mapping[str, Path] = field(default_factory=dict)
315
+
316
+
317
+ @dataclass(frozen=True)
318
+ class DeleteQuestion:
319
+ """
320
+ A question to delete by slug: its local file is gone.
321
+ """
322
+
323
+ slug: str
324
+
325
+
326
+ @dataclass(frozen=True)
327
+ class UpsertExam:
328
+ """
329
+ One exam to `PUT`: its payload, plus the `status` and `rev` that stay
330
+ out of it.
331
+ """
332
+
333
+ slug: str
334
+ payload: Payload
335
+ status: ExamStatus
336
+ rev: str
337
+ path: Path
338
+ #: Sha-256 -> the file its bytes are read from when the server lacks them.
339
+ blobs: Mapping[str, Path] = field(default_factory=dict)
340
+
341
+
342
+ @dataclass(frozen=True)
343
+ class DeleteExam:
344
+ """
345
+ An exam to delete by slug: its local file is gone. The server archives it.
346
+ """
347
+
348
+ slug: str
349
+
350
+
351
+ @dataclass(frozen=True)
352
+ class UpsertTimeSlot:
353
+ """
354
+ One time slot to `PUT`, carried whole.
355
+ """
356
+
357
+ slot: TimeSlot
358
+
359
+
360
+ @dataclass(frozen=True)
361
+ class DeleteTimeSlot:
362
+ """
363
+ A time slot to hard-delete by slug: its `days:` entry is gone.
364
+ """
365
+
366
+ slug: str
367
+
368
+
369
+ @dataclass(frozen=True)
370
+ class UpsertCalendarEvent:
371
+ """
372
+ One calendar event to `PUT`, carried whole.
373
+ """
374
+
375
+ event: Event
376
+
377
+
378
+ @dataclass(frozen=True)
379
+ class DeleteCalendarEvent:
380
+ """
381
+ A calendar event to hard-delete, by the `(week, timeSlot)` pair that
382
+ is both its primary key and its URL.
383
+ """
384
+
385
+ week: int
386
+ time_slot: str
387
+
388
+
389
+ @dataclass(frozen=True)
390
+ class DeleteRollCall:
391
+ """
392
+ A roll call to delete, by the `(week, timeSlot)` of its event.
393
+ """
394
+
395
+ week: int
396
+ time_slot: str
397
+
398
+
399
+ @dataclass(frozen=True)
400
+ class UpsertGradeColumn:
401
+ """
402
+ One grade column to `PUT`, whole: the server replaces its values with
403
+ the ones carried here.
404
+ """
405
+
406
+ column: GradeColumn
407
+
408
+
409
+ @dataclass(frozen=True)
410
+ class DeleteGradeColumn:
411
+ """
412
+ A grade column to delete by slug: `codehood.toml` no longer declares it.
413
+ """
414
+
415
+ slug: str
416
+
417
+
418
+ @dataclass(frozen=True)
419
+ class UpsertRepository:
420
+ """
421
+ One repository to create if missing and commit `tree` to.
422
+
423
+ `message` is the `-m/--message` of the push, `None` for the server's
424
+ default.
425
+ """
426
+
427
+ tree: RepositoryTree
428
+ message: str | None = None
429
+
430
+
431
+ @dataclass(frozen=True)
432
+ class DeleteRepository:
433
+ """
434
+ A repository to delete by slug: its folder is gone and the push ran with
435
+ `--drop-repositories`.
436
+ """
437
+
438
+ slug: str
439
+
440
+
441
+ Write = (
442
+ UpsertCourse
443
+ | UpsertRepository
444
+ | DeleteRepository
445
+ | UpsertResource
446
+ | DeleteResource
447
+ | UpsertQuestion
448
+ | DeleteQuestion
449
+ | UpsertExam
450
+ | DeleteExam
451
+ | UpsertTimeSlot
452
+ | DeleteTimeSlot
453
+ | UpsertCalendarEvent
454
+ | DeleteCalendarEvent
455
+ | DeleteRollCall
456
+ | UpsertGradeColumn
457
+ | DeleteGradeColumn
458
+ )
459
+
460
+
461
+ #
462
+ # Notices
463
+ #
464
+ @dataclass(frozen=True)
465
+ class Rejected:
466
+ """
467
+ A question file `mdq` refused. The server keeps what it holds under the
468
+ slug and the push fails.
469
+ """
470
+
471
+ slug: str
472
+ path: Path
473
+ reason: str
474
+ #: What the refused file holds.
475
+ kind: Literal["question", "exam"] = "question"
476
+
477
+
478
+ @dataclass(frozen=True)
479
+ class KeptDraftPublished:
480
+ """
481
+ A question whose file marks it a draft, kept as the server has it
482
+ because a push never moves a question back down its status.
483
+ """
484
+
485
+ slug: str
486
+ status: QuestionStatus
487
+ path: Path
488
+
489
+
490
+ @dataclass(frozen=True)
491
+ class KeptExamLive:
492
+ """
493
+ An exam the server has moved to `ONGOING` or `COMPLETED`, kept at that
494
+ status whatever the file says: a push never takes a running exam back.
495
+
496
+ `wanted` is the status the file asks for, `None` when its file is gone.
497
+ """
498
+
499
+ slug: str
500
+ status: ExamStatus
501
+ wanted: LocalExamStatus | None
502
+ path: Path | None = None
503
+
504
+
505
+ @dataclass(frozen=True)
506
+ class KeptPinnedSlot:
507
+ """
508
+ A time slot the preflight would otherwise prune, kept because the
509
+ `CANCELLED` calendar events of `weeks` still pin it.
510
+
511
+ A cancelled event is never rewritten or pruned (see the mapping's
512
+ "Calendar events"), and the server refuses to orphan it -- see
513
+ "Deletion and pruning".
514
+ """
515
+
516
+ slug: str
517
+ weeks: tuple[int, ...]
518
+
519
+
520
+ @dataclass(frozen=True)
521
+ class KeptForRollCall:
522
+ """
523
+ A calendar event kept, though gone locally, because it has a roll call.
524
+
525
+ Reported even when the roll call holds no attendance.
526
+ """
527
+
528
+ week: int
529
+ time_slot: str
530
+ attendances: int
531
+
532
+
533
+ @dataclass(frozen=True)
534
+ class KeptRepository:
535
+ """
536
+ A repository the server has and the course root no longer does, kept
537
+ because deleting it kills its clone URL and history.
538
+ """
539
+
540
+ slug: str
541
+
542
+
543
+ @dataclass(frozen=True)
544
+ class KeptCancelled:
545
+ """
546
+ A calendar event the server reports as `CANCELLED`, left alone whatever
547
+ the repository says.
548
+
549
+ Only an input of the plan: it pins the event's slot, and `_sync_calendar`
550
+ folds it into a `KeptPinnedSlot`, so it never reaches `Plan.notices`.
551
+ """
552
+
553
+ week: int
554
+ time_slot: str
555
+
556
+
557
+ @dataclass(frozen=True)
558
+ class ServerDrifted:
559
+ """
560
+ An entity pushed one way only (a grade column) that the server holds in a
561
+ form other than the base: the push overwrites it, and this says which
562
+ `fields` of it are lost.
563
+ """
564
+
565
+ kind: EntityKind
566
+ key: str
567
+ fields: tuple[str, ...]
568
+
569
+
570
+ Notice = (
571
+ Rejected
572
+ | ServerDrifted
573
+ | KeptDraftPublished
574
+ | KeptExamLive
575
+ | IgnoredExamPolicy
576
+ | KeptPinnedSlot
577
+ | KeptForRollCall
578
+ | KeptRepository
579
+ | KeptCancelled
580
+ )
581
+
582
+
583
+ @dataclass(frozen=True)
584
+ class Plan:
585
+ """
586
+ What a push will write and what it leaves alone, and why.
587
+
588
+ `writes` is in execution order. `notices` explain what the plan did not
589
+ write; a `Rejected` one also makes the push fail.
590
+
591
+ The rest is what a three-way plan adds. `pulls`, `conflicts` and
592
+ `other_cli` are the entities the plan does not write to the server.
593
+ `base_updates` are the changes of the base that need no execution: an
594
+ entity both sides agree on, and one gone from both. `confirmations` pair a
595
+ write with the base update to apply once it succeeds.
596
+ """
597
+
598
+ writes: tuple[Write, ...] = ()
599
+ notices: tuple[Notice, ...] = ()
600
+ pulls: tuple[Pull, ...] = ()
601
+ conflicts: tuple[Conflict, ...] = ()
602
+ other_cli: tuple[OtherCli, ...] = ()
603
+ base_updates: tuple[BaseUpdate, ...] = ()
604
+ confirmations: tuple[Confirmation, ...] = ()
605
+
606
+ @classmethod
607
+ def of(cls, decisions: Iterable[Decision]) -> Plan:
608
+ """
609
+ Collect decisions, in order, into the writes and notices they carry.
610
+ """
611
+ writes: list[Write] = []
612
+ notices: list[Notice] = []
613
+ pulls: list[Pull] = []
614
+ conflicts: list[Conflict] = []
615
+ other_cli: list[OtherCli] = []
616
+ updates: list[BaseUpdate] = []
617
+ confirmations: list[Confirmation] = []
618
+ for decision in decisions:
619
+ match decision:
620
+ case Put(op=op, notices=extra, base=base):
621
+ writes.append(op)
622
+ notices.extend(extra)
623
+ if base is not None:
624
+ confirmations.append(Confirmation(op, base))
625
+ case Prune(op=op, before=before, notices=extra, base=base):
626
+ writes.extend((*before, op))
627
+ notices.extend(extra)
628
+ if base is not None:
629
+ confirmations.append(Confirmation(op, base))
630
+ case Keep(notice=notice, base=base):
631
+ notices.append(notice)
632
+ if base is not None:
633
+ updates.append(base)
634
+ case Skip(base=base):
635
+ if base is not None:
636
+ updates.append(base)
637
+ case Pull():
638
+ pulls.append(decision)
639
+ case Conflict():
640
+ conflicts.append(decision)
641
+ case OtherCli():
642
+ other_cli.append(decision)
643
+ return cls(
644
+ tuple(writes),
645
+ tuple(notices),
646
+ tuple(pulls),
647
+ tuple(conflicts),
648
+ tuple(other_cli),
649
+ tuple(updates),
650
+ tuple(confirmations),
651
+ )
652
+
653
+ @property
654
+ def rejected(self) -> tuple[Rejected, ...]:
655
+ """
656
+ The notices that fail the push.
657
+ """
658
+ return tuple(n for n in self.notices if isinstance(n, Rejected))
659
+
660
+ def __add__(self, other: Plan) -> Plan:
661
+ return Plan(
662
+ self.writes + other.writes,
663
+ self.notices + other.notices,
664
+ self.pulls + other.pulls,
665
+ self.conflicts + other.conflicts,
666
+ self.other_cli + other.other_cli,
667
+ self.base_updates + other.base_updates,
668
+ self.confirmations + other.confirmations,
669
+ )
670
+
671
+
672
+ #
673
+ # Decisions
674
+ #
675
+ #: The kinds of entity a plan compares against the base, one per `BaseState`
676
+ #: collection.
677
+ type EntityKind = Literal[
678
+ "course",
679
+ "resource",
680
+ "question",
681
+ "exam",
682
+ "time_slot",
683
+ "calendar_event",
684
+ "grade_column",
685
+ ]
686
+
687
+
688
+ @dataclass(frozen=True)
689
+ class BaseUpdate:
690
+ """
691
+ The base entry of `key` to store, `None` to drop it.
692
+
693
+ Carried by a `Skip` or `Keep` it applies at once. Carried by a `Put` or
694
+ `Prune` it applies once the write succeeds, and then `entry.rev` and
695
+ `entry.updated_at` are placeholders (`None`): the server's answer to the
696
+ write fills them. `entry.payload` is always the local payload.
697
+ """
698
+
699
+ kind: EntityKind
700
+ key: str
701
+ entry: BaseEntry | None
702
+
703
+
704
+ @dataclass(frozen=True)
705
+ class Confirmation:
706
+ """
707
+ A `write` of the plan and the base update to apply when it succeeds.
708
+ """
709
+
710
+ write: Write
711
+ update: BaseUpdate
712
+
713
+
714
+ @dataclass(frozen=True)
715
+ class Skip:
716
+ """
717
+ Both sides already agree, or something protects the server's copy.
718
+
719
+ `base` is the update to the base that agreeing leaves to record, if any.
720
+ """
721
+
722
+ base: BaseUpdate | None = None
723
+
724
+
725
+ @dataclass(frozen=True)
726
+ class Put:
727
+ """
728
+ Write `op`, and tell why the write is not the whole story.
729
+
730
+ `base` is what to record once the write succeeds.
731
+ """
732
+
733
+ op: Write
734
+ notices: tuple[Notice, ...] = ()
735
+ base: BaseUpdate | None = None
736
+
737
+
738
+ @dataclass(frozen=True)
739
+ class Prune:
740
+ """
741
+ Delete what the repository no longer holds, after the `before` writes
742
+ the delete depends on.
743
+
744
+ `base` is what to record once the delete succeeds.
745
+ """
746
+
747
+ op: Write
748
+ before: tuple[Write, ...] = ()
749
+ base: BaseUpdate | None = None
750
+ notices: tuple[Notice, ...] = ()
751
+
752
+
753
+ @dataclass(frozen=True)
754
+ class Keep:
755
+ """
756
+ Write nothing, and say why.
757
+ """
758
+
759
+ notice: Notice
760
+ base: BaseUpdate | None = None
761
+
762
+
763
+ @dataclass(frozen=True)
764
+ class Pull:
765
+ """
766
+ The server changed and the repository did not: bring the change down.
767
+
768
+ `change` tells a creation, an alteration and a removal apart. `remote` is
769
+ the server's entry (`None` for a removal) and `fields` the top-level
770
+ payload keys that differ from the base.
771
+ """
772
+
773
+ kind: EntityKind
774
+ key: str
775
+ change: Literal["create", "update", "delete"]
776
+ fields: tuple[str, ...]
777
+ remote: RemoteEntry | None = None
778
+
779
+
780
+ #: Why a `Conflict` is one.
781
+ type ConflictReason = Literal[
782
+ "both-changed",
783
+ "local-edited-remote-deleted",
784
+ "local-deleted-remote-edited",
785
+ "no-base",
786
+ "rename",
787
+ "link",
788
+ "referenced",
789
+ "event-linked",
790
+ "slot-in-use",
791
+ ]
792
+
793
+
794
+ @dataclass(frozen=True)
795
+ class Conflict:
796
+ """
797
+ Both sides moved apart and no rule says which one wins.
798
+
799
+ `ours` holds the operations that settle it for the repository, empty when
800
+ there is none: a `Put`, a `Prune`, or a `Put` and a `Prune` for a
801
+ rename. `renamed_to` is the new key of a rename, `key` the old one.
802
+ """
803
+
804
+ kind: EntityKind
805
+ key: str
806
+ fields: tuple[str, ...]
807
+ reason: ConflictReason
808
+ ours: tuple[Put | Prune, ...] = ()
809
+ renamed_to: str | None = None
810
+
811
+
812
+ @dataclass(frozen=True)
813
+ class OtherCli:
814
+ """
815
+ The server changed through another CLI: its source is in git, so the
816
+ answer is a `git pull`, not a `Pull`.
817
+
818
+ `ours` is what a `Conflict`'s is: the operations that make the repository
819
+ win, for when the source is gone from git too. Nothing runs them unless
820
+ the user asks with `--ours`.
821
+ """
822
+
823
+ kind: EntityKind
824
+ key: str
825
+ fields: tuple[str, ...]
826
+ renamed_to: str | None = None
827
+ ours: tuple[Put | Prune, ...] = ()
828
+
829
+
830
+ Decision = Skip | Put | Prune | Keep | Pull | Conflict | OtherCli
831
+
832
+
833
+ def diff_keyed[K, L, S](
834
+ local: Mapping[K, L],
835
+ server: Mapping[K, S],
836
+ merge: Callable[[K, L | None, S | None], Decision],
837
+ ) -> Iterator[Decision]:
838
+ """
839
+ Ask `merge` for a decision on every key of either side: the local keys
840
+ in local order, then the server-only keys in key order.
841
+
842
+ `merge` receives the key too, since a server marker alone often cannot
843
+ name what to delete. A side that lacks the key gives `None`.
844
+ """
845
+ for key, value in local.items():
846
+ yield merge(key, value, server.get(key))
847
+ for key in sorted(server.keys() - local.keys()): # type: ignore[type-var]
848
+ yield merge(key, None, server[key])
849
+
850
+
851
+ def join_status(a: QuestionStatus, b: QuestionStatus) -> QuestionStatus:
852
+ """
853
+ The further of two statuses along `STATUS_ORDER`.
854
+ """
855
+ return max(a, b, key=STATUS_ORDER.index)
856
+
857
+
858
+ #
859
+ # Merges
860
+ #
861
+ def merge_event(
862
+ key: tuple[int, str],
863
+ local: Event | None,
864
+ server: ServerEvent | None,
865
+ *,
866
+ drop_roll_calls: bool = False,
867
+ ) -> Decision:
868
+ """
869
+ Upsert an event whose `(ref, kind)` differs from the server's; delete one
870
+ the calendar no longer fills.
871
+
872
+ A `CANCELLED` server event absorbs everything: it is neither rewritten
873
+ nor pruned, whatever the repository says. An event with a roll call is
874
+ kept, unless `drop_roll_calls` deletes the roll call first.
875
+ """
876
+ week, time_slot = key
877
+ if server is not None and server.kind == "CANCELLED":
878
+ return Keep(KeptCancelled(week=week, time_slot=time_slot))
879
+ if local is not None:
880
+ if server is not None and (server.ref, server.kind) == (local.ref, local.kind):
881
+ return Skip()
882
+ return Put(UpsertCalendarEvent(event=local))
883
+ if server is None:
884
+ return Skip()
885
+ delete = DeleteCalendarEvent(week=week, time_slot=time_slot)
886
+ if server.attendances is None:
887
+ return Prune(delete)
888
+ if drop_roll_calls:
889
+ return Prune(delete, before=(DeleteRollCall(week=week, time_slot=time_slot),))
890
+ return Keep(
891
+ KeptForRollCall(week=week, time_slot=time_slot, attendances=server.attendances)
892
+ )
893
+
894
+
895
+ def merge_repository(
896
+ slug: str,
897
+ local: RepositoryTree | None,
898
+ server: str | None,
899
+ *,
900
+ drop_repositories: bool = False,
901
+ message: str | None = None,
902
+ ) -> Decision:
903
+ """
904
+ Commit a repository whose `tree_sha` differs from the server's tree
905
+ (`None` before the first commit included); keep or, with
906
+ `drop_repositories`, delete one whose folder is gone.
907
+ """
908
+ if local is None:
909
+ if drop_repositories:
910
+ return Prune(DeleteRepository(slug=slug))
911
+ return Keep(KeptRepository(slug=slug))
912
+ if server == local.tree_sha:
913
+ return Skip()
914
+ return Put(UpsertRepository(tree=local, message=message))
915
+
916
+
917
+ def plan_repositories(
918
+ local: LocalState,
919
+ server: ServerState,
920
+ *,
921
+ drop_repositories: bool = False,
922
+ message: str | None = None,
923
+ ) -> Plan:
924
+ """
925
+ The repository half of a plan, in slug order.
926
+
927
+ A local repository gets an `UpsertRepository` when the server lacks it
928
+ or reports a `tree` other than its `tree_sha` (`None` included). A
929
+ server repository with no local folder gets a `KeptRepository`, or
930
+ a `DeleteRepository` with `drop_repositories`.
931
+ """
932
+ merge = partial(
933
+ merge_repository, drop_repositories=drop_repositories, message=message
934
+ )
935
+ return Plan.of(
936
+ diff_keyed(
937
+ {tree.slug: tree for tree in local.repositories}, server.repositories, merge
938
+ )
939
+ )
940
+
941
+
942
+ #
943
+ # Three-way sync
944
+ #
945
+ #: The `BaseState` key of the one course row.
946
+ COURSE_KEY = "course"
947
+
948
+ #: Payload fields that make up an entity's key, which a rename changes.
949
+ _SLUG = ("slug",)
950
+ _EVENT_KEY = ("week", "timeSlot")
951
+
952
+ _MISSING = object()
953
+
954
+
955
+ def event_key(week: int, time_slot: str) -> str:
956
+ """
957
+ The base key of a calendar event: `"<week>/<time slot>"`.
958
+ """
959
+ return f"{week}/{time_slot}"
960
+
961
+
962
+ def parse_event_key(key: str) -> tuple[int, str]:
963
+ """
964
+ The `(week, time slot)` of a base key made by `event_key`.
965
+
966
+ Raises:
967
+ ValueError: `key` is not of that form.
968
+ """
969
+ week, sep, time_slot = key.partition("/")
970
+ if not sep or not time_slot:
971
+ raise ValueError(f"not an event key: {key!r}")
972
+ return int(week), time_slot
973
+
974
+
975
+ def diff_fields(a: Payload | None, b: Payload | None) -> tuple[str, ...]:
976
+ """
977
+ The sorted top-level keys whose values differ between two payloads, where
978
+ a side that is `None` holds none.
979
+ """
980
+ left, right = a or {}, b or {}
981
+ return tuple(
982
+ sorted(
983
+ key
984
+ for key in left.keys() | right.keys()
985
+ if left.get(key, _MISSING) != right.get(key, _MISSING)
986
+ )
987
+ )
988
+
989
+
990
+ def three_way(
991
+ kind: EntityKind,
992
+ key: str,
993
+ local: Payload | None,
994
+ base: BaseEntry | None,
995
+ remote: RemoteEntry | None,
996
+ *,
997
+ local_ref: str | None = None,
998
+ server_ref: str | None = None,
999
+ put: Callable[[], Put],
1000
+ prune: Callable[[], Decision],
1001
+ ) -> Decision:
1002
+ """
1003
+ Decide one entity from its local, base and server payloads.
1004
+
1005
+ `put` and `prune` build the write that moves the server to the local
1006
+ side; `prune` may answer a `Keep` when something protects the entity.
1007
+ `local_ref` and `server_ref` are the hash the local side computes and the
1008
+ one the server stores, used only when the base is absent: equal ones mean
1009
+ the server holds what this checkout last sent.
1010
+
1011
+ The server changed through another CLI when its `rev` is not the base's;
1012
+ that takes precedence over a conflict. See the RFC's decision table.
1013
+ """
1014
+
1015
+ stored = base
1016
+
1017
+ def put_() -> Put:
1018
+ assert local is not None
1019
+ return replace(put(), base=BaseUpdate(kind, key, BaseEntry(local)))
1020
+
1021
+ def prune_() -> Decision:
1022
+ decision = prune()
1023
+ if isinstance(decision, Prune):
1024
+ return replace(decision, base=BaseUpdate(kind, key, None))
1025
+ return decision
1026
+
1027
+ def ours_prune() -> tuple[Put | Prune, ...]:
1028
+ decision = prune_()
1029
+ return (decision,) if isinstance(decision, Prune) else ()
1030
+
1031
+ def adopt() -> Skip:
1032
+ assert local is not None and remote is not None
1033
+ entry = BaseEntry(local, remote.rev, remote.updated_at)
1034
+ stale = stored is None or (stored.payload, stored.rev) != (local, remote.rev)
1035
+ return Skip(BaseUpdate(kind, key, entry) if stale else None)
1036
+
1037
+ if base is None:
1038
+ if local is None:
1039
+ if remote is None:
1040
+ return Skip()
1041
+ fields = diff_fields(None, remote.payload)
1042
+ if remote.rev is None:
1043
+ return Pull(kind, key, "create", fields, remote)
1044
+ return OtherCli(kind, key, fields, ours=ours_prune())
1045
+ if remote is None:
1046
+ return put_()
1047
+ if server_ref is not None and server_ref == local_ref:
1048
+ base = BaseEntry(local, remote.rev, remote.updated_at)
1049
+ elif local == remote.payload:
1050
+ return adopt()
1051
+ else:
1052
+ fields = diff_fields(local, remote.payload)
1053
+ return Conflict(kind, key, fields, "no-base", ours=(put_(),))
1054
+ assert base is not None
1055
+ if local is None:
1056
+ if remote is None:
1057
+ return Skip(BaseUpdate(kind, key, None))
1058
+ if remote.payload == base.payload:
1059
+ return prune_()
1060
+ fields = diff_fields(base.payload, remote.payload)
1061
+ if remote.rev != base.rev:
1062
+ return OtherCli(kind, key, fields, ours=ours_prune())
1063
+ return Conflict(kind, key, fields, "local-deleted-remote-edited", ours_prune())
1064
+ if remote is None:
1065
+ if local == base.payload:
1066
+ return Pull(kind, key, "delete", diff_fields(base.payload, None))
1067
+ fields = diff_fields(local, None)
1068
+ return Conflict(
1069
+ kind, key, fields, "local-edited-remote-deleted", ours=(put_(),)
1070
+ )
1071
+ local_changed = local != base.payload
1072
+ remote_changed = remote.payload != base.payload
1073
+ if local == remote.payload:
1074
+ return adopt()
1075
+ if not remote_changed:
1076
+ return put_()
1077
+ if remote.rev != base.rev:
1078
+ return OtherCli(
1079
+ kind,
1080
+ key,
1081
+ diff_fields(base.payload, remote.payload),
1082
+ ours=(put_(),),
1083
+ )
1084
+ if not local_changed:
1085
+ return Pull(
1086
+ kind, key, "update", diff_fields(base.payload, remote.payload), remote
1087
+ )
1088
+ return Conflict(
1089
+ kind, key, diff_fields(local, remote.payload), "both-changed", ours=(put_(),)
1090
+ )
1091
+
1092
+
1093
+ def plan_sync(
1094
+ local: LocalState,
1095
+ base: BaseState,
1096
+ remote: ServerState,
1097
+ *,
1098
+ drop_roll_calls: bool = False,
1099
+ drop_repositories: bool = False,
1100
+ message: str | None = None,
1101
+ ours: Sequence[str] = (),
1102
+ ) -> Plan:
1103
+ """
1104
+ Compare a repository, the base and the server by entity, by natural key,
1105
+ into a `Plan`.
1106
+
1107
+ `ours` are the `--ours` globs of the push: what they settle counts as
1108
+ already done when the calendar checks what still holds an event or a
1109
+ slot, so one push removes both. The conflicts themselves stay in the
1110
+ plan for `resolve_ours` to settle.
1111
+
1112
+ Each entity goes through `three_way` on payloads in the wire format:
1113
+ local through the `wire` constructors, base and server as stored. The
1114
+ plan keeps the order: course, repositories, calendar, resources,
1115
+ questions, exams, grade columns. Repositories and grade columns stay one-way:
1116
+ the repository overwrites, and a grade column the server holds in a form
1117
+ other than the base's gets a `ServerDrifted` notice.
1118
+
1119
+ The course row is never pulled for removal: a course missing on the
1120
+ server is written back.
1121
+ """
1122
+ local = _with_inline_questions(local)
1123
+ resources = _sync_resources(local, base, remote)
1124
+ return (
1125
+ _sync_course(local, base, remote)
1126
+ + plan_repositories(
1127
+ local, remote, drop_repositories=drop_repositories, message=message
1128
+ )
1129
+ + _sync_calendar(
1130
+ local,
1131
+ base,
1132
+ remote,
1133
+ _settled(resources, ours),
1134
+ drop_roll_calls=drop_roll_calls,
1135
+ ours=ours,
1136
+ )
1137
+ + Plan.of(resources)
1138
+ + Plan.of(
1139
+ _sync_questions(
1140
+ local, base, remote, _kept_exam_questions(local, base, remote)
1141
+ )
1142
+ )
1143
+ + _sync_exams(local, base, remote)
1144
+ + _sync_grades(local, base, remote)
1145
+ )
1146
+
1147
+
1148
+ def _sync_course(local: LocalState, base: BaseState, remote: ServerState) -> Plan:
1149
+ start_date, end_date = local.start.isoformat(), local.end.isoformat()
1150
+ ref = course_ref(local.description, start_date, end_date)
1151
+ payload = course_payload(local.key, local.description, local.start, local.end)
1152
+ op = UpsertCourse(
1153
+ key=local.key,
1154
+ description=local.description,
1155
+ start_date=start_date,
1156
+ end_date=end_date,
1157
+ ref=ref,
1158
+ )
1159
+ entry = remote.course if remote.course_exists else None
1160
+ if entry is None:
1161
+ return Plan.of(
1162
+ [Put(op, base=BaseUpdate("course", COURSE_KEY, BaseEntry(payload)))]
1163
+ )
1164
+ decision = three_way(
1165
+ "course",
1166
+ COURSE_KEY,
1167
+ payload,
1168
+ base.course.get(COURSE_KEY),
1169
+ entry,
1170
+ local_ref=ref,
1171
+ server_ref=entry.rev,
1172
+ put=lambda: Put(op),
1173
+ prune=lambda: Skip(),
1174
+ )
1175
+ return Plan.of([decision])
1176
+
1177
+
1178
+ def _sync_kind(
1179
+ kind: EntityKind,
1180
+ local: Mapping[str, Payload],
1181
+ base: Mapping[str, BaseEntry],
1182
+ remote: Mapping[str, RemoteEntry],
1183
+ decide: Callable[
1184
+ [str, Payload | None, BaseEntry | None, RemoteEntry | None], Decision
1185
+ ],
1186
+ *,
1187
+ key_fields: tuple[str, ...] = _SLUG,
1188
+ extra: Iterable[str] = (),
1189
+ ) -> list[Decision]:
1190
+ """
1191
+ Run `decide` on every key of the three sides: local keys in local order,
1192
+ then the others in key order. A new local entity and a locally deleted
1193
+ one that are the same apart from their key, the deleted one changed on
1194
+ the server, become one rename. `extra` are keys with no payload that
1195
+ `decide` still has to see.
1196
+ """
1197
+ extras = [k for k in extra if k not in local]
1198
+ keys = [
1199
+ *local,
1200
+ *extras,
1201
+ *sorted((base.keys() | remote.keys()) - local.keys() - set(extras)),
1202
+ ]
1203
+ decisions = {
1204
+ key: decide(key, local.get(key), base.get(key), remote.get(key)) for key in keys
1205
+ }
1206
+ new = [
1207
+ key
1208
+ for key, decision in decisions.items()
1209
+ if isinstance(decision, Put)
1210
+ and key in local
1211
+ and key not in base
1212
+ and key not in remote
1213
+ ]
1214
+ for old, decision in list(decisions.items()):
1215
+ if old in local or old not in base or old not in remote:
1216
+ continue
1217
+ if not isinstance(decision, OtherCli) and not (
1218
+ isinstance(decision, Conflict)
1219
+ and decision.reason == "local-deleted-remote-edited"
1220
+ ):
1221
+ continue
1222
+ shape = _without(base[old].payload, key_fields)
1223
+ found = next((k for k in new if _without(local[k], key_fields) == shape), None)
1224
+ if found is None:
1225
+ continue
1226
+ new.remove(found)
1227
+ added = decisions.pop(found)
1228
+ if isinstance(decision, OtherCli):
1229
+ ours = (added, *decision.ours) if isinstance(added, Put) else ()
1230
+ decisions[old] = replace(decision, renamed_to=found, ours=ours)
1231
+ elif isinstance(added, Put):
1232
+ decisions[old] = Conflict(
1233
+ kind,
1234
+ old,
1235
+ decision.fields,
1236
+ "rename",
1237
+ ours=(added, *decision.ours),
1238
+ renamed_to=found,
1239
+ )
1240
+ return list(decisions.values())
1241
+
1242
+
1243
+ def _sync_resources(
1244
+ local: LocalState, base: BaseState, remote: ServerState
1245
+ ) -> list[Decision]:
1246
+ files = {file.slug: file for file in local.resources}
1247
+ excluded = _excluded(local, "resource")
1248
+
1249
+ def decide(
1250
+ key: str,
1251
+ payload: Payload | None,
1252
+ entry: BaseEntry | None,
1253
+ server: RemoteEntry | None,
1254
+ ) -> Decision:
1255
+ if payload is None and key in excluded:
1256
+ return Skip()
1257
+ file = files.get(key)
1258
+ decision = three_way(
1259
+ "resource",
1260
+ key,
1261
+ payload,
1262
+ entry,
1263
+ server,
1264
+ local_ref=file.ref if file else None,
1265
+ server_ref=server.rev if server else None,
1266
+ put=lambda: Put(_upsert_resource(files[key])),
1267
+ prune=lambda: Prune(DeleteResource(slug=key)),
1268
+ )
1269
+ if not isinstance(decision, Pull):
1270
+ return decision
1271
+ ours = (
1272
+ (_put("resource", key, payload, _upsert_resource(file)),)
1273
+ if file is not None and payload is not None
1274
+ else ()
1275
+ )
1276
+ if decision.change == "delete":
1277
+ if file is not None and file.event is not None:
1278
+ return Conflict("resource", key, decision.fields, "referenced", ours)
1279
+ return decision
1280
+ assert decision.remote is not None
1281
+ stored = entry.payload if entry else payload
1282
+ before = resource_event_of(stored) if stored is not None else None
1283
+ if resource_event_of(decision.remote.payload) != before:
1284
+ return Conflict("resource", key, decision.fields, "link", ours)
1285
+ return decision
1286
+
1287
+ return _sync_kind(
1288
+ "resource",
1289
+ {slug: resource_payload(file) for slug, file in files.items()},
1290
+ base.resources,
1291
+ remote.resources,
1292
+ decide,
1293
+ )
1294
+
1295
+
1296
+ def _sync_questions(
1297
+ local: LocalState,
1298
+ base: BaseState,
1299
+ remote: ServerState,
1300
+ protected: frozenset[str] = frozenset(),
1301
+ ) -> list[Decision]:
1302
+ files = {q.slug: q for q in local.questions}
1303
+ excluded = _excluded(local, "question")
1304
+ entries = {slug: question.entry for slug, question in remote.questions.items()}
1305
+
1306
+ def decide(
1307
+ key: str,
1308
+ payload: Payload | None,
1309
+ entry: BaseEntry | None,
1310
+ server: RemoteEntry | None,
1311
+ ) -> Decision:
1312
+ if payload is None and key in excluded:
1313
+ return Skip()
1314
+ file = files.get(key)
1315
+ if isinstance(file, InvalidQuestion):
1316
+ return Keep(Rejected(slug=file.slug, path=file.path, reason=file.reason))
1317
+ question = remote.questions.get(key)
1318
+ # A question stored without a `rev` was written by an earlier CLI
1319
+ # when something of ours (a base entry or a local file) tracks it:
1320
+ # its `version` is the `rev` such a CLI sends. One nothing tracks
1321
+ # was made on the server and stays without a `rev`.
1322
+ if (
1323
+ question is not None
1324
+ and server is not None
1325
+ and server.rev is None
1326
+ and (entry is not None or file is not None)
1327
+ ):
1328
+ server = replace(server, rev=question.version)
1329
+ if isinstance(file, QuestionFile):
1330
+ status = (
1331
+ join_status(file.status, question.status) if question else file.status
1332
+ )
1333
+ notices: tuple[Notice, ...] = ()
1334
+ if question is not None and (file.status, question.status) == (
1335
+ "DRAFT",
1336
+ "PUBLISHED",
1337
+ ):
1338
+ notices = (
1339
+ KeptDraftPublished(
1340
+ slug=file.slug, status=question.status, path=file.path
1341
+ ),
1342
+ )
1343
+
1344
+ def put() -> Put:
1345
+ return Put(_upsert_question(file, status), notices)
1346
+
1347
+ else:
1348
+
1349
+ def put() -> Put:
1350
+ raise AssertionError("a missing question is never written")
1351
+
1352
+ decision = three_way(
1353
+ "question",
1354
+ key,
1355
+ payload,
1356
+ entry,
1357
+ server,
1358
+ local_ref=file.version if file else None,
1359
+ server_ref=question.version if question else None,
1360
+ put=put,
1361
+ prune=lambda: Prune(DeleteQuestion(slug=key)),
1362
+ )
1363
+ if key in protected and isinstance(decision, Prune):
1364
+ return Skip()
1365
+ if not isinstance(decision, Skip) or file is None or question is None:
1366
+ return decision
1367
+ if status != question.status:
1368
+ assert payload is not None
1369
+ return _put(
1370
+ "question", key, payload, _upsert_question(file, status), notices
1371
+ )
1372
+ if notices:
1373
+ return Keep(notices[0], decision.base)
1374
+ return decision
1375
+
1376
+ return _sync_kind(
1377
+ "question",
1378
+ {
1379
+ slug: question_payload(file)
1380
+ for slug, file in files.items()
1381
+ if isinstance(file, QuestionFile)
1382
+ },
1383
+ base.questions,
1384
+ entries,
1385
+ decide,
1386
+ extra=[q.slug for q in local.questions if isinstance(q, InvalidQuestion)],
1387
+ )
1388
+
1389
+
1390
+ def _with_inline_questions(local: LocalState) -> LocalState:
1391
+ """
1392
+ `local` with the questions its exams write inline joined to `questions`,
1393
+ so they are pushed like any other.
1394
+ """
1395
+ known = {question.slug for question in local.questions}
1396
+ inline = tuple(q for q in inline_questions(local.exams) if q.slug not in known)
1397
+ return replace(local, questions=local.questions + inline) if inline else local
1398
+
1399
+
1400
+ def _sync_exams(local: LocalState, base: BaseState, remote: ServerState) -> Plan:
1401
+ files = {exam.slug: exam for exam in local.exams}
1402
+ excluded = _excluded(local, "exam")
1403
+
1404
+ def decide(
1405
+ key: str,
1406
+ payload: Payload | None,
1407
+ entry: BaseEntry | None,
1408
+ server: RemoteEntry | None,
1409
+ ) -> Decision:
1410
+ if payload is None and key in excluded:
1411
+ return Skip()
1412
+ file = files.get(key)
1413
+ if isinstance(file, InvalidExam):
1414
+ return Keep(
1415
+ Rejected(
1416
+ slug=file.slug, path=file.path, reason=file.reason, kind="exam"
1417
+ )
1418
+ )
1419
+ exam = remote.exams.get(key)
1420
+ # `duration` and `scheduledAt` may be set on the server by an
1421
+ # instructor: what the local side does not declare is not compared.
1422
+ # An omitted key takes the value the base holds, so omitting is no
1423
+ # change; one the base lacks is the server's alone and not compared.
1424
+ if payload is not None:
1425
+ payload = _carry_server_set(payload, entry)
1426
+ declared = payload if payload is not None else entry.payload if entry else None
1427
+ if declared is not None and server is not None:
1428
+ server = replace(server, payload=_declared_only(server.payload, declared))
1429
+ live = exam is not None and exam.status in LIVE_STATUSES
1430
+ status: ExamStatus
1431
+ notices: tuple[Notice, ...] = ()
1432
+ if isinstance(file, ExamFile):
1433
+ status = exam.status if exam is not None and live else file.status
1434
+ if exam is not None and live:
1435
+ notices = (
1436
+ KeptExamLive(
1437
+ slug=key, status=exam.status, wanted=file.status, path=file.path
1438
+ ),
1439
+ )
1440
+
1441
+ def put() -> Put:
1442
+ return Put(_upsert_exam(file, status, payload), notices)
1443
+
1444
+ else:
1445
+ status = "DRAFT"
1446
+
1447
+ def put() -> Put:
1448
+ raise AssertionError("a missing exam is never written")
1449
+
1450
+ def prune() -> Decision:
1451
+ if exam is not None and live:
1452
+ return Keep(KeptExamLive(slug=key, status=exam.status, wanted=None))
1453
+ return Prune(DeleteExam(slug=key))
1454
+
1455
+ decision = three_way(
1456
+ "exam",
1457
+ key,
1458
+ payload,
1459
+ entry,
1460
+ server,
1461
+ local_ref=file.rev if isinstance(file, ExamFile) else None,
1462
+ server_ref=server.rev if server else None,
1463
+ put=put,
1464
+ prune=prune,
1465
+ )
1466
+ if not isinstance(decision, Skip) or not isinstance(file, ExamFile):
1467
+ return decision
1468
+ if exam is None:
1469
+ return decision
1470
+ if status != exam.status:
1471
+ assert payload is not None
1472
+ return _put(
1473
+ "exam", key, payload, _upsert_exam(file, status, payload), notices
1474
+ )
1475
+ if notices:
1476
+ return Keep(notices[0], decision.base)
1477
+ return decision
1478
+
1479
+ decisions = _sync_kind(
1480
+ "exam",
1481
+ {
1482
+ slug: exam_payload(file)
1483
+ for slug, file in files.items()
1484
+ if isinstance(file, ExamFile)
1485
+ },
1486
+ base.exams,
1487
+ {slug: exam.entry for slug, exam in remote.exams.items()},
1488
+ decide,
1489
+ extra=[exam.slug for exam in local.exams if isinstance(exam, InvalidExam)],
1490
+ )
1491
+ ignored = tuple(
1492
+ IgnoredExamPolicy(file.slug, file.path, file.ignored)
1493
+ for file in files.values()
1494
+ if isinstance(file, ExamFile) and file.ignored
1495
+ )
1496
+ return Plan.of(decisions) + Plan(notices=ignored)
1497
+
1498
+
1499
+ def _carry_server_set(payload: Payload, entry: BaseEntry | None) -> Payload:
1500
+ """
1501
+ `payload` with the `duration` and `scheduledAt` it omits taken from the
1502
+ base, when the base holds them.
1503
+ """
1504
+ if entry is None:
1505
+ return payload
1506
+ carried = {
1507
+ key: entry.payload[key]
1508
+ for key in _SERVER_SET
1509
+ if key not in payload and key in entry.payload
1510
+ }
1511
+ return {**payload, **carried}
1512
+
1513
+
1514
+ def _kept_exam_questions(
1515
+ local: LocalState, base: BaseState, remote: ServerState
1516
+ ) -> frozenset[str]:
1517
+ """
1518
+ The slugs of the questions held by an exam the plan keeps, which a push
1519
+ must not prune: an invalid exam, or a running one whose file is gone.
1520
+ """
1521
+ files = {exam.slug: exam for exam in local.exams}
1522
+ kept = {slug for slug, exam in files.items() if isinstance(exam, InvalidExam)}
1523
+ kept |= _excluded(local, "exam")
1524
+ kept |= {
1525
+ slug
1526
+ for slug, exam in remote.exams.items()
1527
+ if slug not in files and exam.status in LIVE_STATUSES
1528
+ }
1529
+ payloads: list[Payload] = []
1530
+ for slug in kept:
1531
+ if slug in base.exams:
1532
+ payloads.append(base.exams[slug].payload)
1533
+ if slug in remote.exams:
1534
+ payloads.append(remote.exams[slug].entry.payload)
1535
+ held: set[str] = set()
1536
+ for payload in payloads:
1537
+ questions = payload.get("questions")
1538
+ for item in questions if isinstance(questions, list) else ():
1539
+ if isinstance(item, dict) and isinstance(item.get("slug"), str):
1540
+ held.add(str(item["slug"]))
1541
+ return frozenset(held)
1542
+
1543
+
1544
+ def _declared_only(server: Payload, declared: Payload) -> Payload:
1545
+ """
1546
+ `server` without the `duration` and `scheduledAt` that `declared` leaves
1547
+ out.
1548
+ """
1549
+ return _without(server, tuple(k for k in _SERVER_SET if k not in declared))
1550
+
1551
+
1552
+ #: Payload fields of an exam that the server may set on its own.
1553
+ _SERVER_SET = ("duration", "scheduledAt")
1554
+
1555
+
1556
+ def _sync_calendar(
1557
+ local: LocalState,
1558
+ base: BaseState,
1559
+ remote: ServerState,
1560
+ resources: Iterable[Decision],
1561
+ *,
1562
+ drop_roll_calls: bool,
1563
+ ours: Sequence[str] = (),
1564
+ ) -> Plan:
1565
+ """
1566
+ The calendar half of a three-way plan.
1567
+
1568
+ `resources` are the decisions on resources: an event is only pruned when
1569
+ no server resource stays linked to it once they run.
1570
+ """
1571
+ linked = _linked_resources(remote, resources)
1572
+ events = {event_key(e.week, e.time_slot): e for e in local.events}
1573
+ servers = {event_key(*key): ev for key, ev in remote.calendar_events.items()}
1574
+ entries = {key: ev.entry for key, ev in servers.items() if ev.kind != "CANCELLED"}
1575
+ kept_edited: list[Keep] = []
1576
+
1577
+ def decide_event(
1578
+ key: str,
1579
+ payload: Payload | None,
1580
+ entry: BaseEntry | None,
1581
+ server: RemoteEntry | None,
1582
+ ) -> Decision:
1583
+ week, time_slot = parse_event_key(key)
1584
+ found = servers.get(key)
1585
+ if found is not None and found.kind == "CANCELLED":
1586
+ return Keep(KeptCancelled(week=week, time_slot=time_slot))
1587
+ event = events.get(key)
1588
+ if (
1589
+ payload is None
1590
+ and server is not None
1591
+ and found is not None
1592
+ and found.attendances is not None
1593
+ and not drop_roll_calls
1594
+ ):
1595
+ kept = KeptForRollCall(
1596
+ week=week, time_slot=time_slot, attendances=found.attendances
1597
+ )
1598
+ if entry is None or entry.payload == server.payload:
1599
+ # Nothing of the server's to lose: the base follows the
1600
+ # server's rev, so the next push finds it quiet.
1601
+ adopted = BaseEntry(server.payload, server.rev, server.updated_at)
1602
+ return Keep(
1603
+ kept,
1604
+ base=None
1605
+ if entry == adopted
1606
+ else BaseUpdate("calendar_event", key, adopted),
1607
+ )
1608
+ # The server edited an event the base remembers: the base stays
1609
+ # as evidence and the edit is decided like any other.
1610
+ kept_edited.append(Keep(kept))
1611
+ decision = three_way(
1612
+ "calendar_event",
1613
+ key,
1614
+ payload,
1615
+ entry,
1616
+ server,
1617
+ local_ref=event.ref if event else None,
1618
+ server_ref=server.rev if server else None,
1619
+ put=lambda: Put(UpsertCalendarEvent(event=events[key])),
1620
+ prune=lambda: merge_event(
1621
+ (week, time_slot), None, found, drop_roll_calls=drop_roll_calls
1622
+ ),
1623
+ )
1624
+ if key not in linked:
1625
+ return decision
1626
+ if isinstance(decision, Prune):
1627
+ return Conflict("calendar_event", key, tuple(linked[key]), "event-linked")
1628
+ if isinstance(decision, OtherCli | Conflict):
1629
+ return replace(decision, ours=_without_prunes(decision.ours))
1630
+ return decision
1631
+
1632
+ cancelled = {
1633
+ k: RemoteEntry({}) for k, ev in servers.items() if ev.kind == "CANCELLED"
1634
+ }
1635
+ decided = _sync_kind(
1636
+ "calendar_event",
1637
+ {key: event_payload(event) for key, event in events.items()},
1638
+ base.calendar_events,
1639
+ {**entries, **cancelled},
1640
+ decide_event,
1641
+ key_fields=_EVENT_KEY,
1642
+ )
1643
+ pinned, pin_notices = _pin_slots(decided, {slot.slug for slot in local.slots})
1644
+ pinned = pinned | {
1645
+ parse_event_key(d.key)[1]
1646
+ for d in decided
1647
+ if isinstance(d, OtherCli | Conflict)
1648
+ and d.key not in events
1649
+ and (found := servers.get(d.key)) is not None
1650
+ and found.attendances is not None
1651
+ }
1652
+ deleted = {
1653
+ (d.op.week, d.op.time_slot)
1654
+ for d in _only(_settled(decided, ours), Prune)
1655
+ if isinstance(d.op, DeleteCalendarEvent)
1656
+ }
1657
+ held: dict[str, list[str]] = {}
1658
+ for week, time_slot in sorted(
1659
+ {*remote.calendar_events, *(parse_event_key(k) for k in events)} - deleted
1660
+ ):
1661
+ held.setdefault(time_slot, []).append(event_key(week, time_slot))
1662
+ slots = {slot.slug: slot for slot in local.slots}
1663
+
1664
+ def decide_slot(
1665
+ key: str,
1666
+ payload: Payload | None,
1667
+ entry: BaseEntry | None,
1668
+ server: RemoteEntry | None,
1669
+ ) -> Decision:
1670
+ if payload is None and key in pinned:
1671
+ return Skip()
1672
+ decision = three_way(
1673
+ "time_slot",
1674
+ key,
1675
+ payload,
1676
+ entry,
1677
+ server,
1678
+ put=lambda: Put(UpsertTimeSlot(slot=slots[key])),
1679
+ prune=lambda: Prune(DeleteTimeSlot(slug=key)),
1680
+ )
1681
+ if isinstance(decision, Prune) and key in held:
1682
+ return Conflict("time_slot", key, tuple(held[key]), "slot-in-use")
1683
+ if isinstance(decision, OtherCli | Conflict) and key in held:
1684
+ return replace(decision, ours=_without_prunes(decision.ours))
1685
+ return decision
1686
+
1687
+ decided_slots = _sync_kind(
1688
+ "time_slot",
1689
+ {key: time_slot_payload(slot) for key, slot in slots.items()},
1690
+ base.time_slots,
1691
+ remote.time_slots,
1692
+ decide_slot,
1693
+ )
1694
+ reported = [
1695
+ d
1696
+ for d in decided
1697
+ if isinstance(d, Keep) and not isinstance(d.notice, KeptCancelled)
1698
+ ] + kept_edited
1699
+ rest = [
1700
+ d
1701
+ for d in (*decided, *decided_slots)
1702
+ if isinstance(d, Skip | Pull | Conflict | OtherCli)
1703
+ ]
1704
+ return Plan.of(
1705
+ [
1706
+ *order_decisions(
1707
+ [
1708
+ *_only(decided, Prune),
1709
+ *_only(decided_slots, Prune),
1710
+ *_only(decided_slots, Put),
1711
+ *_only(decided, Put),
1712
+ ]
1713
+ ),
1714
+ *reported,
1715
+ *rest,
1716
+ ]
1717
+ ) + Plan(notices=pin_notices)
1718
+
1719
+
1720
+ def _sync_grades(local: LocalState, base: BaseState, remote: ServerState) -> Plan:
1721
+ """
1722
+ The grade columns of a plan: the repository overwrites the server, and a
1723
+ column the server changed since the base is overwritten with a notice.
1724
+ """
1725
+ if local.grade_columns is None:
1726
+ return Plan()
1727
+ columns = {column.slug: column for column in local.grade_columns}
1728
+ payloads = {slug: grade_column_payload(column) for slug, column in columns.items()}
1729
+ decisions: list[Decision] = []
1730
+ keys = [
1731
+ *columns,
1732
+ *sorted(
1733
+ (base.grade_columns.keys() | remote.grade_columns.keys()) - columns.keys()
1734
+ ),
1735
+ ]
1736
+ for key in keys:
1737
+ entry, server = base.grade_columns.get(key), remote.grade_columns.get(key)
1738
+ column = columns.get(key)
1739
+ if column is None:
1740
+ if server is None:
1741
+ if entry is not None:
1742
+ decisions.append(Skip(BaseUpdate("grade_column", key, None)))
1743
+ continue
1744
+ fields = diff_fields(entry.payload if entry else None, server.payload)
1745
+ drift = (ServerDrifted("grade_column", key, fields),) if fields else ()
1746
+ decisions.append(
1747
+ Prune(
1748
+ DeleteGradeColumn(slug=key),
1749
+ base=BaseUpdate("grade_column", key, None),
1750
+ notices=drift,
1751
+ )
1752
+ )
1753
+ continue
1754
+ payload = payloads[key]
1755
+ if server is not None and server.payload == payload:
1756
+ stale = entry is None or (entry.payload, entry.rev) != (payload, server.rev)
1757
+ update = BaseUpdate(
1758
+ "grade_column", key, BaseEntry(payload, server.rev, server.updated_at)
1759
+ )
1760
+ decisions.append(Skip(update if stale else None))
1761
+ continue
1762
+ drift = ()
1763
+ if server is not None:
1764
+ if entry is not None and server.payload != entry.payload:
1765
+ drift = (
1766
+ ServerDrifted(
1767
+ "grade_column", key, diff_fields(entry.payload, server.payload)
1768
+ ),
1769
+ )
1770
+ elif entry is None and server.rev in (None, column.rev):
1771
+ drift = (
1772
+ ServerDrifted(
1773
+ "grade_column", key, diff_fields(payload, server.payload)
1774
+ ),
1775
+ )
1776
+ put = _put("grade_column", key, payload, UpsertGradeColumn(column=column))
1777
+ decisions.append(replace(put, notices=drift))
1778
+ return Plan.of(decisions)
1779
+
1780
+
1781
+ #
1782
+ # Utilities
1783
+ #
1784
+ def _put(
1785
+ kind: EntityKind,
1786
+ key: str,
1787
+ payload: Payload,
1788
+ op: Write,
1789
+ notices: tuple[Notice, ...] = (),
1790
+ ) -> Put:
1791
+ """
1792
+ A `Put` of `op` that records `payload` in the base once it succeeds.
1793
+ """
1794
+ return Put(op, notices, BaseUpdate(kind, key, BaseEntry(payload)))
1795
+
1796
+
1797
+ def _without(payload: Payload, fields: tuple[str, ...]) -> Payload:
1798
+ return {k: v for k, v in payload.items() if k not in fields}
1799
+
1800
+
1801
+ def _excluded(local: LocalState, kind: str) -> frozenset[str]:
1802
+ """
1803
+ The slugs of `kind` that an `exclude` pattern leaves out of the push.
1804
+ """
1805
+ return frozenset(file.slug for file in local.excluded if file.kind == kind)
1806
+
1807
+
1808
+ def _linked_resources(
1809
+ remote: ServerState, decisions: Iterable[Decision]
1810
+ ) -> dict[str, list[str]]:
1811
+ """
1812
+ The slugs of the server resources linked to each event key once the
1813
+ writes in `decisions` have run.
1814
+ """
1815
+ moved: dict[str, EventKey | None] = {}
1816
+ for decision in decisions:
1817
+ if isinstance(decision, Put) and isinstance(decision.op, UpsertResource):
1818
+ moved[decision.op.slug] = decision.op.event
1819
+ elif isinstance(decision, Prune) and isinstance(decision.op, DeleteResource):
1820
+ moved[decision.op.slug] = None
1821
+ linked: dict[str, list[str]] = {}
1822
+ for slug, entry in sorted(remote.resources.items()):
1823
+ lesson = moved[slug] if slug in moved else resource_event_of(entry.payload)
1824
+ if lesson is not None:
1825
+ linked.setdefault(event_key(lesson.week, lesson.time_slot), []).append(slug)
1826
+ return linked
1827
+
1828
+
1829
+ def _settled(decisions: Iterable[Decision], globs: Sequence[str]) -> list[Decision]:
1830
+ """
1831
+ `decisions` with each conflict or other-CLI entry a glob matches replaced
1832
+ by the operations that settle it for the repository.
1833
+ """
1834
+ settled: list[Decision] = []
1835
+ for decision in decisions:
1836
+ if (
1837
+ isinstance(decision, Conflict | OtherCli)
1838
+ and decision.ours
1839
+ and any(
1840
+ fnmatchcase(f"{decision.kind}/{decision.key}", glob) for glob in globs
1841
+ )
1842
+ ):
1843
+ settled.extend(decision.ours)
1844
+ else:
1845
+ settled.append(decision)
1846
+ return settled
1847
+
1848
+
1849
+ def _without_prunes(ours: tuple[Put | Prune, ...]) -> tuple[Put | Prune, ...]:
1850
+ return tuple(d for d in ours if not isinstance(d, Prune))
1851
+
1852
+
1853
+ #: Where each write sits in a plan: the course, the repositories, the
1854
+ #: calendar (removals of events, removals of time slots, time slots, events),
1855
+ #: then resources, questions, exams (removals, then writes) and grade columns. A write only depends on
1856
+ #: those before it.
1857
+ _WRITE_ORDER: tuple[tuple[type, ...], ...] = (
1858
+ (UpsertCourse,),
1859
+ (UpsertRepository, DeleteRepository),
1860
+ (DeleteRollCall, DeleteCalendarEvent),
1861
+ (DeleteTimeSlot,),
1862
+ (UpsertTimeSlot,),
1863
+ (UpsertCalendarEvent,),
1864
+ (UpsertResource, DeleteResource),
1865
+ (UpsertQuestion, DeleteQuestion),
1866
+ (DeleteExam,),
1867
+ (UpsertExam,),
1868
+ (UpsertGradeColumn, DeleteGradeColumn),
1869
+ )
1870
+
1871
+
1872
+ def write_rank(write: Write) -> int:
1873
+ """
1874
+ The position of a write in the order a plan runs its writes.
1875
+ """
1876
+ for rank, types in enumerate(_WRITE_ORDER):
1877
+ if isinstance(write, types):
1878
+ return rank
1879
+ raise TypeError(f"unranked write: {write!r}")
1880
+
1881
+
1882
+ def order_writes(writes: Iterable[Write]) -> tuple[Write, ...]:
1883
+ """
1884
+ Sort writes into the order a plan runs them, keeping the given order
1885
+ among writes of the same rank.
1886
+ """
1887
+ return tuple(sorted(writes, key=write_rank))
1888
+
1889
+
1890
+ def order_decisions(decisions: Iterable[Put | Prune]) -> list[Put | Prune]:
1891
+ """
1892
+ Sort `Put` and `Prune` decisions into the order of their writes.
1893
+ """
1894
+ return sorted(decisions, key=lambda d: write_rank(d.op))
1895
+
1896
+
1897
+ def _only[D: Decision](decisions: Iterable[Decision], kind: type[D]) -> list[D]:
1898
+ return [d for d in decisions if isinstance(d, kind)]
1899
+
1900
+
1901
+ def _pin_slots(
1902
+ events: Iterable[Decision], local_slugs: set[str]
1903
+ ) -> tuple[frozenset[str], tuple[KeptPinnedSlot, ...]]:
1904
+ """
1905
+ Fold the kept events into the slots they pin and one notice per slot
1906
+ whose pin the calendar does not account for.
1907
+ """
1908
+ pinned: set[str] = set()
1909
+ weeks: dict[str, list[int]] = {}
1910
+ for decision in events:
1911
+ if not isinstance(decision, Keep):
1912
+ continue
1913
+ match decision.notice:
1914
+ case KeptForRollCall(time_slot=slot):
1915
+ pinned.add(slot)
1916
+ case KeptCancelled(week=week, time_slot=slot):
1917
+ pinned.add(slot)
1918
+ if slot not in local_slugs:
1919
+ weeks.setdefault(slot, []).append(week)
1920
+ notices = tuple(
1921
+ KeptPinnedSlot(slug=slug, weeks=tuple(sorted(found)))
1922
+ for slug, found in sorted(weeks.items())
1923
+ )
1924
+ return frozenset(pinned), notices
1925
+
1926
+
1927
+ def _upsert_resource(file: ResourceFile) -> UpsertResource:
1928
+ return UpsertResource(
1929
+ slug=file.slug,
1930
+ title=file.title,
1931
+ description=file.description,
1932
+ data=file.data,
1933
+ ref=file.ref,
1934
+ path=file.path,
1935
+ event=file.event,
1936
+ )
1937
+
1938
+
1939
+ def _upsert_question(question: QuestionFile, status: QuestionStatus) -> UpsertQuestion:
1940
+ return UpsertQuestion(
1941
+ slug=question.slug,
1942
+ version=question.version,
1943
+ question=question.question,
1944
+ path=question.path,
1945
+ status=status,
1946
+ files=question.files,
1947
+ blobs=question.blobs,
1948
+ )
1949
+
1950
+
1951
+ def _upsert_exam(
1952
+ exam: ExamFile, status: ExamStatus, payload: Payload | None = None
1953
+ ) -> UpsertExam:
1954
+ payload = exam_payload(exam) if payload is None else payload
1955
+ return UpsertExam(
1956
+ slug=exam.slug,
1957
+ payload=payload,
1958
+ status=status,
1959
+ rev=exam_rev(payload),
1960
+ path=exam.path,
1961
+ blobs=exam.blobs,
1962
+ )
1963
+
1964
+
1965
+ def course_ref(description: str, start_date: str, end_date: str) -> str:
1966
+ """
1967
+ Digest the fields a push writes on the course row into the `rev` it
1968
+ stores, the way `resource.content_ref` digests a resource.
1969
+ """
1970
+ canonical = json.dumps(
1971
+ {
1972
+ "v": "v1",
1973
+ "description": description,
1974
+ "startDate": start_date,
1975
+ "endDate": end_date,
1976
+ },
1977
+ separators=(",", ":"),
1978
+ sort_keys=True,
1979
+ ensure_ascii=False,
1980
+ )
1981
+ return f"v1:{hashlib.sha256(canonical.encode('utf-8')).hexdigest()}"