codehood-cli 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. codehood/__init__.py +0 -0
  2. codehood/__main__.py +4 -0
  3. codehood/actions/__init__.py +0 -0
  4. codehood/actions/base.py +119 -0
  5. codehood/actions/resources.py +30 -0
  6. codehood/api/__init__.py +0 -0
  7. codehood/api/base.py +256 -0
  8. codehood/api/generate.py +1370 -0
  9. codehood/api/generated.py +3818 -0
  10. codehood/api/openapi.py +134 -0
  11. codehood/api/pages.py +53 -0
  12. codehood/cli/__init__.py +64 -0
  13. codehood/cli/api.py +422 -0
  14. codehood/cli/attendance.py +136 -0
  15. codehood/cli/auth.py +106 -0
  16. codehood/cli/base.py +42 -0
  17. codehood/cli/chill.py +52 -0
  18. codehood/cli/exam.py +107 -0
  19. codehood/cli/grades.py +185 -0
  20. codehood/cli/init.py +161 -0
  21. codehood/cli/push.py +609 -0
  22. codehood/cli/show.py +77 -0
  23. codehood/cli/uitils.py +26 -0
  24. codehood/functional.py +40 -0
  25. codehood/globs.py +71 -0
  26. codehood/grades.py +74 -0
  27. codehood/hypothesis.py +274 -0
  28. codehood/models/__init__.py +0 -0
  29. codehood/models/base.py +15 -0
  30. codehood/models/repo.py +187 -0
  31. codehood/models/validators.py +177 -0
  32. codehood/push/__init__.py +225 -0
  33. codehood/push/base.py +216 -0
  34. codehood/push/calendar.py +664 -0
  35. codehood/push/errors.py +136 -0
  36. codehood/push/exam.py +636 -0
  37. codehood/push/exclude.py +60 -0
  38. codehood/push/grades.py +455 -0
  39. codehood/push/hook.py +48 -0
  40. codehood/push/links.py +614 -0
  41. codehood/push/ours.py +78 -0
  42. codehood/push/plan.py +1981 -0
  43. codehood/push/project.py +272 -0
  44. codehood/push/question.py +338 -0
  45. codehood/push/report.py +244 -0
  46. codehood/push/repository.py +326 -0
  47. codehood/push/resource.py +576 -0
  48. codehood/push/run.py +1275 -0
  49. codehood/push/unconsumed.py +208 -0
  50. codehood/push/wire.py +222 -0
  51. codehood/py.typed +0 -0
  52. codehood/repo/__init__.py +62 -0
  53. codehood/repo/_config.py +28 -0
  54. codehood/repo/_layout.py +132 -0
  55. codehood/repo/_scaffold.py +244 -0
  56. codehood/repo/diff.py +71 -0
  57. codehood/repo/file_tracker.py +124 -0
  58. codehood/theme.py +101 -0
  59. codehood/widgets/__init__.py +0 -0
  60. codehood/widgets/mascot.py +76 -0
  61. codehood/widgets/questions/__init__.py +65 -0
  62. codehood/widgets/questions/base.py +119 -0
  63. codehood/widgets/questions/controls.py +194 -0
  64. codehood/widgets/questions/fill_in.py +81 -0
  65. codehood/widgets/questions/responses.py +137 -0
  66. codehood/widgets/questions/simple.py +117 -0
  67. codehood_cli-0.5.0.dist-info/METADATA +294 -0
  68. codehood_cli-0.5.0.dist-info/RECORD +71 -0
  69. codehood_cli-0.5.0.dist-info/WHEEL +4 -0
  70. codehood_cli-0.5.0.dist-info/entry_points.txt +4 -0
  71. codehood_cli-0.5.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,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