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,208 @@
1
+ """
2
+ The repository files a push did not read.
3
+
4
+ `find_unconsumed` is the pure core: it diffs the paths found on disk against
5
+ the paths the push stages consumed. `list_files` and `consumed_paths` feed it
6
+ from the filesystem.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ import re
13
+ import subprocess
14
+ from collections.abc import Collection, Iterable
15
+ from pathlib import Path
16
+
17
+ import pathspec
18
+
19
+ from ..repo.diff import FileType
20
+ from ..repo.file_tracker import File
21
+
22
+ __all__ = [
23
+ "IGNORE_FILE",
24
+ "consumed_paths",
25
+ "excluded_paths",
26
+ "find_unconsumed",
27
+ "ignore_patterns",
28
+ "list_files",
29
+ "read_ignore",
30
+ ]
31
+
32
+ #: Course-root file with gitignore-syntax lines that codehood ignores.
33
+ IGNORE_FILE = ".codehoodignore"
34
+
35
+ #: Trees whose files are pushed one by one: a match there is excluded, not
36
+ #: forgotten, so the server copy survives the prune.
37
+ PUSHED_TREES = ("questions", "resources", "exams")
38
+
39
+ #: Only files under these prefixes can be reported: anything else in the
40
+ #: course (root files, other folders) is not codehood's business.
41
+ PUSHED_PREFIXES = tuple(f"{tree}/" for tree in PUSHED_TREES)
42
+
43
+ #: Directories never versioned by the course: skipped without a gitignore.
44
+ SKIPPED_DIRS = frozenset({".git", ".codehood", ".local"})
45
+
46
+
47
+ def find_unconsumed(
48
+ paths: Iterable[str],
49
+ *,
50
+ consumed: Collection[str],
51
+ excluded: Collection[str],
52
+ gitignore: Iterable[str] = (),
53
+ codehoodignore: Iterable[str] = (),
54
+ ) -> tuple[str, ...]:
55
+ """
56
+ Sort the versionable paths under `questions/`, `resources/` and `exams/`
57
+ that no push stage read.
58
+
59
+ `paths` are `/`-separated and relative to the repository root. Files
60
+ elsewhere are never reported, and `excluded` paths have their own list.
61
+ `codehoodignore` lines (gitignore syntax) drop a path as if it did not exist.
62
+ """
63
+ ignored = pathspec.PathSpec.from_lines("gitignore", gitignore)
64
+ dropped = pathspec.PathSpec.from_lines("gitignore", codehoodignore)
65
+ return tuple(
66
+ sorted(
67
+ path
68
+ for path in set(paths)
69
+ if path.startswith(PUSHED_PREFIXES)
70
+ and path not in consumed
71
+ and path not in excluded
72
+ and not ignored.match_file(path)
73
+ and not dropped.match_file(path)
74
+ )
75
+ )
76
+
77
+
78
+ def consumed_paths(
79
+ files: Iterable[File],
80
+ *,
81
+ sources: Iterable[Path] = (),
82
+ root: Path | None = None,
83
+ ) -> frozenset[str]:
84
+ """
85
+ The paths under the pushed trees that the push stages read: the tracked
86
+ questions, resources and exams that are not excluded.
87
+
88
+ `sources` are the test files that `code` questions link. They count as
89
+ read when they lie under `root`.
90
+ """
91
+ tracked = {FileType.QUESTION, FileType.RESOURCE, FileType.EXAM}
92
+ linked = {
93
+ relative.as_posix()
94
+ for source in sources
95
+ if (relative := _relative_to(source, root)) is not None
96
+ }
97
+ return frozenset(
98
+ linked
99
+ | {
100
+ file.path.as_posix()
101
+ for file in files
102
+ if file.type in tracked and not file.excluded
103
+ }
104
+ )
105
+
106
+
107
+ def _relative_to(path: Path, root: Path | None) -> Path | None:
108
+ """
109
+ `path` made relative to `root` with `..` segments resolved, or `None`
110
+ when it lies outside it.
111
+ """
112
+ if root is None:
113
+ return None
114
+ resolved = Path(os.path.normpath(path))
115
+ try:
116
+ return resolved.relative_to(Path(os.path.normpath(root)))
117
+ except ValueError:
118
+ return None
119
+
120
+
121
+ def excluded_paths(files: Iterable[File]) -> frozenset[str]:
122
+ """
123
+ The tracked paths that a `[push] exclude` pattern matched.
124
+ """
125
+ return frozenset(file.path.as_posix() for file in files if file.excluded)
126
+
127
+
128
+ def list_files(root: Path) -> tuple[list[str], list[str]]:
129
+ """
130
+ List the repository files that git does not ignore.
131
+
132
+ In a git repository, git decides (`.gitignore` at any level,
133
+ `.git/info/exclude` and `core.excludesFile`), tracked and untracked files
134
+ alike, and the returned lines are empty. Otherwise it walks the tree,
135
+ skipping `.git/`, `.local/` and the legacy `.codehood/`, and returns the
136
+ lines of the root `.gitignore` for `find_unconsumed` to apply.
137
+
138
+ Returns the relative paths and the `.gitignore` lines.
139
+ """
140
+ if (found := _git_files(root)) is not None:
141
+ return found, []
142
+ paths: list[str] = []
143
+ for directory, subdirs, names in os.walk(root):
144
+ subdirs[:] = [name for name in subdirs if name not in SKIPPED_DIRS]
145
+ base = Path(directory).relative_to(root)
146
+ paths.extend((base / name).as_posix() for name in names)
147
+ return paths, _read_lines(root / ".gitignore")
148
+
149
+
150
+ def read_ignore(root: Path) -> list[str]:
151
+ """
152
+ The lines of the course's `.codehoodignore`, empty when there is none.
153
+ """
154
+ return _read_lines(root / IGNORE_FILE)
155
+
156
+
157
+ def ignore_patterns(root: Path, lines: Iterable[str]) -> list[str]:
158
+ """
159
+ `[push] exclude` patterns for the pushed files that `.codehoodignore` matches.
160
+
161
+ Each file under `questions/` and `resources/` that the lines match becomes
162
+ one literal pattern, so the existing exclude mechanism protects it.
163
+ """
164
+ spec = pathspec.PathSpec.from_lines("gitignore", lines)
165
+ patterns: list[str] = []
166
+ for tree in PUSHED_TREES:
167
+ for directory, _, names in os.walk(root / tree):
168
+ base = Path(directory).relative_to(root)
169
+ for name in names:
170
+ path = (base / name).as_posix()
171
+ if spec.match_file(path):
172
+ patterns.append(re.sub(r"([*?\\])", r"\\\1", path))
173
+ return patterns
174
+
175
+
176
+ #
177
+ # Utilities
178
+ #
179
+ def _read_lines(path: Path) -> list[str]:
180
+ return path.read_text(encoding="utf-8").splitlines() if path.is_file() else []
181
+
182
+
183
+ def _git_files(root: Path) -> list[str] | None:
184
+ """
185
+ Ask git for the files of a course that is a git repository, or `None` when
186
+ it is not one or git is unavailable.
187
+ """
188
+ if not (root / ".git").exists():
189
+ return None
190
+ try:
191
+ result = subprocess.run(
192
+ ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
193
+ cwd=root,
194
+ capture_output=True,
195
+ check=True,
196
+ )
197
+ except (OSError, subprocess.CalledProcessError):
198
+ return None
199
+ names = result.stdout.decode("utf-8", errors="surrogateescape").split("\0")
200
+ return sorted(
201
+ {
202
+ name
203
+ for name in names
204
+ if name
205
+ and name.split("/", 1)[0] not in SKIPPED_DIRS
206
+ and (root / name).is_file()
207
+ }
208
+ )
codehood/push/wire.py ADDED
@@ -0,0 +1,222 @@
1
+ """
2
+ Translates the local forms a push writes into the JSON the server accepts.
3
+
4
+ Every `*_payload` function returns the body of the entity's `PUT`, so the
5
+ payload of a local entity and the payload a read model projects to (see
6
+ `project.py`) are the same dict, and comparing them is comparing dicts.
7
+ Where the server rewrites a value on the way in (a time slot's duration is
8
+ carried into hours, a grade column's strings are trimmed), the payload holds
9
+ the rewritten value: a payload the server hands back unchanged is the only
10
+ kind that can be compared.
11
+
12
+ `rev` is left out of every payload. It is a digest of the payload, stored and
13
+ compared on its own.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from datetime import date
19
+ from typing import TYPE_CHECKING
20
+
21
+ import mdq
22
+ from pydantic import JsonValue
23
+
24
+ from ..models.repo import CourseKey
25
+ from .calendar import Event, TimeSlot
26
+ from .grades import GradeColumn
27
+ from .question import QuestionFile
28
+
29
+ if TYPE_CHECKING:
30
+ from .exam import ExamFile
31
+ from .resource import CodeData, FileData, LinkData, MdData, ResourceFile
32
+
33
+ __all__ = [
34
+ "Payload",
35
+ "canonical_question",
36
+ "course_payload",
37
+ "event_payload",
38
+ "exam_payload",
39
+ "grade_column_payload",
40
+ "question_payload",
41
+ "resource_payload",
42
+ "time_slot_payload",
43
+ "wire_question",
44
+ ]
45
+
46
+ #: The JSON body a push sends for one entity, without its `rev`.
47
+ type Payload = dict[str, JsonValue]
48
+
49
+ #: Lists the mdq schema requires to be absent or non-empty.
50
+ _NON_EMPTY_LISTS = ("extra", "accept", "reject")
51
+
52
+
53
+ def wire_question(question: mdq.Question) -> dict[str, JsonValue]:
54
+ """
55
+ Return `question` as the plain mapping the server's `question` union takes.
56
+
57
+ Omitted optional fields stay omitted: the server rejects an explicit
58
+ `null`, and an empty `extra`, `accept` or `reject` list, which `mdq`
59
+ models default to but the mdq schema requires to have items.
60
+ """
61
+ payload = question.model_dump(mode="json", by_alias=True, exclude_none=True)
62
+ for key in _NON_EMPTY_LISTS:
63
+ if payload.get(key) == []:
64
+ del payload[key]
65
+ return payload
66
+
67
+
68
+ def canonical_question(question: mdq.Question) -> dict[str, JsonValue]:
69
+ """
70
+ Return `question` in the form two equal questions share: ids filled in
71
+ and fields normalized by `mdq`, then as `wire_question` takes it.
72
+ """
73
+ return wire_question(question.with_ids().normalize())
74
+
75
+
76
+ def course_payload(key: CourseKey, description: str, start: date, end: date) -> Payload:
77
+ """
78
+ The body of the course's `PUT`.
79
+ """
80
+ return {
81
+ "discipline": key.discipline,
82
+ "instructor": key.instructor,
83
+ "edition": key.edition,
84
+ "description": description,
85
+ "startDate": start.isoformat(),
86
+ "endDate": end.isoformat(),
87
+ }
88
+
89
+
90
+ def resource_payload(file: ResourceFile) -> Payload:
91
+ """
92
+ The body of a resource's `PUT`.
93
+
94
+ A `FILE` carries the sha-256 of its bytes, not the bytes, which travel in
95
+ a multipart part named by that hash.
96
+ """
97
+ data: dict[str, JsonValue]
98
+ match file.data:
99
+ case MdData(content=content):
100
+ data = {"type": "MD", "content": content}
101
+ case CodeData(content=content, language=language):
102
+ data = {"type": "CODE", "content": content, "language": language}
103
+ case FileData(filename=filename) as upload:
104
+ data = {"type": "FILE", "filename": filename, "hash": upload.sha256}
105
+ case LinkData(url=url):
106
+ data = {"type": "LINK", "url": url}
107
+ return {
108
+ "slug": file.slug,
109
+ "title": file.title,
110
+ "description": file.description,
111
+ "event": (
112
+ {"week": file.event.week, "timeSlot": file.event.time_slot}
113
+ if file.event is not None
114
+ else None
115
+ ),
116
+ "data": data,
117
+ }
118
+
119
+
120
+ def question_payload(file: QuestionFile) -> Payload:
121
+ """
122
+ The canonical form of a question: its slug, its document and, when it
123
+ links attachments, their `files`.
124
+
125
+ `status` and `version` are left out: the status follows `join_status`,
126
+ and the version digests the file's bytes rather than its content.
127
+ """
128
+ payload: Payload = {
129
+ "slug": file.slug,
130
+ "question": canonical_question(file.question),
131
+ }
132
+ if file.files:
133
+ payload["files"] = dict(sorted(file.files.items()))
134
+ return payload
135
+
136
+
137
+ def exam_payload(file: ExamFile) -> Payload:
138
+ """
139
+ The body of an exam's `PUT`, without its `status` and `rev`.
140
+
141
+ The questions are sent as `{slug, version: null}`, which the server
142
+ reads as the latest version of each. `duration` and `scheduledAt` are
143
+ left out when the file declares none, since an instructor action may set
144
+ them on the server and a push must not blank them.
145
+ """
146
+ questions: list[JsonValue] = [
147
+ {"slug": slug, "version": None} for slug in file.questions
148
+ ]
149
+ tags: list[JsonValue] = [*sorted(file.tags)]
150
+ payload: Payload = {
151
+ "slug": file.slug,
152
+ "type": file.type,
153
+ "title": file.title,
154
+ "description": file.description,
155
+ "preamble": file.preamble,
156
+ "format": "MARKDOWN",
157
+ "tags": tags,
158
+ "allowCodeRun": file.allow_code_run,
159
+ "questions": questions,
160
+ "attachments": [
161
+ attachment.model_dump(mode="json", by_alias=True, exclude_none=True)
162
+ for attachment in file.attachments
163
+ ],
164
+ "files": dict(sorted(file.files.items())),
165
+ }
166
+ if file.duration is not None:
167
+ payload["duration"] = file.duration
168
+ if file.scheduled_at is not None:
169
+ payload["scheduledAt"] = file.scheduled_at
170
+ return payload
171
+
172
+
173
+ def time_slot_payload(slot: TimeSlot) -> Payload:
174
+ """
175
+ The body of a time slot's `PUT`, with the duration carried into hours
176
+ the way the server stores and reads it back.
177
+ """
178
+ minutes = slot.duration.hours * 60 + slot.duration.minutes
179
+ return {
180
+ "slug": slot.slug,
181
+ "title": slot.title,
182
+ "day": slot.day,
183
+ "start": {"hour": slot.start.hour, "minute": slot.start.minute},
184
+ "duration": {"hours": minutes // 60, "minutes": minutes % 60},
185
+ }
186
+
187
+
188
+ def event_payload(event: Event) -> Payload:
189
+ """
190
+ The body of a calendar event's `PUT`, with the repositories sorted by
191
+ slug, the order the server lists them in.
192
+ """
193
+ repositories: list[JsonValue] = [*sorted(event.repositories)]
194
+ return {
195
+ "kind": event.kind,
196
+ "title": event.title,
197
+ "description": event.description,
198
+ "week": event.week,
199
+ "timeSlot": event.time_slot,
200
+ "repositories": repositories,
201
+ }
202
+
203
+
204
+ def grade_column_payload(column: GradeColumn) -> Payload:
205
+ """
206
+ The body of a grade column's `PUT`, with the strings trimmed and the
207
+ values ordered by username, as the server stores and lists them.
208
+ """
209
+ values: list[JsonValue] = [
210
+ {
211
+ "username": username,
212
+ "value": value.strip() if isinstance(value, str) else value,
213
+ }
214
+ for username, value in sorted(column.values, key=lambda item: item[0])
215
+ ]
216
+ return {
217
+ "slug": column.slug,
218
+ "title": column.title.strip(),
219
+ "kind": column.kind.upper(),
220
+ "position": column.position,
221
+ "values": values,
222
+ }
codehood/py.typed ADDED
File without changes
@@ -0,0 +1,62 @@
1
+ """
2
+ Layout and scaffolding for a course repository.
3
+
4
+ A course repository is a directory of plain text an instructor edits,
5
+ commits, and pushes: `codehood.toml`, `README.md`, `calendar.md`,
6
+ `questions/`, `exams/`, and `resources/`. This module knows that layout and
7
+ how to write it, but nothing about the terminal or the network -- see
8
+ `dev/specs/to-do/init.md`.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from ._config import config_path, set_config_override
14
+ from ._layout import (
15
+ CALENDAR_FILE,
16
+ CONFIG_FILE,
17
+ EXAMPLE_EXAM_FILE,
18
+ EXAMPLE_ID,
19
+ EXAMPLE_QUESTION_FILE,
20
+ EXAMS_DIR,
21
+ GIT_DIR,
22
+ GITIGNORE_FILE,
23
+ MACHINE_DIR,
24
+ QUESTIONS_DIR,
25
+ README_FILE,
26
+ REPOSITORIES_DIR,
27
+ RESOURCES_DIR,
28
+ )
29
+ from ._scaffold import (
30
+ IdentityConflictError,
31
+ PathReport,
32
+ PathStatus,
33
+ RepoError,
34
+ ensure_machine_dir,
35
+ read_config,
36
+ write_repo,
37
+ )
38
+
39
+ __all__ = [
40
+ "CALENDAR_FILE",
41
+ "CONFIG_FILE",
42
+ "EXAMPLE_EXAM_FILE",
43
+ "EXAMPLE_ID",
44
+ "EXAMPLE_QUESTION_FILE",
45
+ "EXAMS_DIR",
46
+ "GITIGNORE_FILE",
47
+ "GIT_DIR",
48
+ "MACHINE_DIR",
49
+ "QUESTIONS_DIR",
50
+ "README_FILE",
51
+ "REPOSITORIES_DIR",
52
+ "RESOURCES_DIR",
53
+ "IdentityConflictError",
54
+ "PathReport",
55
+ "PathStatus",
56
+ "RepoError",
57
+ "config_path",
58
+ "ensure_machine_dir",
59
+ "read_config",
60
+ "set_config_override",
61
+ "write_repo",
62
+ ]
@@ -0,0 +1,28 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from . import _layout
6
+
7
+ __all__ = ["config_path", "set_config_override"]
8
+
9
+ #: The file `--config` / `CODEHOOD_CONFIG` points at, set once per invocation
10
+ #: by the app callback.
11
+ config_override: Path | None = None
12
+
13
+
14
+ def set_config_override(path: Path | None) -> None:
15
+ """
16
+ Make `config_path` return `path` instead of `<root>/codehood.toml`, or restore the default with `None`.
17
+ """
18
+ global config_override
19
+ config_override = path
20
+
21
+
22
+ def config_path(root: Path) -> Path:
23
+ """
24
+ The config file to read for the repository at `root`: the override when set, else `root/codehood.toml`.
25
+ """
26
+ if config_override is not None:
27
+ return config_override
28
+ return root / _layout.CONFIG_FILE
@@ -0,0 +1,132 @@
1
+ from __future__ import annotations
2
+
3
+ # Names of the files and directories `init` writes, relative to the
4
+ # repository root. Kept as constants so a rename is a diff in one place.
5
+ CONFIG_FILE = "codehood.toml"
6
+ README_FILE = "README.md"
7
+ CALENDAR_FILE = "calendar.md"
8
+ GITIGNORE_FILE = ".gitignore"
9
+ QUESTIONS_DIR = "questions"
10
+ EXAMS_DIR = "exams"
11
+ RESOURCES_DIR = "resources"
12
+ REPOSITORIES_DIR = "repositories"
13
+ LOCAL_DIR = ".local"
14
+ MACHINE_DIR = ".local/codehood"
15
+ MACHINE_GITIGNORE = "*\n"
16
+ GIT_DIR = ".git"
17
+
18
+ # The example question and exam. Flat filenames -- see the spec's
19
+ # "`questions/` is flat too" and "`exams/` is flat" sections -- and plain
20
+ # `.md`, so editors and forges treat the file as Markdown.
21
+ EXAMPLE_ID = "example"
22
+ EXAMPLE_QUESTION_FILE = f"{EXAMPLE_ID}.md"
23
+ EXAMPLE_EXAM_FILE = f"{EXAMPLE_ID}.md"
24
+
25
+
26
+ def render_gitignore() -> str:
27
+ """
28
+ Render the `.gitignore` `init` writes at the repository root.
29
+
30
+ Only the usual OS noise: the machine state in `.local/codehood/` ignores
31
+ itself through its own `.gitignore`. This is a content repository, not a
32
+ Python project.
33
+ """
34
+ return ".DS_Store\nThumbs.db\n"
35
+
36
+
37
+ def render_readme(name: str) -> str:
38
+ """
39
+ Render the `README.md` `init` writes.
40
+
41
+ The H1 is a local title only -- the server has no course name, just
42
+ `Discipline.name`, shared across every edition and instructor, and a
43
+ per-course file must not rename a shared row. `push` sends the
44
+ paragraph under the H1 as the course's description and ignores the H1
45
+ itself; see `dev/specs/to-do/push.md`, "The README's H1 is ignored".
46
+ """
47
+ return (
48
+ f"# {name}\n"
49
+ "\n"
50
+ "Course description. Edit this paragraph -- it becomes the course's\n"
51
+ "public description, shown to someone who has not enrolled.\n"
52
+ )
53
+
54
+
55
+ def render_calendar() -> str:
56
+ """
57
+ Render the `calendar.md` `init` writes.
58
+
59
+ Format is provisional -- the calendar spec that settles it is still in
60
+ `dev/specs/to-do/` -- so this is placeholder frontmatter an instructor
61
+ is expected to replace with the term's real dates.
62
+ """
63
+ return (
64
+ "---\n"
65
+ "start: 2026-01-01\n"
66
+ "end: 2026-06-01\n"
67
+ "days:\n"
68
+ " - Mon 14:00 2h, Lecture\n"
69
+ "holidays: []\n"
70
+ "---\n"
71
+ "\n"
72
+ "# Schedule\n"
73
+ "\n"
74
+ "## Course overview\n"
75
+ "\n"
76
+ "What we will cover, how grading works.\n"
77
+ "\n"
78
+ "* Course presentation\n"
79
+ "* Instructor contact\n"
80
+ "* Office hours\n"
81
+ )
82
+
83
+
84
+ def render_example_question() -> str:
85
+ """
86
+ Render `questions/example.md`.
87
+
88
+ Real MDQ, not a placeholder: it parses and it would push. It sets
89
+ neither `id` nor a filename that disagrees with one, so the filename
90
+ stem (`example`) is its id by default.
91
+ """
92
+ return (
93
+ "---\n"
94
+ "title: Example question\n"
95
+ "---\n"
96
+ "\n"
97
+ "What is 2 + 2?\n"
98
+ "\n"
99
+ "- [ ] 3\n"
100
+ "- [*] 4\n"
101
+ "- [ ] 5\n"
102
+ )
103
+
104
+
105
+ def render_example_exam(discipline: str) -> str:
106
+ """
107
+ Render `exams/example.md`.
108
+
109
+ Includes the example question by id (`example`, the question's
110
+ filename stem), so the pair parses and the first `codehood push` has
111
+ something real to do.
112
+
113
+ Args:
114
+ discipline: The course's discipline slug, written as the exam's
115
+ `course` field.
116
+ """
117
+ return (
118
+ "---\n"
119
+ f"course: {discipline}\n"
120
+ "start: 2026-01-01T09:00:00\n"
121
+ "duration: 1h\n"
122
+ "---\n"
123
+ "\n"
124
+ "# Example Exam\n"
125
+ "\n"
126
+ "Generated by `codehood init`. Replace it with a real exam, or\n"
127
+ "delete this pair along with `questions/example.md`.\n"
128
+ "\n"
129
+ "---\n"
130
+ f"include: {EXAMPLE_ID}\n"
131
+ "---\n"
132
+ )