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.
- github_milestone_roadmap/__init__.py +8 -0
- github_milestone_roadmap/build.py +169 -0
- github_milestone_roadmap/changes.py +377 -0
- github_milestone_roadmap/cli.py +142 -0
- github_milestone_roadmap/config.py +304 -0
- github_milestone_roadmap/static/app.js +577 -0
- github_milestone_roadmap/static/index.html +49 -0
- github_milestone_roadmap/static/styles.css +589 -0
- github_milestone_roadmap-0.1.0.dist-info/METADATA +134 -0
- github_milestone_roadmap-0.1.0.dist-info/RECORD +13 -0
- github_milestone_roadmap-0.1.0.dist-info/WHEEL +4 -0
- github_milestone_roadmap-0.1.0.dist-info/entry_points.txt +2 -0
- github_milestone_roadmap-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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
|