throughline-transform 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.
- throughline_transform/__init__.py +13 -0
- throughline_transform/blocks.py +156 -0
- throughline_transform/cli.py +155 -0
- throughline_transform/html.py +157 -0
- throughline_transform/markdown.py +82 -0
- throughline_transform/model.py +171 -0
- throughline_transform/notes.py +215 -0
- throughline_transform/office.py +334 -0
- throughline_transform/package.py +70 -0
- throughline_transform/project.py +108 -0
- throughline_transform/provenance.py +91 -0
- throughline_transform/shape.py +32 -0
- throughline_transform/tables.py +165 -0
- throughline_transform-0.1.0.dist-info/METADATA +108 -0
- throughline_transform-0.1.0.dist-info/RECORD +20 -0
- throughline_transform-0.1.0.dist-info/WHEEL +5 -0
- throughline_transform-0.1.0.dist-info/entry_points.txt +3 -0
- throughline_transform-0.1.0.dist-info/licenses/LICENSE +201 -0
- throughline_transform-0.1.0.dist-info/licenses/NOTICE +12 -0
- throughline_transform-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,334 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""xlsx and docx, written from their own specifications (SR-0010).
|
|
4
|
+
|
|
5
|
+
Both are zips of XML, and both are written here rather than depended on. What
|
|
6
|
+
is produced is deliberately plain — a sheet of cells, a document of headings
|
|
7
|
+
and paragraphs. Neither format is exercised beyond what a reader needs to sort
|
|
8
|
+
a column or read a requirement.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import re
|
|
14
|
+
|
|
15
|
+
from .blocks import Block
|
|
16
|
+
from .package import Entry, archive, utf8, xml
|
|
17
|
+
from .tables import Table
|
|
18
|
+
|
|
19
|
+
# --- xlsx ------------------------------------------------------------------
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def column_name(index: int) -> str:
|
|
23
|
+
"""Column names in a sheet — A, B, … Z, AA, AB, …"""
|
|
24
|
+
name = ""
|
|
25
|
+
n = index + 1
|
|
26
|
+
while n > 0:
|
|
27
|
+
remainder = (n - 1) % 26
|
|
28
|
+
name = chr(65 + remainder) + name
|
|
29
|
+
n = (n - remainder) // 26
|
|
30
|
+
return name
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _widths(table: Table) -> list[int]:
|
|
34
|
+
"""Column widths from the content, bounded at both ends."""
|
|
35
|
+
widths = []
|
|
36
|
+
for i, name in enumerate(table.columns):
|
|
37
|
+
longest = max([len(name), *[len(row[i]) if i < len(row) else 0 for row in table.rows]])
|
|
38
|
+
widths.append(min(60, max(10, longest + 2)))
|
|
39
|
+
return widths
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _sheet_xml(table: Table) -> str:
|
|
43
|
+
def row(cells: list[str], index: int) -> str:
|
|
44
|
+
style = 1 if index == 0 else 2
|
|
45
|
+
out = [f'<row r="{index + 1}">']
|
|
46
|
+
for column, value in enumerate(cells):
|
|
47
|
+
out.append(
|
|
48
|
+
f'<c r="{column_name(column)}{index + 1}" t="inlineStr" s="{style}">'
|
|
49
|
+
f'<is><t xml:space="preserve">{xml(value)}</t></is></c>'
|
|
50
|
+
)
|
|
51
|
+
out.append("</row>")
|
|
52
|
+
return "".join(out)
|
|
53
|
+
|
|
54
|
+
last = f"{column_name(max(0, len(table.columns) - 1))}{len(table.rows) + 1}"
|
|
55
|
+
cols = "".join(
|
|
56
|
+
f'<col min="{i + 1}" max="{i + 1}" width="{w}" customWidth="1"/>' for i, w in enumerate(_widths(table))
|
|
57
|
+
)
|
|
58
|
+
data = "".join(row(cells, i) for i, cells in enumerate([table.columns, *table.rows]))
|
|
59
|
+
return (
|
|
60
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
61
|
+
'<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
|
|
62
|
+
# The header row is frozen: a table of requirements is longer than a
|
|
63
|
+
# screen, and a column nobody can name is not sortable.
|
|
64
|
+
'<sheetViews><sheetView workbookViewId="0">'
|
|
65
|
+
'<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
|
|
66
|
+
"</sheetView></sheetViews>"
|
|
67
|
+
f"<cols>{cols}</cols>"
|
|
68
|
+
f"<sheetData>{data}</sheetData>"
|
|
69
|
+
# Read-only, without a password (SR-0007): a guard against a stray
|
|
70
|
+
# keystroke and a statement that this is a record. Sorting, filtering
|
|
71
|
+
# and selecting stay permitted. In this element a 0 means "allowed".
|
|
72
|
+
'<sheetProtection sheet="1" objects="1" scenarios="1" '
|
|
73
|
+
'selectLockedCells="0" selectUnlockedCells="0" sort="0" autoFilter="0"/>'
|
|
74
|
+
f'<autoFilter ref="A1:{last}"/>'
|
|
75
|
+
"</worksheet>"
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def sheet_name(name: str, index: int) -> str:
|
|
80
|
+
"""A sheet name Excel will accept: 31 characters, and none of \\/?*[]:"""
|
|
81
|
+
clean = re.sub(r"[\\/?*\[\]:]", " ", name).strip()[:31]
|
|
82
|
+
return clean or f"Sheet{index + 1}"
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def to_xlsx(tables: list[Table]) -> bytes:
|
|
86
|
+
names = [sheet_name(t.name, i) for i, t in enumerate(tables)]
|
|
87
|
+
n = len(tables)
|
|
88
|
+
entries: list[Entry] = [
|
|
89
|
+
(
|
|
90
|
+
"[Content_Types].xml",
|
|
91
|
+
utf8(
|
|
92
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
93
|
+
'<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
|
|
94
|
+
'<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
|
|
95
|
+
'<Default Extension="xml" ContentType="application/xml"/>'
|
|
96
|
+
'<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>'
|
|
97
|
+
'<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>'
|
|
98
|
+
+ "".join(
|
|
99
|
+
f'<Override PartName="/xl/worksheets/sheet{i + 1}.xml" '
|
|
100
|
+
'ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>'
|
|
101
|
+
for i in range(n)
|
|
102
|
+
)
|
|
103
|
+
+ "</Types>"
|
|
104
|
+
),
|
|
105
|
+
),
|
|
106
|
+
(
|
|
107
|
+
"_rels/.rels",
|
|
108
|
+
utf8(
|
|
109
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
110
|
+
'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
|
|
111
|
+
'<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>'
|
|
112
|
+
"</Relationships>"
|
|
113
|
+
),
|
|
114
|
+
),
|
|
115
|
+
(
|
|
116
|
+
"xl/workbook.xml",
|
|
117
|
+
utf8(
|
|
118
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
119
|
+
'<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
|
|
120
|
+
'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">'
|
|
121
|
+
# Opened read-only by recommendation, structure locked so no
|
|
122
|
+
# sheet is added, removed or renamed (SR-0007).
|
|
123
|
+
'<fileSharing readOnlyRecommended="1"/>'
|
|
124
|
+
'<workbookProtection lockStructure="1"/>'
|
|
125
|
+
"<sheets>"
|
|
126
|
+
+ "".join(
|
|
127
|
+
f'<sheet name="{xml(name)}" sheetId="{i + 1}" r:id="rId{i + 1}"/>' for i, name in enumerate(names)
|
|
128
|
+
)
|
|
129
|
+
+ "</sheets></workbook>"
|
|
130
|
+
),
|
|
131
|
+
),
|
|
132
|
+
(
|
|
133
|
+
"xl/_rels/workbook.xml.rels",
|
|
134
|
+
utf8(
|
|
135
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
136
|
+
'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
|
|
137
|
+
+ "".join(
|
|
138
|
+
f'<Relationship Id="rId{i + 1}" '
|
|
139
|
+
'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" '
|
|
140
|
+
f'Target="worksheets/sheet{i + 1}.xml"/>'
|
|
141
|
+
for i in range(n)
|
|
142
|
+
)
|
|
143
|
+
+ f'<Relationship Id="rId{n + 1}" '
|
|
144
|
+
'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" '
|
|
145
|
+
'Target="styles.xml"/>'
|
|
146
|
+
"</Relationships>"
|
|
147
|
+
),
|
|
148
|
+
),
|
|
149
|
+
(
|
|
150
|
+
"xl/styles.xml",
|
|
151
|
+
utf8(
|
|
152
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
153
|
+
'<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
|
|
154
|
+
'<fonts count="2"><font><sz val="11"/><name val="Calibri"/></font>'
|
|
155
|
+
'<font><b/><sz val="11"/><name val="Calibri"/></font></fonts>'
|
|
156
|
+
# A fill and a border are required even when nothing uses them —
|
|
157
|
+
# Excel indexes into these tables and refuses a file whose
|
|
158
|
+
# counts do not line up.
|
|
159
|
+
'<fills count="2"><fill><patternFill patternType="none"/></fill>'
|
|
160
|
+
'<fill><patternFill patternType="gray125"/></fill></fills>'
|
|
161
|
+
'<borders count="1"><border/></borders>'
|
|
162
|
+
'<cellStyleXfs count="1"><xf/></cellStyleXfs>'
|
|
163
|
+
'<cellXfs count="3">'
|
|
164
|
+
'<xf xfId="0"/>'
|
|
165
|
+
'<xf xfId="0" fontId="1" applyFont="1" applyAlignment="1">'
|
|
166
|
+
'<alignment vertical="top" wrapText="1"/></xf>'
|
|
167
|
+
'<xf xfId="0" applyAlignment="1">'
|
|
168
|
+
'<alignment vertical="top" wrapText="1"/></xf>'
|
|
169
|
+
"</cellXfs>"
|
|
170
|
+
'<cellStyles count="1">'
|
|
171
|
+
'<cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>'
|
|
172
|
+
"</styleSheet>"
|
|
173
|
+
),
|
|
174
|
+
),
|
|
175
|
+
*[(f"xl/worksheets/sheet{i + 1}.xml", utf8(_sheet_xml(t))) for i, t in enumerate(tables)],
|
|
176
|
+
]
|
|
177
|
+
return archive(entries)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
# --- docx ------------------------------------------------------------------
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _run(text: str, bold: bool = False) -> str:
|
|
184
|
+
lines = "".join(
|
|
185
|
+
("" if i == 0 else "<w:br/>") + f'<w:t xml:space="preserve">{xml(line)}</w:t>'
|
|
186
|
+
for i, line in enumerate(text.split("\n"))
|
|
187
|
+
)
|
|
188
|
+
return f"<w:r>{'<w:rPr><w:b/></w:rPr>' if bold else ''}{lines}</w:r>"
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _table_xml(header: list[str], rows: list[list[str]]) -> str:
|
|
192
|
+
def side(edge: str) -> str:
|
|
193
|
+
return f'<w:{edge} w:val="single" w:sz="4" w:space="0" w:color="auto"/>'
|
|
194
|
+
|
|
195
|
+
def tc(text: str, bold: bool) -> str:
|
|
196
|
+
return (
|
|
197
|
+
'<w:tc><w:tcPr><w:tcW w:w="0" w:type="auto"/></w:tcPr>'
|
|
198
|
+
f"<w:p>{_run(text, bold)}</w:p></w:tc>"
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
def tr(cells: list[str], head: bool) -> str:
|
|
202
|
+
return (
|
|
203
|
+
f"<w:tr>{'<w:trPr><w:tblHeader/></w:trPr>' if head else ''}"
|
|
204
|
+
+ "".join(tc(c, head) for c in cells)
|
|
205
|
+
+ "</w:tr>"
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
width = 9360 // max(1, len(header))
|
|
209
|
+
return (
|
|
210
|
+
'<w:tbl><w:tblPr><w:tblW w:w="5000" w:type="pct"/><w:tblBorders>'
|
|
211
|
+
+ "".join(side(e) for e in ["top", "left", "bottom", "right", "insideH", "insideV"])
|
|
212
|
+
+ "</w:tblBorders></w:tblPr>"
|
|
213
|
+
# The grid is required, not decorative: a table without it is one Word
|
|
214
|
+
# will usually render and a conforming reader refuses outright.
|
|
215
|
+
"<w:tblGrid>"
|
|
216
|
+
+ "".join(f'<w:gridCol w:w="{width}"/>' for _ in header)
|
|
217
|
+
+ "</w:tblGrid>"
|
|
218
|
+
+ tr(header, True)
|
|
219
|
+
+ "".join(tr(r, False) for r in rows)
|
|
220
|
+
+ "</w:tbl>"
|
|
221
|
+
)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
def _paragraph(block: Block) -> str:
|
|
225
|
+
if block.table:
|
|
226
|
+
return _table_xml(block.table["header"], block.table["rows"])
|
|
227
|
+
if block.heading:
|
|
228
|
+
style = f'<w:pStyle w:val="Heading{min(block.heading, 4)}"/>'
|
|
229
|
+
elif block.quote:
|
|
230
|
+
style = '<w:pStyle w:val="Quote"/>'
|
|
231
|
+
elif block.small:
|
|
232
|
+
style = '<w:pStyle w:val="Attrs"/>'
|
|
233
|
+
else:
|
|
234
|
+
style = ""
|
|
235
|
+
text = f"<w:p>{f'<w:pPr>{style}</w:pPr>' if style else ''}{_run(block.text)}</w:p>"
|
|
236
|
+
beneath = (
|
|
237
|
+
f"{block.item['type'].replace('_', ' ')} · {block.item['status']}" if block.item else block.subtitle
|
|
238
|
+
)
|
|
239
|
+
if beneath:
|
|
240
|
+
text += f'<w:p><w:pPr><w:pStyle w:val="Attrs"/></w:pPr>{_run(beneath)}</w:p>'
|
|
241
|
+
return text
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def _contents_xml() -> str:
|
|
245
|
+
"""A table of contents Word fills in when asked (SR-0008)."""
|
|
246
|
+
return (
|
|
247
|
+
'<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr>' + _run("Contents") + "</w:p>"
|
|
248
|
+
'<w:p><w:fldSimple w:instr="TOC \\o "1-4" \\h \\z \\u">'
|
|
249
|
+
+ _run("Right-click here and choose Update Field to fill in the contents.")
|
|
250
|
+
+ "</w:fldSimple></w:p>"
|
|
251
|
+
'<w:p><w:r><w:br w:type="page"/></w:r></w:p>'
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
_STYLES = (
|
|
256
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
257
|
+
'<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
|
|
258
|
+
'<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>'
|
|
259
|
+
'<w:sz w:val="22"/></w:rPr></w:rPrDefault>'
|
|
260
|
+
'<w:pPrDefault><w:pPr><w:spacing w:after="120"/></w:pPr></w:pPrDefault></w:docDefaults>'
|
|
261
|
+
+ "".join(
|
|
262
|
+
f'<w:style w:type="paragraph" w:styleId="Heading{level}">'
|
|
263
|
+
f'<w:name w:val="heading {level}"/><w:basedOn w:val="Normal"/>'
|
|
264
|
+
f'<w:pPr><w:outlineLvl w:val="{level - 1}"/><w:spacing w:before="240"/></w:pPr>'
|
|
265
|
+
f'<w:rPr><w:b/><w:sz w:val="{36 - level * 4}"/></w:rPr></w:style>'
|
|
266
|
+
for level in (1, 2, 3, 4)
|
|
267
|
+
)
|
|
268
|
+
+ '<w:style w:type="paragraph" w:styleId="Quote"><w:name w:val="Quote"/>'
|
|
269
|
+
'<w:pPr><w:ind w:left="720"/></w:pPr><w:rPr><w:i/></w:rPr></w:style>'
|
|
270
|
+
'<w:style w:type="paragraph" w:styleId="Attrs"><w:name w:val="Attrs"/>'
|
|
271
|
+
'<w:basedOn w:val="Normal"/><w:rPr><w:sz w:val="18"/><w:color w:val="555555"/></w:rPr></w:style>'
|
|
272
|
+
'<w:style w:type="paragraph" w:default="1" w:styleId="Normal">'
|
|
273
|
+
'<w:name w:val="Normal"/></w:style>'
|
|
274
|
+
"</w:styles>"
|
|
275
|
+
)
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def to_docx(blocks: list[Block]) -> bytes:
|
|
279
|
+
first_section = next((i for i, b in enumerate(blocks) if b.heading == 2), -1)
|
|
280
|
+
body: list[str] = []
|
|
281
|
+
for i, block in enumerate(blocks):
|
|
282
|
+
if i == first_section:
|
|
283
|
+
body.append(_contents_xml())
|
|
284
|
+
elif block.heading == 2:
|
|
285
|
+
body.append('<w:p><w:r><w:br w:type="page"/></w:r></w:p>')
|
|
286
|
+
body.append(_paragraph(block))
|
|
287
|
+
# Word joins two tables that touch into one.
|
|
288
|
+
if block.table and i + 1 < len(blocks) and blocks[i + 1].table:
|
|
289
|
+
body.append("<w:p/>")
|
|
290
|
+
document = (
|
|
291
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
292
|
+
'<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
|
|
293
|
+
"<w:body>" + "".join(body) +
|
|
294
|
+
# A4, with a margin on every side.
|
|
295
|
+
'<w:sectPr><w:pgSz w:w="11906" w:h="16838"/>'
|
|
296
|
+
'<w:pgMar w:top="1418" w:right="1134" w:bottom="1418" w:left="1134" w:header="709" w:footer="709"/>'
|
|
297
|
+
"</w:sectPr>"
|
|
298
|
+
"</w:body></w:document>"
|
|
299
|
+
)
|
|
300
|
+
entries: list[Entry] = [
|
|
301
|
+
(
|
|
302
|
+
"[Content_Types].xml",
|
|
303
|
+
utf8(
|
|
304
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
305
|
+
'<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
|
|
306
|
+
'<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
|
|
307
|
+
'<Default Extension="xml" ContentType="application/xml"/>'
|
|
308
|
+
'<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
|
|
309
|
+
'<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>'
|
|
310
|
+
"</Types>"
|
|
311
|
+
),
|
|
312
|
+
),
|
|
313
|
+
(
|
|
314
|
+
"_rels/.rels",
|
|
315
|
+
utf8(
|
|
316
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
317
|
+
'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
|
|
318
|
+
'<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>'
|
|
319
|
+
"</Relationships>"
|
|
320
|
+
),
|
|
321
|
+
),
|
|
322
|
+
(
|
|
323
|
+
"word/_rels/document.xml.rels",
|
|
324
|
+
utf8(
|
|
325
|
+
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
|
|
326
|
+
'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
|
|
327
|
+
'<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>'
|
|
328
|
+
"</Relationships>"
|
|
329
|
+
),
|
|
330
|
+
),
|
|
331
|
+
("word/styles.xml", utf8(_STYLES)),
|
|
332
|
+
("word/document.xml", utf8(document)),
|
|
333
|
+
]
|
|
334
|
+
return archive(entries)
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""Containers (SR-0011): a zip, or the same files written into a folder.
|
|
4
|
+
|
|
5
|
+
Every timestamp is the same fixed value, so the same graph exported twice
|
|
6
|
+
produces identical bytes. An output that differs only in when it was taken
|
|
7
|
+
cannot be compared with the one before it, and comparing them is a thing
|
|
8
|
+
people do with a specification.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import io
|
|
14
|
+
import re
|
|
15
|
+
import zipfile
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
|
|
18
|
+
Entry = tuple[str, bytes]
|
|
19
|
+
|
|
20
|
+
#: 1980-01-01 00:00:00 — the epoch of the zip format itself.
|
|
21
|
+
_EPOCH = (1980, 1, 1, 0, 0, 0)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def archive(entries: list[Entry]) -> bytes:
|
|
25
|
+
buffer = io.BytesIO()
|
|
26
|
+
with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as zf:
|
|
27
|
+
for path, data in entries:
|
|
28
|
+
info = zipfile.ZipInfo(path, date_time=_EPOCH)
|
|
29
|
+
info.compress_type = zipfile.ZIP_DEFLATED
|
|
30
|
+
# Regular file, rw-r--r--, so the member unpacks with sane permissions.
|
|
31
|
+
info.external_attr = 0o100644 << 16
|
|
32
|
+
zf.writestr(info, data)
|
|
33
|
+
return buffer.getvalue()
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def unpack(entries: list[Entry], folder: Path) -> list[Path]:
|
|
37
|
+
"""Write the entries beneath ``folder``. Refuses a path that would escape it."""
|
|
38
|
+
folder = folder.resolve()
|
|
39
|
+
written: list[Path] = []
|
|
40
|
+
for path, data in entries:
|
|
41
|
+
target = (folder / path).resolve()
|
|
42
|
+
if folder != target and folder not in target.parents:
|
|
43
|
+
raise ValueError(f"refusing to write outside {folder}: {path}")
|
|
44
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
45
|
+
target.write_bytes(data)
|
|
46
|
+
written.append(target)
|
|
47
|
+
return written
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
_CONTROL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def xml(text: str) -> str:
|
|
54
|
+
"""XML text escaping, needed by every part of both Office formats.
|
|
55
|
+
|
|
56
|
+
A control character is not legal in XML 1.0 at all, and an item's text is
|
|
57
|
+
arbitrary content from a repository — so they go rather than producing a
|
|
58
|
+
file the reader refuses to open. Tab, newline and carriage return stay.
|
|
59
|
+
"""
|
|
60
|
+
text = (
|
|
61
|
+
text.replace("&", "&")
|
|
62
|
+
.replace("<", "<")
|
|
63
|
+
.replace(">", ">")
|
|
64
|
+
.replace('"', """)
|
|
65
|
+
)
|
|
66
|
+
return _CONTROL.sub("", text)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def utf8(text: str) -> bytes:
|
|
70
|
+
return text.encode("utf-8")
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""Reaching the tool (SR-0001, SR-0002).
|
|
4
|
+
|
|
5
|
+
Two commands are asked of it and nothing else: ``dump`` for the structure and
|
|
6
|
+
``docs`` for the prose. Which entry point answers is decided by the graph, not
|
|
7
|
+
the caller — a graph that declares sources is composed, and the core command
|
|
8
|
+
run over it would exit cleanly and drop every borrowed clause's own reference
|
|
9
|
+
number, which is exactly the identifier a conformance document exists to carry.
|
|
10
|
+
|
|
11
|
+
The tool is reached as a command, not imported. Its command line is the surface
|
|
12
|
+
it publishes; its modules move between releases.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import json
|
|
18
|
+
import os
|
|
19
|
+
import shutil
|
|
20
|
+
import subprocess
|
|
21
|
+
import sys
|
|
22
|
+
import tempfile
|
|
23
|
+
import tomllib
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from .model import Graph, index
|
|
28
|
+
|
|
29
|
+
CONFIG = "throughline.toml"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class TransformError(Exception):
|
|
33
|
+
"""A failure the user can act on, reported in one line on stderr."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def find_graph(start: str | os.PathLike[str] | None) -> Path:
|
|
37
|
+
"""The directory holding ``throughline.toml``.
|
|
38
|
+
|
|
39
|
+
With ``-C``, that directory must be a graph — a wrong path is refused rather
|
|
40
|
+
than searched around, because an export of the wrong graph reads exactly
|
|
41
|
+
like the right one. Without it, the walk upward from the working directory
|
|
42
|
+
is the one ``tl`` itself makes.
|
|
43
|
+
"""
|
|
44
|
+
if start is not None:
|
|
45
|
+
root = Path(start).resolve()
|
|
46
|
+
if not (root / CONFIG).is_file():
|
|
47
|
+
raise TransformError(f"{root} holds no {CONFIG}")
|
|
48
|
+
return root
|
|
49
|
+
here = Path.cwd().resolve()
|
|
50
|
+
for candidate in (here, *here.parents):
|
|
51
|
+
if (candidate / CONFIG).is_file():
|
|
52
|
+
return candidate
|
|
53
|
+
raise TransformError(f"no {CONFIG} here or above; pass -C <dir>")
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def is_composed(root: Path) -> bool:
|
|
57
|
+
"""Whether the graph declares sources, and so is the composer's to read."""
|
|
58
|
+
with open(root / CONFIG, "rb") as fh:
|
|
59
|
+
config = tomllib.load(fh)
|
|
60
|
+
return bool(config.get("sources"))
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def executable(name: str) -> str:
|
|
64
|
+
"""Where the tool is.
|
|
65
|
+
|
|
66
|
+
Beside this interpreter first, because that is the tool this package was
|
|
67
|
+
installed with and the one its floors were proven against; then the path.
|
|
68
|
+
"""
|
|
69
|
+
beside = Path(sys.executable).parent / name
|
|
70
|
+
if beside.is_file() and os.access(beside, os.X_OK):
|
|
71
|
+
return str(beside)
|
|
72
|
+
found = shutil.which(name)
|
|
73
|
+
if found:
|
|
74
|
+
return found
|
|
75
|
+
raise TransformError(f"{name} is not installed beside this tool nor on the path")
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def run(root: Path, args: list[str], composed: bool) -> str:
|
|
79
|
+
"""Run the tool over the graph and hand back what it wrote."""
|
|
80
|
+
command = [executable("tl-compose" if composed else "tl"), "-C", str(root), *args]
|
|
81
|
+
try:
|
|
82
|
+
done = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
|
|
83
|
+
except OSError as exc: # pragma: no cover - the executable check above covers the common case
|
|
84
|
+
raise TransformError(f"could not run {command[0]}: {exc}") from exc
|
|
85
|
+
if done.returncode != 0:
|
|
86
|
+
detail = done.stderr.strip() or done.stdout.strip() or f"exit {done.returncode}"
|
|
87
|
+
raise TransformError(f"{Path(command[0]).name} {args[0]} failed — {detail}")
|
|
88
|
+
return done.stdout
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def load(root: Path) -> Graph:
|
|
92
|
+
"""The graph, as the tool exports it."""
|
|
93
|
+
composed = is_composed(root)
|
|
94
|
+
raw: dict[str, Any] = json.loads(run(root, ["dump"], composed))
|
|
95
|
+
return index(raw, composed)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def docs(root: Path, document: str, composed: bool) -> str:
|
|
99
|
+
"""Hand the tool a document of directives and read back what it wrote.
|
|
100
|
+
|
|
101
|
+
Written outside the graph, so an export can never be mistaken for a change
|
|
102
|
+
to it and never reaches a commit.
|
|
103
|
+
"""
|
|
104
|
+
with tempfile.TemporaryDirectory(prefix="tl-transform-") as scratch:
|
|
105
|
+
path = Path(scratch) / "document.md"
|
|
106
|
+
path.write_text(document, encoding="utf-8")
|
|
107
|
+
run(root, ["docs", str(path)], composed)
|
|
108
|
+
return path.read_text(encoding="utf-8")
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""What an output was taken from (SR-0004).
|
|
4
|
+
|
|
5
|
+
An output outlives the working tree that made it, and the first question anyone
|
|
6
|
+
asks of one is what it was true of. A commit answers that when there is one. A
|
|
7
|
+
tree with uncommitted changes, or none under version control at all, is still a
|
|
8
|
+
graph worth exporting — the output has to say which it was, because a reader
|
|
9
|
+
holding the file cannot tell.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
import subprocess
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
|
|
19
|
+
CLEAN = "clean"
|
|
20
|
+
DIRTY = "uncommitted changes"
|
|
21
|
+
UNTRACKED = "not under version control"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class Provenance:
|
|
26
|
+
repository: str
|
|
27
|
+
ref: str
|
|
28
|
+
commit: str
|
|
29
|
+
tree: str
|
|
30
|
+
tool: str
|
|
31
|
+
|
|
32
|
+
def lines(self) -> list[str]:
|
|
33
|
+
return [
|
|
34
|
+
f"Repository: {self.repository}",
|
|
35
|
+
f"Ref: {self.ref or 'none'}",
|
|
36
|
+
f"Commit: {self.commit or 'none'}",
|
|
37
|
+
f"Working tree: {self.tree}",
|
|
38
|
+
f"Produced by: {self.tool}",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
@property
|
|
42
|
+
def stem(self) -> str:
|
|
43
|
+
"""A file name stem: the repository and the ref, made safe for a file name."""
|
|
44
|
+
base = self.repository.replace("/", "-")
|
|
45
|
+
if self.ref:
|
|
46
|
+
base = f"{base}-{self.ref}"
|
|
47
|
+
return re.sub(r"[^\w.-]", "-", base).strip("-") or "graph"
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _git(root: Path, *args: str) -> str | None:
|
|
51
|
+
try:
|
|
52
|
+
done = subprocess.run(
|
|
53
|
+
["git", "-C", str(root), *args], capture_output=True, text=True, encoding="utf-8"
|
|
54
|
+
)
|
|
55
|
+
except OSError:
|
|
56
|
+
return None
|
|
57
|
+
return done.stdout.strip() if done.returncode == 0 else None
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
_REMOTE = re.compile(r"(?:[:/])([^/:]+/[^/]+?)(?:\.git)?/?$")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _repository_name(remote: str | None, toplevel: Path) -> str:
|
|
64
|
+
if remote:
|
|
65
|
+
match = _REMOTE.search(remote)
|
|
66
|
+
if match:
|
|
67
|
+
return match.group(1)
|
|
68
|
+
return toplevel.name
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def provenance_of(root: Path, tool: str) -> Provenance:
|
|
72
|
+
"""Read the working tree's state for the graph at ``root``.
|
|
73
|
+
|
|
74
|
+
Cleanliness is judged over the graph's directory, not the whole repository:
|
|
75
|
+
an output is of the graph, and a change elsewhere in the repository does not
|
|
76
|
+
alter what it says.
|
|
77
|
+
"""
|
|
78
|
+
toplevel = _git(root, "rev-parse", "--show-toplevel")
|
|
79
|
+
if not toplevel:
|
|
80
|
+
return Provenance(repository=root.name, ref="", commit="", tree=UNTRACKED, tool=tool)
|
|
81
|
+
top = Path(toplevel)
|
|
82
|
+
repository = _repository_name(_git(root, "remote", "get-url", "origin"), top)
|
|
83
|
+
ref = _git(root, "rev-parse", "--abbrev-ref", "HEAD") or ""
|
|
84
|
+
if ref == "HEAD":
|
|
85
|
+
ref = "detached"
|
|
86
|
+
commit = _git(root, "rev-parse", "HEAD") or ""
|
|
87
|
+
status = _git(root, "status", "--porcelain", "--", str(root))
|
|
88
|
+
tree = DIRTY if status else CLEAN
|
|
89
|
+
if not commit:
|
|
90
|
+
tree = DIRTY
|
|
91
|
+
return Provenance(repository=repository, ref=ref, commit=commit, tree=tree, tool=tool)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""The shape of what the tool writes, read in one place (SR-0003).
|
|
4
|
+
|
|
5
|
+
``tl docs`` renders an item as a bold line, its words as a quotation, its
|
|
6
|
+
rationale, one line per link type and a line of attributes (throughline
|
|
7
|
+
SR-0111, SR-0113, SR-0187). Nothing here is restated — these patterns are read,
|
|
8
|
+
never written. If the tool changes the line, every consumer of this module
|
|
9
|
+
falls back the same way rather than each guessing differently.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
|
|
16
|
+
#: The line the tool writes to open an item in a catalogue or a mirrored source:
|
|
17
|
+
#: ``**UID — title** — `type`, status `status```, where a borrowed clause's UID is
|
|
18
|
+
#: namespace-qualified and may carry its reference in brackets.
|
|
19
|
+
ITEM_LINE = re.compile(
|
|
20
|
+
r"^\*\*((?:[a-z][a-z0-9_-]*:)?[A-Z][A-Z0-9]*-\d+)(?: \((.*?)\))? — (.+?)\*\* — "
|
|
21
|
+
r"`([^`]+)`, status `([^`]+)`$"
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
#: The tool's attribute line: ``**name**: value · **name**: value``.
|
|
25
|
+
ATTRS_LINE = re.compile(r"^\*\*[a-z_]+\*\*: .*$")
|
|
26
|
+
|
|
27
|
+
#: An identifier as the tool writes one anywhere in prose: a local UID, or a
|
|
28
|
+
#: namespace-qualified one naming a clause of an adopted source.
|
|
29
|
+
IDENTIFIER = re.compile(r"(?:[a-z][a-z0-9_-]*:)?[A-Z][A-Z0-9]*-\d+")
|
|
30
|
+
|
|
31
|
+
#: A region marker, opening or closing.
|
|
32
|
+
MARKER = re.compile(r"^\s*<!--\s*tl:(?:[a-z.]+|end)\b.*-->\s*$", re.IGNORECASE)
|