github-milestone-roadmap 0.1.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.
@@ -0,0 +1,304 @@
1
+ """Load and validate the roadmap configuration file (TOML)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import tomllib
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ DEFAULT_HEADING = "Community Roadmap"
12
+
13
+ _TOP_LEVEL_KEYS = {
14
+ "title",
15
+ "heading",
16
+ "subtitle",
17
+ "description",
18
+ "source_url",
19
+ "cache_key",
20
+ "home",
21
+ "repos",
22
+ }
23
+ _HOME_KEYS = {"text", "url"}
24
+ _REPO_KEYS = {"owner", "name", "description"}
25
+ _REPO_PART_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
26
+
27
+
28
+ class ConfigError(ValueError):
29
+ """Raised when the roadmap configuration is invalid."""
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class RepoConfig:
34
+ """A GitHub repository shown on the roadmap.
35
+
36
+ Attributes
37
+ ----------
38
+ owner : str
39
+ GitHub user or organisation owning the repository.
40
+ name : str
41
+ Repository name. Also used as the page anchor, so it must be unique.
42
+ description : str
43
+ Short description shown under the repository heading.
44
+ """
45
+
46
+ owner: str
47
+ name: str
48
+ description: str = ""
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class HomeLink:
53
+ """The brand link in the top-left corner of the page.
54
+
55
+ Attributes
56
+ ----------
57
+ text : str
58
+ Link text.
59
+ url : str
60
+ Link target.
61
+ """
62
+
63
+ text: str
64
+ url: str
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class RoadmapConfig:
69
+ """Configuration of one roadmap site.
70
+
71
+ Attributes
72
+ ----------
73
+ title : str
74
+ Browser tab title.
75
+ heading : str
76
+ Main page heading.
77
+ subtitle : str
78
+ Line shown under the heading.
79
+ description : str
80
+ Content of the ``<meta name="description">`` tag.
81
+ source_url : str
82
+ URL of the GitHub link in the top-right corner; empty hides the link.
83
+ cache_key : str
84
+ Prefix for the browser ``localStorage`` cache of GitHub API responses.
85
+ home : HomeLink
86
+ Brand link in the top-left corner.
87
+ repos : tuple of RepoConfig
88
+ Repositories shown on the roadmap, in display order.
89
+ """
90
+
91
+ title: str
92
+ heading: str
93
+ subtitle: str
94
+ description: str
95
+ source_url: str
96
+ cache_key: str
97
+ home: HomeLink
98
+ repos: tuple[RepoConfig, ...]
99
+
100
+
101
+ def slugify_text(text: str) -> str:
102
+ """Turn free text into a lowercase, hyphen-separated slug.
103
+
104
+ Parameters
105
+ ----------
106
+ text : str
107
+ Text to convert.
108
+
109
+ Returns
110
+ -------
111
+ str
112
+ Slug containing only ``a-z``, ``0-9`` and ``-``.
113
+ """
114
+ return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
115
+
116
+
117
+ def read_string_field(
118
+ table: dict[str, Any], key: str, where: str, default: str | None = None
119
+ ) -> str:
120
+ """Read a string value from a TOML table.
121
+
122
+ Parameters
123
+ ----------
124
+ table : dict
125
+ Parsed TOML table.
126
+ key : str
127
+ Key to read.
128
+ where : str
129
+ Location of the table, used in error messages.
130
+ default : str or None
131
+ Value used when the key is missing; ``None`` makes the key required.
132
+
133
+ Returns
134
+ -------
135
+ str
136
+ The value.
137
+
138
+ Raises
139
+ ------
140
+ ConfigError
141
+ If the key is required and missing, or the value is not a string.
142
+ """
143
+ if key not in table:
144
+ if default is None:
145
+ raise ConfigError(f"{where}: missing required key '{key}'")
146
+ return default
147
+ value = table[key]
148
+ if not isinstance(value, str):
149
+ raise ConfigError(f"{where}: '{key}' must be a string, got {value!r}")
150
+ return value
151
+
152
+
153
+ def check_unknown_keys(table: dict[str, Any], allowed: set[str], where: str) -> None:
154
+ """Fail on keys that the configuration format does not know.
155
+
156
+ Parameters
157
+ ----------
158
+ table : dict
159
+ Parsed TOML table.
160
+ allowed : set of str
161
+ Keys allowed in this table.
162
+ where : str
163
+ Location of the table, used in error messages.
164
+
165
+ Raises
166
+ ------
167
+ ConfigError
168
+ If the table contains keys outside ``allowed``.
169
+ """
170
+ unknown = sorted(set(table) - allowed)
171
+ if unknown:
172
+ raise ConfigError(
173
+ f"{where}: unknown key(s) {', '.join(unknown)}; "
174
+ f"allowed: {', '.join(sorted(allowed))}"
175
+ )
176
+
177
+
178
+ def parse_repo_entry(entry: Any, index: int) -> RepoConfig:
179
+ """Validate one ``[[repos]]`` entry.
180
+
181
+ Parameters
182
+ ----------
183
+ entry : Any
184
+ Parsed TOML value of the entry.
185
+ index : int
186
+ Position of the entry, used in error messages.
187
+
188
+ Returns
189
+ -------
190
+ RepoConfig
191
+ The validated repository.
192
+
193
+ Raises
194
+ ------
195
+ ConfigError
196
+ If the entry is malformed.
197
+ """
198
+ where = f"repos[{index}]"
199
+ if not isinstance(entry, dict):
200
+ raise ConfigError(f"{where}: must be a table with 'owner' and 'name'")
201
+ check_unknown_keys(entry, _REPO_KEYS, where)
202
+ owner = read_string_field(entry, "owner", where)
203
+ name = read_string_field(entry, "name", where)
204
+ for key, value in (("owner", owner), ("name", name)):
205
+ if not _REPO_PART_RE.match(value):
206
+ raise ConfigError(f"{where}: '{key}' is not a valid GitHub name: {value!r}")
207
+ description = read_string_field(entry, "description", where, default="")
208
+ return RepoConfig(owner=owner, name=name, description=description)
209
+
210
+
211
+ def parse_config_data(data: dict[str, Any]) -> RoadmapConfig:
212
+ """Validate parsed TOML data and fill in defaults.
213
+
214
+ Parameters
215
+ ----------
216
+ data : dict
217
+ Parsed TOML document.
218
+
219
+ Returns
220
+ -------
221
+ RoadmapConfig
222
+ The validated configuration.
223
+
224
+ Raises
225
+ ------
226
+ ConfigError
227
+ If the data does not describe a valid roadmap.
228
+ """
229
+ check_unknown_keys(data, _TOP_LEVEL_KEYS, "config")
230
+ title = read_string_field(data, "title", "config")
231
+ heading = read_string_field(data, "heading", "config", default=DEFAULT_HEADING)
232
+ subtitle = read_string_field(data, "subtitle", "config", default="")
233
+ description = read_string_field(
234
+ data, "description", "config", default=subtitle or title
235
+ )
236
+ source_url = read_string_field(data, "source_url", "config", default="")
237
+ cache_key = read_string_field(
238
+ data, "cache_key", "config", default=slugify_text(title) or "roadmap"
239
+ )
240
+
241
+ home_data = data.get("home", {})
242
+ if not isinstance(home_data, dict):
243
+ raise ConfigError("home: must be a table with 'text' and 'url'")
244
+ check_unknown_keys(home_data, _HOME_KEYS, "home")
245
+ home = HomeLink(
246
+ text=read_string_field(home_data, "text", "home", default=title),
247
+ url=read_string_field(home_data, "url", "home", default="/"),
248
+ )
249
+
250
+ repos_data = data.get("repos")
251
+ if not isinstance(repos_data, list) or not repos_data:
252
+ raise ConfigError("config: at least one [[repos]] entry is required")
253
+ repos = tuple(parse_repo_entry(entry, i) for i, entry in enumerate(repos_data))
254
+
255
+ seen: set[str] = set()
256
+ for repo in repos:
257
+ if repo.name in seen:
258
+ raise ConfigError(
259
+ f"repos: repository name '{repo.name}' is used twice; "
260
+ "names must be unique because they are used as page anchors"
261
+ )
262
+ seen.add(repo.name)
263
+
264
+ return RoadmapConfig(
265
+ title=title,
266
+ heading=heading,
267
+ subtitle=subtitle,
268
+ description=description,
269
+ source_url=source_url,
270
+ cache_key=cache_key,
271
+ home=home,
272
+ repos=repos,
273
+ )
274
+
275
+
276
+ def load_config(path: Path) -> RoadmapConfig:
277
+ """Read and validate a roadmap configuration file.
278
+
279
+ Parameters
280
+ ----------
281
+ path : Path
282
+ Path to the TOML configuration file.
283
+
284
+ Returns
285
+ -------
286
+ RoadmapConfig
287
+ The validated configuration.
288
+
289
+ Raises
290
+ ------
291
+ ConfigError
292
+ If the file is not valid TOML or not a valid roadmap configuration.
293
+ FileNotFoundError
294
+ If the file does not exist.
295
+ """
296
+ with path.open("rb") as file:
297
+ try:
298
+ data = tomllib.load(file)
299
+ except tomllib.TOMLDecodeError as exc:
300
+ raise ConfigError(f"{path}: invalid TOML: {exc}") from exc
301
+ try:
302
+ return parse_config_data(data)
303
+ except ConfigError as exc:
304
+ raise ConfigError(f"{path}: {exc}") from exc