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
|
@@ -0,0 +1,576 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The pure core that turns files under `resources/` into `ResourceFile`s.
|
|
3
|
+
|
|
4
|
+
Nothing here touches the network or the server's idea of what it holds --
|
|
5
|
+
see `plan.py` for that half. A `ResourceFile` carries everything a
|
|
6
|
+
`push.plan.UpsertResource` needs, including the `ref` the server stores
|
|
7
|
+
verbatim and hands back on the next read, so the core can diff two of
|
|
8
|
+
these by comparing strings.
|
|
9
|
+
|
|
10
|
+
The `ResourceData` union mirrors the server's own tagged union on
|
|
11
|
+
`Resource.data` without importing it: the core stays independent of
|
|
12
|
+
`api/generated.py`, and `push/run.py` translates one into the other.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import hashlib
|
|
18
|
+
import json
|
|
19
|
+
import re
|
|
20
|
+
import unicodedata
|
|
21
|
+
from collections import defaultdict
|
|
22
|
+
from collections.abc import Iterator, Sequence
|
|
23
|
+
from dataclasses import dataclass
|
|
24
|
+
from itertools import takewhile
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Literal
|
|
27
|
+
|
|
28
|
+
import yaml
|
|
29
|
+
|
|
30
|
+
from ..repo.diff import FileType
|
|
31
|
+
from ..repo.file_tracker import scan_files
|
|
32
|
+
from .calendar import EventKey
|
|
33
|
+
from .errors import ResourceFileError, SlugCollisionError
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"INFO_FILE",
|
|
37
|
+
"README_SLUG",
|
|
38
|
+
"CodeData",
|
|
39
|
+
"FileData",
|
|
40
|
+
"LinkData",
|
|
41
|
+
"MdData",
|
|
42
|
+
"ResourceData",
|
|
43
|
+
"ResourceFile",
|
|
44
|
+
"content_ref",
|
|
45
|
+
"read_course_readme",
|
|
46
|
+
"resource_slug",
|
|
47
|
+
"scan_resources",
|
|
48
|
+
"slugify",
|
|
49
|
+
"slugify_text",
|
|
50
|
+
"title_from_filename",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
#: `.md`/`.markdown` files become `MD` resources -- see `push.md`, "Type is
|
|
54
|
+
#: inferred from the extension".
|
|
55
|
+
MD_SUFFIXES = (".md", ".markdown")
|
|
56
|
+
|
|
57
|
+
#: `.url` files become `LINK` resources, read as a text/uri-list.
|
|
58
|
+
LINK_SUFFIX = ".url"
|
|
59
|
+
|
|
60
|
+
#: The per-directory metadata file: never a resource itself.
|
|
61
|
+
INFO_FILE = "info.yaml"
|
|
62
|
+
|
|
63
|
+
#: The slug the course README pushes under, as an `MD` resource.
|
|
64
|
+
README_SLUG = "readme"
|
|
65
|
+
|
|
66
|
+
#: Keys an `info.yaml` entry may set.
|
|
67
|
+
INFO_KEYS = frozenset({"title", "description", "language", "mime"})
|
|
68
|
+
|
|
69
|
+
#: Extension -> the language a `CODE` resource reports. An `info.yaml`
|
|
70
|
+
#: `language` overrides it, so this is a reasonable-effort table, not a
|
|
71
|
+
#: spec-pinned one.
|
|
72
|
+
CODE_LANGUAGES: dict[str, str] = {
|
|
73
|
+
".py": "python",
|
|
74
|
+
".js": "javascript",
|
|
75
|
+
".mjs": "javascript",
|
|
76
|
+
".cjs": "javascript",
|
|
77
|
+
".jsx": "javascript",
|
|
78
|
+
".ts": "typescript",
|
|
79
|
+
".tsx": "typescript",
|
|
80
|
+
".java": "java",
|
|
81
|
+
".c": "c",
|
|
82
|
+
".h": "c",
|
|
83
|
+
".cpp": "cpp",
|
|
84
|
+
".cc": "cpp",
|
|
85
|
+
".hpp": "cpp",
|
|
86
|
+
".cs": "csharp",
|
|
87
|
+
".go": "go",
|
|
88
|
+
".rs": "rust",
|
|
89
|
+
".rb": "ruby",
|
|
90
|
+
".php": "php",
|
|
91
|
+
".sh": "bash",
|
|
92
|
+
".bash": "bash",
|
|
93
|
+
".sql": "sql",
|
|
94
|
+
".html": "html",
|
|
95
|
+
".css": "css",
|
|
96
|
+
".json": "json",
|
|
97
|
+
".yaml": "yaml",
|
|
98
|
+
".yml": "yaml",
|
|
99
|
+
".toml": "toml",
|
|
100
|
+
".kt": "kotlin",
|
|
101
|
+
".swift": "swift",
|
|
102
|
+
".scala": "scala",
|
|
103
|
+
".r": "r",
|
|
104
|
+
".pl": "perl",
|
|
105
|
+
".lua": "lua",
|
|
106
|
+
".hs": "haskell",
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
#: Any run of characters outside this set collapses to a single `-` in a
|
|
110
|
+
#: slug -- see `push.md`, "A resource's slug is its flattened path".
|
|
111
|
+
SLUG_INVALID_RUN = re.compile(r"[^a-z0-9._-]+")
|
|
112
|
+
|
|
113
|
+
#: The combining marks NFKD splits off accented Latin letters; the server's
|
|
114
|
+
#: `src/utils/slugify.ts` strips the same range.
|
|
115
|
+
COMBINING_MARKS = re.compile("[\u0300-\u036f]")
|
|
116
|
+
|
|
117
|
+
#: Where a file name splits into words for its fallback title: hyphens,
|
|
118
|
+
#: underscores, whitespace, and camel case humps.
|
|
119
|
+
TITLE_WORD_BREAK = re.compile(
|
|
120
|
+
r"[-_\s]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])"
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
H1_RE = re.compile(r"^#\s+(.+?)\s*$")
|
|
124
|
+
|
|
125
|
+
#: Leads every `ref` this CLI writes. `ref` is a free-form string the
|
|
126
|
+
#: server stores and returns untouched, so its meaning is entirely ours;
|
|
127
|
+
#: the prefix says which recipe produced the digest, so changing the recipe
|
|
128
|
+
#: later invalidates old refs loudly instead of colliding with them.
|
|
129
|
+
REF_PREFIX = "v1"
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
@dataclass(frozen=True)
|
|
133
|
+
class MdData:
|
|
134
|
+
"""
|
|
135
|
+
A Markdown resource's body, front matter already stripped.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
content: str
|
|
139
|
+
type: Literal["MD"] = "MD"
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
@dataclass(frozen=True)
|
|
143
|
+
class CodeData:
|
|
144
|
+
"""
|
|
145
|
+
A source file's text, plus the language the server highlights it as.
|
|
146
|
+
"""
|
|
147
|
+
|
|
148
|
+
content: str
|
|
149
|
+
language: str
|
|
150
|
+
type: Literal["CODE"] = "CODE"
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@dataclass(frozen=True)
|
|
154
|
+
class FileData:
|
|
155
|
+
"""
|
|
156
|
+
An opaque file's bytes, uploaded whole under `filename`.
|
|
157
|
+
"""
|
|
158
|
+
|
|
159
|
+
filename: str
|
|
160
|
+
blob: bytes
|
|
161
|
+
type: Literal["FILE"] = "FILE"
|
|
162
|
+
|
|
163
|
+
@property
|
|
164
|
+
def sha256(self) -> str:
|
|
165
|
+
"""
|
|
166
|
+
The hex sha-256 of `blob`, the name the server stores it under.
|
|
167
|
+
"""
|
|
168
|
+
return hashlib.sha256(self.blob).hexdigest()
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@dataclass(frozen=True)
|
|
172
|
+
class LinkData:
|
|
173
|
+
"""
|
|
174
|
+
An external `http(s)` URL, read from a `.url` file.
|
|
175
|
+
"""
|
|
176
|
+
|
|
177
|
+
url: str
|
|
178
|
+
type: Literal["LINK"] = "LINK"
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
#: What a resource holds, tagged the way the server tags it.
|
|
182
|
+
type ResourceData = MdData | CodeData | FileData | LinkData
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
@dataclass(frozen=True)
|
|
186
|
+
class ResourceFile:
|
|
187
|
+
"""
|
|
188
|
+
One file under `resources/`, already typed, titled, and hashed.
|
|
189
|
+
"""
|
|
190
|
+
|
|
191
|
+
slug: str
|
|
192
|
+
title: str
|
|
193
|
+
description: str | None
|
|
194
|
+
data: ResourceData
|
|
195
|
+
ref: str
|
|
196
|
+
path: Path
|
|
197
|
+
event: EventKey | None = None
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def resource_slug(rel_path: Path) -> str:
|
|
201
|
+
"""
|
|
202
|
+
The slug a file under `resources/` pushes under: `slugify`, keeping the
|
|
203
|
+
extension of anything but Markdown.
|
|
204
|
+
|
|
205
|
+
`aabb.py` and `aabb.png` in one folder are two resources, `aabb.py` and
|
|
206
|
+
`aabb.png`, while `notas.md` stays `notas`, so a lesson's page reads
|
|
207
|
+
like a page. `week1/Slides (final).PDF` becomes `week1-slides-final.pdf`.
|
|
208
|
+
"""
|
|
209
|
+
if rel_path.suffix.lower() in MD_SUFFIXES or not rel_path.suffix:
|
|
210
|
+
return slugify(rel_path)
|
|
211
|
+
return slugify(rel_path) + slugify_text(rel_path.suffix)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def slugify(rel_path: Path) -> str:
|
|
215
|
+
"""
|
|
216
|
+
Flatten a path into a slug without its extension.
|
|
217
|
+
|
|
218
|
+
Joins the parts with `-`, then applies `slugify_text`.
|
|
219
|
+
`week1/Slides (final).pdf` becomes `week1-slides-final` and
|
|
220
|
+
`laços/herança.md` becomes `lacos-heranca`.
|
|
221
|
+
"""
|
|
222
|
+
return slugify_text("-".join(rel_path.with_suffix("").parts))
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def slugify_text(text: str) -> str:
|
|
226
|
+
"""
|
|
227
|
+
Turn free text into a slug: accents dropped, lowercase, runs outside
|
|
228
|
+
`[a-z0-9._-]` collapsed to `-`, no leading or trailing `-`.
|
|
229
|
+
|
|
230
|
+
Accents go the way the server's `src/utils/slugify.ts` drops them: NFKD,
|
|
231
|
+
then the combining marks removed. Letters NFKD does not decompose (`ß`,
|
|
232
|
+
`æ`, `ø`) are not transliterated and become `-`, as on the server.
|
|
233
|
+
"""
|
|
234
|
+
plain = COMBINING_MARKS.sub("", unicodedata.normalize("NFKD", text))
|
|
235
|
+
return SLUG_INVALID_RUN.sub("-", plain.lower()).strip("-")
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def title_from_filename(stem: str) -> str:
|
|
239
|
+
"""
|
|
240
|
+
The fallback title of a file: its name split on hyphens, underscores
|
|
241
|
+
and camel case, each word capitalised.
|
|
242
|
+
|
|
243
|
+
`janela-minima` becomes `Janela Minima` and `bigONotation` becomes
|
|
244
|
+
`Big O Notation`. Letters after the first keep their case, so `PDF`
|
|
245
|
+
stays `PDF`.
|
|
246
|
+
"""
|
|
247
|
+
words = [word for word in TITLE_WORD_BREAK.split(stem) if word]
|
|
248
|
+
return " ".join(word[:1].upper() + word[1:] for word in words) or stem
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def content_ref(
|
|
252
|
+
title: str,
|
|
253
|
+
description: str | None,
|
|
254
|
+
data: ResourceData,
|
|
255
|
+
event: EventKey | None = None,
|
|
256
|
+
) -> str:
|
|
257
|
+
"""
|
|
258
|
+
Digest a resource's pushable fields into the `ref` the server stores.
|
|
259
|
+
|
|
260
|
+
Sha-256, hex, over a canonical JSON rendering of `{v, title,
|
|
261
|
+
description, data}` with no whitespace, prefixed by `REF_PREFIX`. Two
|
|
262
|
+
resources with the same ref are the same resource, which is the whole
|
|
263
|
+
basis on which `plan_sync` decides not to push one again -- so the
|
|
264
|
+
rendering has to be stable across runs, machines, and Python versions.
|
|
265
|
+
|
|
266
|
+
A `FILE`'s bytes are digested separately and only their hex digest
|
|
267
|
+
enters the rendering, keeping the payload small and JSON-safe.
|
|
268
|
+
|
|
269
|
+
The event key the resource is attached to is part of the digest, so
|
|
270
|
+
moving a resource to another lesson changes its ref. With `event=None`
|
|
271
|
+
the digest MUST stay byte-identical to the one computed before events
|
|
272
|
+
existed (existing refs and test vectors stay valid): add the key to the
|
|
273
|
+
rendering only when it is not `None`.
|
|
274
|
+
"""
|
|
275
|
+
payload: dict[str, object] = {
|
|
276
|
+
"v": REF_PREFIX,
|
|
277
|
+
"title": title,
|
|
278
|
+
"description": description,
|
|
279
|
+
"data": _data_payload(data),
|
|
280
|
+
}
|
|
281
|
+
if event is not None:
|
|
282
|
+
payload["event"] = {"week": event.week, "timeSlot": event.time_slot}
|
|
283
|
+
canonical = json.dumps(
|
|
284
|
+
payload,
|
|
285
|
+
separators=(",", ":"),
|
|
286
|
+
sort_keys=True,
|
|
287
|
+
ensure_ascii=False,
|
|
288
|
+
)
|
|
289
|
+
digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
|
290
|
+
return f"{REF_PREFIX}:{digest}"
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def scan_resources(
|
|
294
|
+
root: Path,
|
|
295
|
+
exclude: Sequence[str] = (),
|
|
296
|
+
extras: Sequence[ResourceFile] = (),
|
|
297
|
+
) -> Iterator[ResourceFile]:
|
|
298
|
+
"""
|
|
299
|
+
Walk `resources/` and yield one `ResourceFile` per file.
|
|
300
|
+
|
|
301
|
+
`extras` are resources that do not live under `resources/` (the course
|
|
302
|
+
README). They are yielded first and take part in the slug collision check.
|
|
303
|
+
|
|
304
|
+
Reuses the (fixed) `repo.file_tracker.scan_files` for the walk, so a
|
|
305
|
+
subdirectory never becomes a resource of its own. Files matching an
|
|
306
|
+
`exclude` pattern are skipped without being read. An `info.yaml` is
|
|
307
|
+
read as the metadata of its directory's files, not pushed.
|
|
308
|
+
|
|
309
|
+
Raises:
|
|
310
|
+
SlugCollisionError: two or more files flatten to the same slug.
|
|
311
|
+
Raised eagerly, before any file is read or any network call is
|
|
312
|
+
made.
|
|
313
|
+
ResourceFileError: an `info.yaml` or a `.url` file is malformed.
|
|
314
|
+
"""
|
|
315
|
+
base = root / "resources"
|
|
316
|
+
by_slug: dict[str, list[Path]] = defaultdict(list)
|
|
317
|
+
entries: list[tuple[str, Path]] = []
|
|
318
|
+
info_dirs: set[Path] = set()
|
|
319
|
+
|
|
320
|
+
for extra in extras:
|
|
321
|
+
by_slug[extra.slug].append(extra.path)
|
|
322
|
+
|
|
323
|
+
for file in scan_files(root, exclude):
|
|
324
|
+
if file.type is not FileType.RESOURCE or file.excluded:
|
|
325
|
+
continue
|
|
326
|
+
rel_path = Path(file.name)
|
|
327
|
+
if rel_path.name == INFO_FILE:
|
|
328
|
+
info_dirs.add(rel_path.parent)
|
|
329
|
+
continue
|
|
330
|
+
slug = resource_slug(rel_path)
|
|
331
|
+
by_slug[slug].append(rel_path)
|
|
332
|
+
entries.append((slug, rel_path))
|
|
333
|
+
|
|
334
|
+
collisions = {slug: paths for slug, paths in by_slug.items() if len(paths) > 1}
|
|
335
|
+
if collisions:
|
|
336
|
+
raise SlugCollisionError(collisions)
|
|
337
|
+
|
|
338
|
+
infos = {folder: read_info(base / folder / INFO_FILE) for folder in info_dirs}
|
|
339
|
+
yield from extras
|
|
340
|
+
for slug, rel_path in entries:
|
|
341
|
+
info = infos.get(rel_path.parent, {}).get(rel_path.name, ResourceInfo())
|
|
342
|
+
yield read_resource(base, slug, rel_path, info)
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def read_course_readme(
|
|
346
|
+
text: str, override: str | None, path: Path
|
|
347
|
+
) -> tuple[str, ResourceFile | None]:
|
|
348
|
+
"""
|
|
349
|
+
Split the course README into the course description and the `MD`
|
|
350
|
+
resource `README_SLUG` that carries the rest of it.
|
|
351
|
+
|
|
352
|
+
The description is `override`, else the README's first paragraph (after
|
|
353
|
+
its H1, if any). The resource is titled by the H1, holds the README
|
|
354
|
+
without it, and is `None` when it would add nothing: with no `override`,
|
|
355
|
+
a README holding only the description; with one, an empty README.
|
|
356
|
+
`path` only labels the resource; nothing is read from it.
|
|
357
|
+
"""
|
|
358
|
+
lines = text.splitlines()
|
|
359
|
+
title = "README"
|
|
360
|
+
for index, line in enumerate(lines):
|
|
361
|
+
if not line.strip():
|
|
362
|
+
continue
|
|
363
|
+
if line.startswith("# "):
|
|
364
|
+
title = line[2:].strip()
|
|
365
|
+
lines = lines[index + 1 :]
|
|
366
|
+
break
|
|
367
|
+
content = "\n".join(lines).strip()
|
|
368
|
+
first_paragraph = "\n".join(
|
|
369
|
+
takewhile(
|
|
370
|
+
lambda line: line.strip() and not line.startswith("#"),
|
|
371
|
+
content.splitlines(),
|
|
372
|
+
)
|
|
373
|
+
)
|
|
374
|
+
description = override or first_paragraph
|
|
375
|
+
if not content or (not override and content == first_paragraph):
|
|
376
|
+
return description, None
|
|
377
|
+
data = MdData(content=content + "\n")
|
|
378
|
+
resource = ResourceFile(
|
|
379
|
+
slug=README_SLUG,
|
|
380
|
+
title=title,
|
|
381
|
+
description=None,
|
|
382
|
+
data=data,
|
|
383
|
+
ref=content_ref(title, None, data),
|
|
384
|
+
path=path,
|
|
385
|
+
)
|
|
386
|
+
return description, resource
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
#
|
|
390
|
+
# Utilities
|
|
391
|
+
#
|
|
392
|
+
@dataclass(frozen=True)
|
|
393
|
+
class ResourceInfo:
|
|
394
|
+
"""
|
|
395
|
+
One file's entry in its directory's `info.yaml`; `None` means unset.
|
|
396
|
+
"""
|
|
397
|
+
|
|
398
|
+
title: str | None = None
|
|
399
|
+
description: str | None = None
|
|
400
|
+
#: Forces `CODE`, highlighted as this language.
|
|
401
|
+
language: str | None = None
|
|
402
|
+
#: Forces `FILE`. The server derives the served type from the filename,
|
|
403
|
+
#: so the value itself is not sent.
|
|
404
|
+
mime: str | None = None
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
def read_info(path: Path) -> dict[str, ResourceInfo]:
|
|
408
|
+
"""
|
|
409
|
+
Parse an `info.yaml` into each named file's `ResourceInfo`.
|
|
410
|
+
|
|
411
|
+
Raises:
|
|
412
|
+
ResourceFileError: the file is not a YAML mapping of file names to
|
|
413
|
+
mappings, an entry uses a key outside `INFO_KEYS` or a value
|
|
414
|
+
that is not a string, or it names a file that does not exist.
|
|
415
|
+
"""
|
|
416
|
+
try:
|
|
417
|
+
raw = yaml.safe_load(path.read_text(encoding="utf-8"))
|
|
418
|
+
except yaml.YAMLError as exc:
|
|
419
|
+
raise ResourceFileError(path, f"not valid YAML: {exc}") from exc
|
|
420
|
+
if raw is None:
|
|
421
|
+
return {}
|
|
422
|
+
if not isinstance(raw, dict):
|
|
423
|
+
raise ResourceFileError(path, "expected a mapping of file names")
|
|
424
|
+
infos: dict[str, ResourceInfo] = {}
|
|
425
|
+
for name, entry in raw.items():
|
|
426
|
+
if not isinstance(entry, dict):
|
|
427
|
+
raise ResourceFileError(path, f"{name!r}: expected a mapping")
|
|
428
|
+
unknown = set(entry) - INFO_KEYS
|
|
429
|
+
if unknown:
|
|
430
|
+
keys = ", ".join(sorted(map(str, unknown)))
|
|
431
|
+
raise ResourceFileError(path, f"{name!r}: unknown keys {keys}")
|
|
432
|
+
if not all(isinstance(value, str) for value in entry.values()):
|
|
433
|
+
raise ResourceFileError(path, f"{name!r}: values must be strings")
|
|
434
|
+
if not (path.parent / str(name)).is_file():
|
|
435
|
+
raise ResourceFileError(path, f"{name!r}: no such file in this folder")
|
|
436
|
+
infos[str(name)] = ResourceInfo(**entry)
|
|
437
|
+
return infos
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
def read_resource(
|
|
441
|
+
base: Path, slug: str, rel_path: Path, info: ResourceInfo
|
|
442
|
+
) -> ResourceFile:
|
|
443
|
+
"""
|
|
444
|
+
Read one resource file off disk and infer its type, title, and ref.
|
|
445
|
+
|
|
446
|
+
The type comes from the extension unless `info` forces one; `info`'s
|
|
447
|
+
title and description win over anything the file declares, and the
|
|
448
|
+
file name is the last resort for the title.
|
|
449
|
+
|
|
450
|
+
Raises:
|
|
451
|
+
ResourceFileError: a `.url` file holds no `http(s)` URI.
|
|
452
|
+
"""
|
|
453
|
+
path = base / rel_path
|
|
454
|
+
suffix = path.suffix.lower()
|
|
455
|
+
title: str | None = None
|
|
456
|
+
description: str | None = None
|
|
457
|
+
data: ResourceData
|
|
458
|
+
|
|
459
|
+
if info.mime is not None:
|
|
460
|
+
data = FileData(filename=path.name, blob=path.read_bytes())
|
|
461
|
+
elif info.language is not None:
|
|
462
|
+
data = CodeData(
|
|
463
|
+
content=path.read_text(encoding="utf-8"), language=info.language
|
|
464
|
+
)
|
|
465
|
+
elif suffix in MD_SUFFIXES:
|
|
466
|
+
front_matter, body = split_front_matter(path.read_text(encoding="utf-8"))
|
|
467
|
+
title = front_matter_str(front_matter, "title") or first_h1(body)
|
|
468
|
+
description = front_matter_str(front_matter, "description")
|
|
469
|
+
data = MdData(content=body)
|
|
470
|
+
elif suffix == LINK_SUFFIX:
|
|
471
|
+
url, title, description = read_uri_list(path)
|
|
472
|
+
data = LinkData(url=url)
|
|
473
|
+
elif suffix in CODE_LANGUAGES:
|
|
474
|
+
content = path.read_text(encoding="utf-8")
|
|
475
|
+
data = CodeData(content=content, language=CODE_LANGUAGES[suffix])
|
|
476
|
+
else:
|
|
477
|
+
data = FileData(filename=path.name, blob=path.read_bytes())
|
|
478
|
+
|
|
479
|
+
title = info.title or title or title_from_filename(path.stem)
|
|
480
|
+
description = info.description if info.description is not None else description
|
|
481
|
+
return ResourceFile(
|
|
482
|
+
slug=slug,
|
|
483
|
+
title=title,
|
|
484
|
+
description=description,
|
|
485
|
+
data=data,
|
|
486
|
+
ref=content_ref(title, description, data),
|
|
487
|
+
path=path,
|
|
488
|
+
)
|
|
489
|
+
|
|
490
|
+
|
|
491
|
+
def read_uri_list(path: Path) -> tuple[str, str | None, str | None]:
|
|
492
|
+
"""
|
|
493
|
+
Read a text/uri-list into its first URI, title and description.
|
|
494
|
+
|
|
495
|
+
The first comment line is the title and the remaining ones, joined by
|
|
496
|
+
newlines, the description; each loses its `#` and surrounding
|
|
497
|
+
whitespace, and blank ones are dropped.
|
|
498
|
+
|
|
499
|
+
Raises:
|
|
500
|
+
ResourceFileError: the file has no URI, or the first one is not
|
|
501
|
+
`http(s)`, the only kind the server accepts for a `LINK`.
|
|
502
|
+
"""
|
|
503
|
+
comments: list[str] = []
|
|
504
|
+
uris: list[str] = []
|
|
505
|
+
for line in path.read_text(encoding="utf-8").splitlines():
|
|
506
|
+
stripped = line.strip()
|
|
507
|
+
if stripped.startswith("#"):
|
|
508
|
+
comment = stripped[1:].strip()
|
|
509
|
+
if comment:
|
|
510
|
+
comments.append(comment)
|
|
511
|
+
elif stripped:
|
|
512
|
+
uris.append(stripped)
|
|
513
|
+
if not uris:
|
|
514
|
+
raise ResourceFileError(path, "no URI in this text/uri-list")
|
|
515
|
+
if not re.match(r"https?://", uris[0], re.IGNORECASE):
|
|
516
|
+
raise ResourceFileError(path, f"{uris[0]!r} is not an http(s) URL")
|
|
517
|
+
title = comments[0] if comments else None
|
|
518
|
+
description = "\n".join(comments[1:]) or None
|
|
519
|
+
return uris[0], title, description
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
def _data_payload(data: ResourceData) -> dict[str, str]:
|
|
523
|
+
"""
|
|
524
|
+
One resource's data as the flat, JSON-safe mapping `content_ref`
|
|
525
|
+
digests.
|
|
526
|
+
"""
|
|
527
|
+
match data:
|
|
528
|
+
case MdData(content=content):
|
|
529
|
+
return {"type": data.type, "content": content}
|
|
530
|
+
case CodeData(content=content, language=language):
|
|
531
|
+
return {"type": data.type, "content": content, "language": language}
|
|
532
|
+
case FileData(filename=filename):
|
|
533
|
+
return {"type": data.type, "filename": filename, "blob": data.sha256}
|
|
534
|
+
case LinkData(url=url):
|
|
535
|
+
return {"type": data.type, "url": url}
|
|
536
|
+
|
|
537
|
+
|
|
538
|
+
def split_front_matter(text: str) -> tuple[dict[str, object], str]:
|
|
539
|
+
"""
|
|
540
|
+
Split a Markdown file's leading `---`-delimited YAML front matter from
|
|
541
|
+
its body.
|
|
542
|
+
|
|
543
|
+
Returns `({}, text)` unchanged when there is no front matter, or the
|
|
544
|
+
front matter fails to parse as a YAML mapping.
|
|
545
|
+
"""
|
|
546
|
+
if not text.startswith("---"):
|
|
547
|
+
return {}, text
|
|
548
|
+
lines = text.splitlines(keepends=True)
|
|
549
|
+
if not lines or lines[0].strip() != "---":
|
|
550
|
+
return {}, text
|
|
551
|
+
for index in range(1, len(lines)):
|
|
552
|
+
if lines[index].strip() != "---":
|
|
553
|
+
continue
|
|
554
|
+
front_matter_text = "".join(lines[1:index])
|
|
555
|
+
body = "".join(lines[index + 1 :]).lstrip("\n")
|
|
556
|
+
try:
|
|
557
|
+
data = yaml.safe_load(front_matter_text)
|
|
558
|
+
except yaml.YAMLError:
|
|
559
|
+
return {}, text
|
|
560
|
+
if not isinstance(data, dict):
|
|
561
|
+
return {}, text
|
|
562
|
+
return data, body
|
|
563
|
+
return {}, text
|
|
564
|
+
|
|
565
|
+
|
|
566
|
+
def front_matter_str(front_matter: dict[str, object], key: str) -> str | None:
|
|
567
|
+
value = front_matter.get(key)
|
|
568
|
+
return None if value is None else str(value)
|
|
569
|
+
|
|
570
|
+
|
|
571
|
+
def first_h1(body: str) -> str | None:
|
|
572
|
+
for line in body.splitlines():
|
|
573
|
+
match = H1_RE.match(line)
|
|
574
|
+
if match:
|
|
575
|
+
return match.group(1)
|
|
576
|
+
return None
|