reqtable 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.
- reqtable/__init__.py +3 -0
- reqtable/__main__.py +3 -0
- reqtable/baselines.py +920 -0
- reqtable/cli.py +631 -0
- reqtable/comparison.py +63 -0
- reqtable/core.py +1448 -0
- reqtable/drafts.py +166 -0
- reqtable/findings.py +605 -0
- reqtable/gate_checks.py +84 -0
- reqtable/gates.py +348 -0
- reqtable/glossary.py +162 -0
- reqtable/gui.py +952 -0
- reqtable/gui_lookups.py +192 -0
- reqtable/gui_mapping.py +789 -0
- reqtable/gui_page.py +691 -0
- reqtable/gui_page_gates.py +173 -0
- reqtable/gui_page_mapping.py +390 -0
- reqtable/gui_server.py +467 -0
- reqtable/html_report.py +2595 -0
- reqtable/markdown.py +127 -0
- reqtable/package.py +163 -0
- reqtable/quality.py +422 -0
- reqtable/review.py +318 -0
- reqtable/signoff.py +179 -0
- reqtable/traceability.py +1670 -0
- reqtable/values.py +192 -0
- reqtable/waivers.py +109 -0
- reqtable/xlsx.py +1108 -0
- reqtable-0.1.0.dist-info/METADATA +106 -0
- reqtable-0.1.0.dist-info/RECORD +33 -0
- reqtable-0.1.0.dist-info/WHEEL +4 -0
- reqtable-0.1.0.dist-info/entry_points.txt +2 -0
- reqtable-0.1.0.dist-info/licenses/LICENSE +21 -0
reqtable/gui_mapping.py
ADDED
|
@@ -0,0 +1,789 @@
|
|
|
1
|
+
"""The GUI's workbook mapping builder: what each kind of table can fill in, and the pure code that turns a form into
|
|
2
|
+
the ``xlsx.sources`` mapping documented in docs/excel.md. Only ``preview_mapping`` and ``save_mapping`` touch the disk."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import json
|
|
7
|
+
from collections import Counter
|
|
8
|
+
from dataclasses import asdict, dataclass
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any, Mapping
|
|
11
|
+
|
|
12
|
+
from .core import (
|
|
13
|
+
ConfigError,
|
|
14
|
+
ReqtableError,
|
|
15
|
+
atomic_write_text,
|
|
16
|
+
validate_headings,
|
|
17
|
+
validate_xlsx_sources,
|
|
18
|
+
)
|
|
19
|
+
from .gui import BadRequest, GuiError, guess_id_column
|
|
20
|
+
from .xlsx import SourceStats, XlsxSelection, import_workbook
|
|
21
|
+
|
|
22
|
+
ID_COLUMN = "ID"
|
|
23
|
+
FIELD_COLUMN = "Field"
|
|
24
|
+
SEPARATORS = ((",", "Comma"), (";", "Semicolon"), ("newline", "New line"))
|
|
25
|
+
LIST_SEPARATOR = ","
|
|
26
|
+
DEFAULT_CATEGORY = "Category"
|
|
27
|
+
KEEP, MAP, EXCLUDE = "keep", "map", "exclude"
|
|
28
|
+
FIELD_CHOICES = (
|
|
29
|
+
("Priority", "Priority"),
|
|
30
|
+
("Verification Method", "Verification Method"),
|
|
31
|
+
("Verification Level", "Verification Level (verification stages)"),
|
|
32
|
+
("Execution", "Execution (manual or automated)"),
|
|
33
|
+
("Compliance", "Compliance"),
|
|
34
|
+
("Result", "Result"),
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class Target:
|
|
40
|
+
"""An output column a role offers. `hints` are other header names that should be matched to it automatically."""
|
|
41
|
+
|
|
42
|
+
column: str
|
|
43
|
+
label: str
|
|
44
|
+
list_separator: bool = False
|
|
45
|
+
hints: tuple[str, ...] = ()
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True)
|
|
49
|
+
class Role:
|
|
50
|
+
id: str
|
|
51
|
+
label: str
|
|
52
|
+
help: str
|
|
53
|
+
type: str | None
|
|
54
|
+
targets: tuple[Target, ...]
|
|
55
|
+
id_prefix: str = ""
|
|
56
|
+
needs_field: bool = False
|
|
57
|
+
merge: bool = False
|
|
58
|
+
headings: bool = False
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _id(label: str = "ID") -> Target:
|
|
62
|
+
return Target(ID_COLUMN, label, hints=("id",))
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
NAME = Target("Name", "Name", hints=("title",))
|
|
66
|
+
REFERENCE = Target("Reference", "Link or citation", hints=("url", "link"))
|
|
67
|
+
METHOD = Target("Verification Method", "Verification Method", True, ("method",))
|
|
68
|
+
LEVEL = Target(
|
|
69
|
+
"Verification Level",
|
|
70
|
+
"Verification Level (verification stages)",
|
|
71
|
+
True,
|
|
72
|
+
("level", "stage"),
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
ROLES: tuple[Role, ...] = (
|
|
76
|
+
Role(
|
|
77
|
+
"requirements",
|
|
78
|
+
"Requirements",
|
|
79
|
+
"The requirements themselves. Each row keeps its own Type.",
|
|
80
|
+
None,
|
|
81
|
+
(
|
|
82
|
+
_id("ID"),
|
|
83
|
+
Target("Name", "Short title", hints=("title",)),
|
|
84
|
+
Target(
|
|
85
|
+
"Requirement",
|
|
86
|
+
"Requirement text",
|
|
87
|
+
hints=("text", "description", "shall"),
|
|
88
|
+
),
|
|
89
|
+
Target("Priority", "Priority"),
|
|
90
|
+
METHOD,
|
|
91
|
+
LEVEL,
|
|
92
|
+
Target("Verified by", "Tests that verify it", True, ("tests",)),
|
|
93
|
+
Target("Allocated to", "Systems it is allocated to", True),
|
|
94
|
+
Target("Derived from", "Parent requirements", True, ("parent",)),
|
|
95
|
+
Target("Source refs", "Needs and sources", True, ("sources",)),
|
|
96
|
+
Target("Owner", "Owning system"),
|
|
97
|
+
Target("Rationale", "Rationale"),
|
|
98
|
+
Target("Compliance", "Compliance (is it met?)"),
|
|
99
|
+
Target("Type", "Record type", hints=("kind",)),
|
|
100
|
+
),
|
|
101
|
+
headings=True,
|
|
102
|
+
),
|
|
103
|
+
Role(
|
|
104
|
+
"glossary",
|
|
105
|
+
"Glossary terms",
|
|
106
|
+
"Words and abbreviations the project defines. Each row becomes a Term.",
|
|
107
|
+
"Term",
|
|
108
|
+
(
|
|
109
|
+
_id("ID"),
|
|
110
|
+
Target("Name", "Term", hints=("name", "word")),
|
|
111
|
+
Target("Definition", "Meaning", hints=("meaning", "description")),
|
|
112
|
+
Target(
|
|
113
|
+
"Aliases",
|
|
114
|
+
"Other spellings",
|
|
115
|
+
True,
|
|
116
|
+
("abbreviation", "synonyms", "alias"),
|
|
117
|
+
),
|
|
118
|
+
Target("Auto Link", "Link automatically in text", hints=("autolink",)),
|
|
119
|
+
REFERENCE,
|
|
120
|
+
),
|
|
121
|
+
id_prefix="TERM-",
|
|
122
|
+
),
|
|
123
|
+
Role(
|
|
124
|
+
"values",
|
|
125
|
+
"Allowed values",
|
|
126
|
+
"The values a column may hold, such as Must and Should for Priority, or Unit and System for Verification Level.",
|
|
127
|
+
"Value",
|
|
128
|
+
(
|
|
129
|
+
_id("ID"),
|
|
130
|
+
Target(FIELD_COLUMN, "Column the value belongs to", hints=("column",)),
|
|
131
|
+
Target("Name", "Allowed value", hints=("value",)),
|
|
132
|
+
Target("Definition", "Meaning", hints=("meaning", "description")),
|
|
133
|
+
Target("Aliases", "Old spellings", True, ("synonyms", "alias")),
|
|
134
|
+
REFERENCE,
|
|
135
|
+
),
|
|
136
|
+
id_prefix="VAL-",
|
|
137
|
+
needs_field=True,
|
|
138
|
+
),
|
|
139
|
+
Role(
|
|
140
|
+
"tests",
|
|
141
|
+
"Tests",
|
|
142
|
+
"Tests, scripts or checklists that verify requirements. The description lands in the Requirement column.",
|
|
143
|
+
"Test",
|
|
144
|
+
(
|
|
145
|
+
_id("ID"),
|
|
146
|
+
Target("Name", "Test title", hints=("title", "name")),
|
|
147
|
+
Target(
|
|
148
|
+
"Requirement", "Description", hints=("description", "text", "steps")
|
|
149
|
+
),
|
|
150
|
+
Target("Test plan", "Test plan", hints=("plan",)),
|
|
151
|
+
METHOD,
|
|
152
|
+
LEVEL,
|
|
153
|
+
Target("Execution", "How it is run (Manual or Automated)"),
|
|
154
|
+
Target("Result", "Result", hints=("status",)),
|
|
155
|
+
Target("Reference", "Link to the test", hints=("url", "link")),
|
|
156
|
+
),
|
|
157
|
+
id_prefix="TEST-",
|
|
158
|
+
),
|
|
159
|
+
Role(
|
|
160
|
+
"plans",
|
|
161
|
+
"Test plans",
|
|
162
|
+
"Groups of tests. The description lands in the Requirement column.",
|
|
163
|
+
"Test plan",
|
|
164
|
+
(
|
|
165
|
+
_id("ID"),
|
|
166
|
+
Target("Name", "Plan title", hints=("title",)),
|
|
167
|
+
Target("Requirement", "Description", hints=("description", "text")),
|
|
168
|
+
REFERENCE,
|
|
169
|
+
),
|
|
170
|
+
id_prefix="PLAN-",
|
|
171
|
+
),
|
|
172
|
+
Role(
|
|
173
|
+
"systems",
|
|
174
|
+
"Systems",
|
|
175
|
+
"The systems and subsystems the requirements are allocated to.",
|
|
176
|
+
"System",
|
|
177
|
+
(
|
|
178
|
+
_id("ID"),
|
|
179
|
+
NAME,
|
|
180
|
+
Target("Part of", "Parent system", hints=("parent",)),
|
|
181
|
+
REFERENCE,
|
|
182
|
+
),
|
|
183
|
+
id_prefix="SYS-",
|
|
184
|
+
),
|
|
185
|
+
Role(
|
|
186
|
+
"needs",
|
|
187
|
+
"Needs",
|
|
188
|
+
"Stakeholder needs that requirements trace back to. The description lands in the Requirement column.",
|
|
189
|
+
"Need",
|
|
190
|
+
(
|
|
191
|
+
_id("ID"),
|
|
192
|
+
NAME,
|
|
193
|
+
Target("Requirement", "Description", hints=("description", "text")),
|
|
194
|
+
Target("Source refs", "Sources", True, ("sources",)),
|
|
195
|
+
REFERENCE,
|
|
196
|
+
),
|
|
197
|
+
id_prefix="NEED-",
|
|
198
|
+
),
|
|
199
|
+
Role(
|
|
200
|
+
"sources",
|
|
201
|
+
"Sources",
|
|
202
|
+
"Documents, standards or people that needs and requirements cite.",
|
|
203
|
+
"Source",
|
|
204
|
+
(_id("ID"), NAME, REFERENCE),
|
|
205
|
+
id_prefix="SRC-",
|
|
206
|
+
),
|
|
207
|
+
)
|
|
208
|
+
ROLES += (
|
|
209
|
+
Role(
|
|
210
|
+
"merge",
|
|
211
|
+
"Details for existing requirements (matched by ID)",
|
|
212
|
+
"Fills in cells of requirements that are already imported, matching each row by ID. Use it for a verification "
|
|
213
|
+
"matrix sheet, or add a tests table a second time here to link its tests to the requirements they verify.",
|
|
214
|
+
None,
|
|
215
|
+
(
|
|
216
|
+
Target(
|
|
217
|
+
ID_COLUMN,
|
|
218
|
+
"Requirement ID (which requirement this row is about)",
|
|
219
|
+
True,
|
|
220
|
+
(
|
|
221
|
+
"requirement",
|
|
222
|
+
"requirements",
|
|
223
|
+
"requirement id",
|
|
224
|
+
"req",
|
|
225
|
+
"req id",
|
|
226
|
+
"verifies",
|
|
227
|
+
),
|
|
228
|
+
),
|
|
229
|
+
LEVEL,
|
|
230
|
+
METHOD,
|
|
231
|
+
Target(
|
|
232
|
+
"Verified by",
|
|
233
|
+
"Tests that verify it",
|
|
234
|
+
True,
|
|
235
|
+
("test", "tests", "test id"),
|
|
236
|
+
),
|
|
237
|
+
Target("Priority", "Priority"),
|
|
238
|
+
Target("Rationale", "Rationale"),
|
|
239
|
+
),
|
|
240
|
+
merge=True,
|
|
241
|
+
),
|
|
242
|
+
)
|
|
243
|
+
ROLES_BY_ID = {role.id: role for role in ROLES}
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def role_named(role_id: str) -> Role:
|
|
247
|
+
try:
|
|
248
|
+
return ROLES_BY_ID[role_id]
|
|
249
|
+
except KeyError:
|
|
250
|
+
raise BadRequest(f"unknown role {role_id!r}") from None
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def role_for_type(record_type: str | None) -> Role | None:
|
|
254
|
+
return next((role for role in ROLES if role.type == record_type), None)
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
def mapping_json() -> dict[str, Any]:
|
|
258
|
+
return {
|
|
259
|
+
"roles": [asdict(role) for role in ROLES],
|
|
260
|
+
"separators": [{"value": value, "label": label} for value, label in SEPARATORS],
|
|
261
|
+
"fields": [{"value": value, "label": label} for value, label in FIELD_CHOICES],
|
|
262
|
+
"id_column": ID_COLUMN,
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def suggest_columns(role: Role, headers: list[str]) -> dict[str, Any]:
|
|
267
|
+
"""Prefill: each header goes to the role target it is named after. Any other header is kept as it is, except in a
|
|
268
|
+
merge source, where a kept column would be added to every requirement."""
|
|
269
|
+
guessed_id = guess_id_column(headers)
|
|
270
|
+
taken: set[str] = set()
|
|
271
|
+
columns = []
|
|
272
|
+
for header in headers:
|
|
273
|
+
name = header.strip().casefold()
|
|
274
|
+
target = None
|
|
275
|
+
for candidate in role.targets:
|
|
276
|
+
if candidate.column in taken:
|
|
277
|
+
continue
|
|
278
|
+
if candidate.column == ID_COLUMN and not role.merge:
|
|
279
|
+
hit = header == guessed_id and bool(guessed_id)
|
|
280
|
+
else:
|
|
281
|
+
hit = name in {
|
|
282
|
+
candidate.column.casefold(),
|
|
283
|
+
candidate.label.casefold(),
|
|
284
|
+
*candidate.hints,
|
|
285
|
+
}
|
|
286
|
+
if hit:
|
|
287
|
+
target = candidate
|
|
288
|
+
break
|
|
289
|
+
if target is None:
|
|
290
|
+
columns.append(
|
|
291
|
+
{
|
|
292
|
+
"header": header,
|
|
293
|
+
"action": EXCLUDE if role.merge else KEEP,
|
|
294
|
+
"to": "",
|
|
295
|
+
"separator": "",
|
|
296
|
+
}
|
|
297
|
+
)
|
|
298
|
+
continue
|
|
299
|
+
taken.add(target.column)
|
|
300
|
+
columns.append(
|
|
301
|
+
{
|
|
302
|
+
"header": header,
|
|
303
|
+
"action": MAP,
|
|
304
|
+
"to": target.column,
|
|
305
|
+
"separator": LIST_SEPARATOR if target.list_separator else "",
|
|
306
|
+
}
|
|
307
|
+
)
|
|
308
|
+
if role.merge and ID_COLUMN not in taken and guessed_id:
|
|
309
|
+
# A merge key is the requirement a row points to; a header that only looks like an ID is the fallback.
|
|
310
|
+
fallback = next(c for c in columns if c["header"] == guessed_id)
|
|
311
|
+
if fallback["action"] != MAP:
|
|
312
|
+
fallback.update(action=MAP, to=ID_COLUMN, separator=LIST_SEPARATOR)
|
|
313
|
+
taken.add(ID_COLUMN)
|
|
314
|
+
has_id = ID_COLUMN in taken
|
|
315
|
+
return {
|
|
316
|
+
"columns": columns,
|
|
317
|
+
"id_prefix": "" if has_id or role.merge else role.id_prefix,
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
@dataclass(frozen=True)
|
|
322
|
+
class ColumnDraft:
|
|
323
|
+
header: str
|
|
324
|
+
action: str
|
|
325
|
+
to: str
|
|
326
|
+
separator: str
|
|
327
|
+
|
|
328
|
+
@property
|
|
329
|
+
def output(self) -> str:
|
|
330
|
+
return self.to if self.action == MAP else self.header
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
@dataclass(frozen=True)
|
|
334
|
+
class HeadingRows:
|
|
335
|
+
"""Rows whose `column` cell holds one of `values` are category names; the requirements below one get its text in `into`."""
|
|
336
|
+
|
|
337
|
+
column: str
|
|
338
|
+
values: tuple[str, ...]
|
|
339
|
+
text: str
|
|
340
|
+
into: str = DEFAULT_CATEGORY
|
|
341
|
+
|
|
342
|
+
def to_json(self) -> dict[str, Any]:
|
|
343
|
+
return {
|
|
344
|
+
"column": self.column,
|
|
345
|
+
"values": list(self.values),
|
|
346
|
+
**({"text": self.text} if self.text else {}),
|
|
347
|
+
"into": self.into,
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
@classmethod
|
|
351
|
+
def from_json(cls, headings: Mapping[str, Any]) -> HeadingRows:
|
|
352
|
+
return cls(
|
|
353
|
+
headings["column"],
|
|
354
|
+
tuple(headings["values"]),
|
|
355
|
+
headings.get("text", ""),
|
|
356
|
+
headings["into"],
|
|
357
|
+
)
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
@dataclass(frozen=True)
|
|
361
|
+
class SourceDraft:
|
|
362
|
+
kind: str
|
|
363
|
+
name: str
|
|
364
|
+
header_row: int | None
|
|
365
|
+
role: Role | None
|
|
366
|
+
field: str
|
|
367
|
+
id_prefix: str
|
|
368
|
+
columns: tuple[ColumnDraft, ...]
|
|
369
|
+
extra: Mapping[str, Any]
|
|
370
|
+
raw: Mapping[str, Any] | None = None
|
|
371
|
+
headings: HeadingRows | None = None
|
|
372
|
+
|
|
373
|
+
@property
|
|
374
|
+
def where(self) -> str:
|
|
375
|
+
return f"{self.kind} {self.name!r}"
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
def _text(value: object, where: str) -> str:
|
|
379
|
+
if value is None:
|
|
380
|
+
return ""
|
|
381
|
+
if not isinstance(value, str):
|
|
382
|
+
raise BadRequest(f"{where} must be text")
|
|
383
|
+
return value.strip()
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def _parse_column(item: object, where: str) -> ColumnDraft:
|
|
387
|
+
if not isinstance(item, Mapping):
|
|
388
|
+
raise BadRequest(f"{where} must be an object")
|
|
389
|
+
action = _text(item.get("action", KEEP), f"{where}.action")
|
|
390
|
+
if action not in (KEEP, MAP, EXCLUDE):
|
|
391
|
+
raise BadRequest(f"{where}.action must be keep, map or exclude")
|
|
392
|
+
return ColumnDraft(
|
|
393
|
+
_text(item.get("header"), f"{where}.header"),
|
|
394
|
+
action,
|
|
395
|
+
_text(item.get("to"), f"{where}.to"),
|
|
396
|
+
_text(item.get("separator"), f"{where}.separator"),
|
|
397
|
+
)
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def _parse_headings(item: object, where: str) -> HeadingRows | None:
|
|
401
|
+
if item is None:
|
|
402
|
+
return None
|
|
403
|
+
if not isinstance(item, Mapping):
|
|
404
|
+
raise BadRequest(f"{where} must be an object")
|
|
405
|
+
values = item.get("values", [])
|
|
406
|
+
if not isinstance(values, list):
|
|
407
|
+
raise BadRequest(f"{where}.values must be a list")
|
|
408
|
+
return HeadingRows(
|
|
409
|
+
_text(item.get("column"), f"{where}.column"),
|
|
410
|
+
tuple(v for v in (_text(v, f"{where}.values") for v in values) if v),
|
|
411
|
+
_text(item.get("text"), f"{where}.text"),
|
|
412
|
+
_text(item.get("into"), f"{where}.into"),
|
|
413
|
+
)
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def _parse_source(item: object, index: int) -> SourceDraft:
|
|
417
|
+
where = f"sources[{index}]"
|
|
418
|
+
if not isinstance(item, Mapping):
|
|
419
|
+
raise BadRequest(f"{where} must be an object")
|
|
420
|
+
kind = _text(item.get("kind"), f"{where}.kind")
|
|
421
|
+
if kind not in ("table", "sheet"):
|
|
422
|
+
raise BadRequest(f"{where}.kind must be table or sheet")
|
|
423
|
+
name = _text(item.get("name"), f"{where}.name")
|
|
424
|
+
if not name:
|
|
425
|
+
raise BadRequest(f"{where}.name is required")
|
|
426
|
+
if isinstance(item.get("raw"), Mapping):
|
|
427
|
+
return SourceDraft(kind, name, None, None, "", "", (), {}, item["raw"])
|
|
428
|
+
row = item.get("header_row")
|
|
429
|
+
header_row = None if row in (None, "") else row
|
|
430
|
+
if header_row is not None and (
|
|
431
|
+
isinstance(header_row, bool) or not isinstance(header_row, int)
|
|
432
|
+
):
|
|
433
|
+
try:
|
|
434
|
+
header_row = int(str(header_row))
|
|
435
|
+
except ValueError:
|
|
436
|
+
raise BadRequest(f"{where}.header_row must be a number") from None
|
|
437
|
+
role_id = _text(item.get("role"), f"{where}.role")
|
|
438
|
+
columns = item.get("columns", [])
|
|
439
|
+
extra = item.get("extra", {})
|
|
440
|
+
if not isinstance(columns, list) or not isinstance(extra, Mapping):
|
|
441
|
+
raise BadRequest(f"{where} has columns or extra of the wrong shape")
|
|
442
|
+
return SourceDraft(
|
|
443
|
+
kind,
|
|
444
|
+
name,
|
|
445
|
+
header_row,
|
|
446
|
+
role_named(role_id) if role_id else None,
|
|
447
|
+
_text(item.get("field"), f"{where}.field"),
|
|
448
|
+
_text(item.get("id_prefix"), f"{where}.id_prefix"),
|
|
449
|
+
tuple(
|
|
450
|
+
_parse_column(column, f"{where}.columns[{i}]")
|
|
451
|
+
for i, column in enumerate(columns)
|
|
452
|
+
),
|
|
453
|
+
extra,
|
|
454
|
+
headings=_parse_headings(item.get("headings"), f"{where}.headings"),
|
|
455
|
+
)
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
def _build_headings(draft: SourceDraft) -> dict[str, Any]:
|
|
459
|
+
headings = draft.headings
|
|
460
|
+
assert headings is not None
|
|
461
|
+
if not headings.column:
|
|
462
|
+
raise GuiError(f"{draft.where}: choose which column marks a heading row")
|
|
463
|
+
if not headings.values:
|
|
464
|
+
raise GuiError(
|
|
465
|
+
f"{draft.where}: say which value in {headings.column!r} marks a heading row, such as Heading"
|
|
466
|
+
)
|
|
467
|
+
if not headings.into:
|
|
468
|
+
raise GuiError(f"{draft.where}: say which column receives the category")
|
|
469
|
+
return headings.to_json()
|
|
470
|
+
|
|
471
|
+
|
|
472
|
+
def build_source(draft: SourceDraft, id_column: str) -> dict[str, Any]:
|
|
473
|
+
if draft.raw is not None:
|
|
474
|
+
return dict(draft.raw)
|
|
475
|
+
assert draft.role is not None
|
|
476
|
+
role = draft.role
|
|
477
|
+
if draft.headings and not role.headings:
|
|
478
|
+
raise BadRequest(f"{draft.where}: {role.label} cannot have heading rows")
|
|
479
|
+
source: dict[str, Any] = {draft.kind: draft.name}
|
|
480
|
+
if draft.kind == "sheet" and draft.header_row is not None:
|
|
481
|
+
source["header_row"] = draft.header_row
|
|
482
|
+
if role.type:
|
|
483
|
+
source["type"] = role.type
|
|
484
|
+
if role.merge:
|
|
485
|
+
source["merge"] = True
|
|
486
|
+
if not any(c.action == MAP and c.to == ID_COLUMN for c in draft.columns):
|
|
487
|
+
raise GuiError(
|
|
488
|
+
f"{draft.where}: choose which column holds the requirement ID, so each row finds its requirement"
|
|
489
|
+
)
|
|
490
|
+
empty = [c.header for c in draft.columns if c.action == MAP and not c.to]
|
|
491
|
+
if empty:
|
|
492
|
+
raise GuiError(
|
|
493
|
+
f"{draft.where}: choose where {empty[0]!r} goes, keep it as it is, or leave it out"
|
|
494
|
+
)
|
|
495
|
+
columns = {
|
|
496
|
+
c.header: out
|
|
497
|
+
for c in draft.columns
|
|
498
|
+
if c.action == MAP
|
|
499
|
+
and (out := id_column if c.to == ID_COLUMN else c.to) != c.header
|
|
500
|
+
}
|
|
501
|
+
outputs = [c.output for c in draft.columns if c.action != EXCLUDE]
|
|
502
|
+
for output, count in Counter(outputs).items():
|
|
503
|
+
if count > 1:
|
|
504
|
+
raise GuiError(f"{draft.where}: more than one column goes to {output!r}")
|
|
505
|
+
if columns:
|
|
506
|
+
source["columns"] = columns
|
|
507
|
+
exclude = [c.header for c in draft.columns if c.action == EXCLUDE]
|
|
508
|
+
if exclude:
|
|
509
|
+
source["exclude"] = exclude
|
|
510
|
+
lists = {
|
|
511
|
+
(id_column if c.output == ID_COLUMN else c.output): c.separator
|
|
512
|
+
for c in draft.columns
|
|
513
|
+
if c.action != EXCLUDE and c.separator
|
|
514
|
+
}
|
|
515
|
+
if lists:
|
|
516
|
+
source["lists"] = lists
|
|
517
|
+
constants = dict(draft.extra.get("set", {}))
|
|
518
|
+
if role.needs_field and FIELD_COLUMN not in outputs:
|
|
519
|
+
if not draft.field:
|
|
520
|
+
raise GuiError(
|
|
521
|
+
f"{draft.where}: say which column these values are for, or map a column to {FIELD_COLUMN!r}"
|
|
522
|
+
)
|
|
523
|
+
constants[FIELD_COLUMN] = draft.field
|
|
524
|
+
if constants:
|
|
525
|
+
source["set"] = constants
|
|
526
|
+
if draft.id_prefix and not role.merge:
|
|
527
|
+
source["id_prefix"] = draft.id_prefix
|
|
528
|
+
if draft.headings:
|
|
529
|
+
source["headings"] = _build_headings(draft)
|
|
530
|
+
return {
|
|
531
|
+
**source,
|
|
532
|
+
**{k: v for k, v in draft.extra.items() if k not in source and k != "set"},
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def build_mapping(form: Mapping[str, Any]) -> dict[str, Any]:
|
|
537
|
+
"""The JSON configuration a form describes, validated the way the importer validates it."""
|
|
538
|
+
if not isinstance(form, Mapping) or not isinstance(form.get("sources"), list):
|
|
539
|
+
raise BadRequest("expected {sources: [...]}")
|
|
540
|
+
id_column = _text(form.get("id_column"), "id_column") or ID_COLUMN
|
|
541
|
+
extra = form.get("extra", {})
|
|
542
|
+
xlsx_extra = form.get("xlsx_extra", {})
|
|
543
|
+
if not isinstance(extra, Mapping) or not isinstance(xlsx_extra, Mapping):
|
|
544
|
+
raise BadRequest("extra must be an object")
|
|
545
|
+
drafts = [_parse_source(item, i) for i, item in enumerate(form["sources"])]
|
|
546
|
+
chosen = [d for d in drafts if d.raw is not None or d.role is not None]
|
|
547
|
+
if not chosen:
|
|
548
|
+
raise GuiError(
|
|
549
|
+
"Choose at least one table or sheet to import, and say what it holds."
|
|
550
|
+
)
|
|
551
|
+
sources = [build_source(draft, id_column) for draft in chosen]
|
|
552
|
+
mapping = {
|
|
553
|
+
"id_column": id_column,
|
|
554
|
+
"traceability": True,
|
|
555
|
+
**{
|
|
556
|
+
k: v
|
|
557
|
+
for k, v in extra.items()
|
|
558
|
+
if k not in ("id_column", "traceability", "xlsx")
|
|
559
|
+
},
|
|
560
|
+
"xlsx": {
|
|
561
|
+
**{k: v for k, v in xlsx_extra.items() if k != "sources"},
|
|
562
|
+
"sources": sources,
|
|
563
|
+
},
|
|
564
|
+
}
|
|
565
|
+
try:
|
|
566
|
+
validate_xlsx_sources(sources)
|
|
567
|
+
except ConfigError as exc:
|
|
568
|
+
raise GuiError(str(exc)) from exc
|
|
569
|
+
return mapping
|
|
570
|
+
|
|
571
|
+
|
|
572
|
+
def form_from_mapping(mapping: object) -> tuple[dict[str, Any], list[str]]:
|
|
573
|
+
"""Best effort inverse of build_mapping. Anything the form cannot show is kept untouched and listed in the notes."""
|
|
574
|
+
if not isinstance(mapping, Mapping):
|
|
575
|
+
raise GuiError(
|
|
576
|
+
"That file is not a reqtable settings file: its top level must be a JSON object."
|
|
577
|
+
)
|
|
578
|
+
xlsx = mapping.get("xlsx")
|
|
579
|
+
sources = xlsx.get("sources") if isinstance(xlsx, Mapping) else None
|
|
580
|
+
if not isinstance(sources, list) or not sources:
|
|
581
|
+
raise GuiError(
|
|
582
|
+
"That settings file has no xlsx.sources, so there is no workbook mapping to edit."
|
|
583
|
+
)
|
|
584
|
+
notes: list[str] = []
|
|
585
|
+
extra = {
|
|
586
|
+
k: v
|
|
587
|
+
for k, v in mapping.items()
|
|
588
|
+
if k not in ("id_column", "traceability", "xlsx")
|
|
589
|
+
}
|
|
590
|
+
xlsx_extra = {k: v for k, v in xlsx.items() if k != "sources"} # type: ignore[union-attr]
|
|
591
|
+
for key in extra:
|
|
592
|
+
notes.append(f"Kept as it is, not editable here: {key}")
|
|
593
|
+
for key in xlsx_extra:
|
|
594
|
+
notes.append(f"Kept as it is, not editable here: xlsx.{key}")
|
|
595
|
+
if mapping.get("traceability") is False:
|
|
596
|
+
notes.append(
|
|
597
|
+
"The file turns traceability off. Sources with a record type need it, so it is switched on."
|
|
598
|
+
)
|
|
599
|
+
id_column = mapping.get("id_column") or ID_COLUMN
|
|
600
|
+
form_sources = [
|
|
601
|
+
_source_form(source, index, notes, id_column)
|
|
602
|
+
for index, source in enumerate(sources)
|
|
603
|
+
]
|
|
604
|
+
return {
|
|
605
|
+
"id_column": mapping.get("id_column") or ID_COLUMN,
|
|
606
|
+
"sources": form_sources,
|
|
607
|
+
"extra": extra,
|
|
608
|
+
"xlsx_extra": xlsx_extra,
|
|
609
|
+
}, notes
|
|
610
|
+
|
|
611
|
+
|
|
612
|
+
def _loadable_headings(headings: object) -> HeadingRows | None:
|
|
613
|
+
try:
|
|
614
|
+
validate_headings(headings, "headings")
|
|
615
|
+
except ConfigError:
|
|
616
|
+
return None
|
|
617
|
+
return HeadingRows.from_json(headings) # type: ignore[arg-type]
|
|
618
|
+
|
|
619
|
+
|
|
620
|
+
def _source_form(
|
|
621
|
+
source: object, index: int, notes: list[str], id_column: str
|
|
622
|
+
) -> dict[str, Any]:
|
|
623
|
+
if not isinstance(source, Mapping) or ("table" in source) == ("sheet" in source):
|
|
624
|
+
raise GuiError(
|
|
625
|
+
f"xlsx.sources[{index}] needs exactly one of 'table' or 'sheet'."
|
|
626
|
+
)
|
|
627
|
+
kind = "table" if "table" in source else "sheet"
|
|
628
|
+
name = str(source[kind])
|
|
629
|
+
constants = (
|
|
630
|
+
dict(source.get("set", {})) if isinstance(source.get("set"), Mapping) else {}
|
|
631
|
+
)
|
|
632
|
+
type_name = source.get("type") or constants.get("Type")
|
|
633
|
+
role = (
|
|
634
|
+
role_for_type(type_name)
|
|
635
|
+
if type_name != "Requirement"
|
|
636
|
+
else ROLES_BY_ID["requirements"]
|
|
637
|
+
)
|
|
638
|
+
if source.get("merge") is True:
|
|
639
|
+
role = ROLES_BY_ID["merge"] if not type_name else None
|
|
640
|
+
if role is None or ("type" in source and "Type" in constants):
|
|
641
|
+
notes.append(
|
|
642
|
+
f"{kind.capitalize()} {name!r} has a record type this form cannot edit, so it is kept exactly as it is."
|
|
643
|
+
)
|
|
644
|
+
return {"kind": kind, "name": name, "raw": dict(source)}
|
|
645
|
+
headings = _loadable_headings(source.get("headings")) if role.headings else None
|
|
646
|
+
handled = {
|
|
647
|
+
kind,
|
|
648
|
+
"header_row",
|
|
649
|
+
"columns",
|
|
650
|
+
"exclude",
|
|
651
|
+
"lists",
|
|
652
|
+
"id_prefix",
|
|
653
|
+
"set",
|
|
654
|
+
"type",
|
|
655
|
+
"merge",
|
|
656
|
+
*(("headings",) if headings else ()),
|
|
657
|
+
}
|
|
658
|
+
extra = {k: v for k, v in source.items() if k not in handled}
|
|
659
|
+
if type_name == "Requirement":
|
|
660
|
+
extra["type"] = "Requirement"
|
|
661
|
+
constants.pop("Type", None)
|
|
662
|
+
field = constants.pop(FIELD_COLUMN, "") if role.needs_field else ""
|
|
663
|
+
if constants:
|
|
664
|
+
extra["set"] = {**extra.get("set", {}), **constants}
|
|
665
|
+
for key in extra:
|
|
666
|
+
notes.append(
|
|
667
|
+
f"{kind.capitalize()} {name!r}: kept as it is, not editable here: {key}"
|
|
668
|
+
)
|
|
669
|
+
columns: dict[str, dict[str, Any]] = {}
|
|
670
|
+
for header, to in (source.get("columns") or {}).items():
|
|
671
|
+
columns[header] = {
|
|
672
|
+
"header": header,
|
|
673
|
+
"action": MAP,
|
|
674
|
+
"to": ID_COLUMN if to == id_column else to,
|
|
675
|
+
"separator": "",
|
|
676
|
+
}
|
|
677
|
+
for header in source.get("exclude") or []:
|
|
678
|
+
columns[header] = {
|
|
679
|
+
"header": header,
|
|
680
|
+
"action": EXCLUDE,
|
|
681
|
+
"to": "",
|
|
682
|
+
"separator": "",
|
|
683
|
+
}
|
|
684
|
+
for output, separator in (
|
|
685
|
+
(ID_COLUMN if k == id_column else k, v)
|
|
686
|
+
for k, v in (source.get("lists") or {}).items()
|
|
687
|
+
):
|
|
688
|
+
match = next(
|
|
689
|
+
(c for c in columns.values() if c["action"] == MAP and c["to"] == output),
|
|
690
|
+
None,
|
|
691
|
+
) or columns.setdefault(
|
|
692
|
+
output, {"header": output, "action": KEEP, "to": "", "separator": ""}
|
|
693
|
+
)
|
|
694
|
+
match["separator"] = separator
|
|
695
|
+
if (
|
|
696
|
+
role.needs_field
|
|
697
|
+
and not field
|
|
698
|
+
and FIELD_COLUMN
|
|
699
|
+
not in {
|
|
700
|
+
c["to"] if c["action"] == MAP else c["header"] for c in columns.values()
|
|
701
|
+
}
|
|
702
|
+
):
|
|
703
|
+
columns[FIELD_COLUMN] = {
|
|
704
|
+
"header": FIELD_COLUMN,
|
|
705
|
+
"action": KEEP,
|
|
706
|
+
"to": "",
|
|
707
|
+
"separator": "",
|
|
708
|
+
}
|
|
709
|
+
return {
|
|
710
|
+
"kind": kind,
|
|
711
|
+
"name": name,
|
|
712
|
+
"header_row": source.get("header_row"),
|
|
713
|
+
"role": role.id,
|
|
714
|
+
"field": field,
|
|
715
|
+
"id_prefix": source.get("id_prefix", ""),
|
|
716
|
+
"columns": list(columns.values()),
|
|
717
|
+
"extra": extra,
|
|
718
|
+
"headings": headings.to_json() if headings else None,
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
|
|
722
|
+
def _heading_summary(headings: Mapping[str, Any], stats: SourceStats) -> dict[str, Any]:
|
|
723
|
+
found = Counter(stats.categories)
|
|
724
|
+
return {
|
|
725
|
+
"removed": stats.headings_removed,
|
|
726
|
+
"categories": [
|
|
727
|
+
{"name": name, "count": count} for name, count in found.items() if name
|
|
728
|
+
],
|
|
729
|
+
"uncategorised": found.get("", 0),
|
|
730
|
+
"warning": None
|
|
731
|
+
if stats.headings_removed
|
|
732
|
+
else f"No row in {headings['column']!r} says {' or '.join(headings['values'])}.",
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
|
|
736
|
+
def preview_mapping(workbook: Path, mapping: Mapping[str, Any]) -> dict[str, Any]:
|
|
737
|
+
"""Run the importer on the draft once: rows per source, record types and warnings, or the error the CLI would give."""
|
|
738
|
+
sources = mapping["xlsx"]["sources"]
|
|
739
|
+
try:
|
|
740
|
+
imported = import_workbook(
|
|
741
|
+
workbook, XlsxSelection(), sources, mapping["id_column"], True, False
|
|
742
|
+
)
|
|
743
|
+
except (ReqtableError, OSError) as exc:
|
|
744
|
+
return {"error": str(exc)}
|
|
745
|
+
counts = []
|
|
746
|
+
for source, stats in zip(sources, imported.sources):
|
|
747
|
+
entry: dict[str, Any] = {"name": stats.name, "rows": stats.rows}
|
|
748
|
+
if "headings" in source:
|
|
749
|
+
entry["headings"] = _heading_summary(source["headings"], stats)
|
|
750
|
+
counts.append(entry)
|
|
751
|
+
rows = imported.block.rows
|
|
752
|
+
type_at = rows[0].index("Type") if "Type" in rows[0] else None
|
|
753
|
+
types = Counter(
|
|
754
|
+
(row[type_at].strip() if type_at is not None else "") or "Requirement"
|
|
755
|
+
for row in rows[1:]
|
|
756
|
+
)
|
|
757
|
+
return {
|
|
758
|
+
"sources": counts,
|
|
759
|
+
"types": dict(types),
|
|
760
|
+
"total": len(rows) - 1,
|
|
761
|
+
"warnings": list(imported.warnings),
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
|
|
765
|
+
def save_mapping(
|
|
766
|
+
workdir: Path, path: str, mapping: Mapping[str, Any], overwrite: bool
|
|
767
|
+
) -> dict[str, Any]:
|
|
768
|
+
if not path.strip():
|
|
769
|
+
raise GuiError("Choose where to save the mapping.")
|
|
770
|
+
target = workdir / path
|
|
771
|
+
if target.suffix.lower() != ".json":
|
|
772
|
+
raise GuiError("The mapping file name must end in .json.")
|
|
773
|
+
if target.exists() and not overwrite:
|
|
774
|
+
return {"exists": True, "path": str(target)}
|
|
775
|
+
atomic_write_text(str(target), json.dumps(mapping, indent=2) + "\n")
|
|
776
|
+
return {"saved": str(target)}
|
|
777
|
+
|
|
778
|
+
|
|
779
|
+
def load_mapping(workdir: Path, path: str) -> dict[str, Any]:
|
|
780
|
+
if not path.strip():
|
|
781
|
+
raise GuiError("Choose a mapping file to load.")
|
|
782
|
+
try:
|
|
783
|
+
mapping = json.loads((workdir / path).read_text(encoding="utf-8"))
|
|
784
|
+
except OSError as exc:
|
|
785
|
+
raise GuiError(f"Cannot read {path}: {exc.strerror or exc}") from exc
|
|
786
|
+
except ValueError as exc:
|
|
787
|
+
raise GuiError(f"{path} is not valid JSON: {exc}") from exc
|
|
788
|
+
form, notes = form_from_mapping(mapping)
|
|
789
|
+
return {"form": form, "notes": notes}
|