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