throughline-transform 0.4.0__tar.gz → 0.5.0__tar.gz
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-0.4.0 → throughline_transform-0.5.0}/LICENSE +1 -1
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/NOTICE +3 -3
- {throughline_transform-0.4.0/src/throughline_transform.egg-info → throughline_transform-0.5.0}/PKG-INFO +11 -5
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/README.md +10 -4
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/pyproject.toml +6 -6
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/cli.py +43 -11
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/markdown.py +20 -5
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/model.py +22 -2
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/provenance.py +16 -2
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/tables.py +6 -1
- {throughline_transform-0.4.0 → throughline_transform-0.5.0/src/throughline_transform.egg-info}/PKG-INFO +11 -5
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/SOURCES.txt +1 -0
- throughline_transform-0.5.0/tests/test_only.py +150 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/tests/test_outputs.py +9 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/MANIFEST.in +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/setup.cfg +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/blocks.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/notes.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/progress.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/project.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/requires.txt +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/tests/conftest.py +0 -0
- {throughline_transform-0.4.0 → throughline_transform-0.5.0}/tests/test_surface.py +0 -0
|
@@ -186,7 +186,7 @@
|
|
|
186
186
|
same "printed page" as the copyright notice for easier
|
|
187
187
|
identification within third-party archives.
|
|
188
188
|
|
|
189
|
-
Copyright 2026 The throughline-
|
|
189
|
+
Copyright 2026 The throughline-transform authors
|
|
190
190
|
|
|
191
191
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
192
|
you may not use this file except in compliance with the License.
|
|
@@ -7,6 +7,6 @@ This product includes software developed by Henry J Grech-Cini.
|
|
|
7
7
|
Licensed under the Apache License, Version 2.0. See the LICENSE file for the
|
|
8
8
|
full terms.
|
|
9
9
|
|
|
10
|
-
throughline-transform is a
|
|
11
|
-
throughline
|
|
12
|
-
|
|
10
|
+
throughline-transform is a command-line companion for throughline (the `tl`
|
|
11
|
+
CLI). It builds on throughline's published command line; no third-party source
|
|
12
|
+
code was copied.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI.
|
|
5
5
|
Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -71,8 +71,7 @@ Office formats, which are written from their own specifications.
|
|
|
71
71
|
|
|
72
72
|
Every graph is read through `tl`, which composes a graph that declares
|
|
73
73
|
`[[sources]]` itself, so a borrowed clause is written with the reference number
|
|
74
|
-
a conformance document exists to carry
|
|
75
|
-
same program.
|
|
74
|
+
a conformance document exists to carry.
|
|
76
75
|
The tool is found beside this package's interpreter first and on the path
|
|
77
76
|
second, and is run as a command — its command line is the surface it publishes.
|
|
78
77
|
|
|
@@ -95,6 +94,13 @@ knows them without git — the editor holds them from its clone — states them
|
|
|
95
94
|
`--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
|
|
96
95
|
is then not consulted.
|
|
97
96
|
|
|
97
|
+
`--only UID[,UID…]`, given once or more, narrows any format to the items it
|
|
98
|
+
names: the catalogue, table and matrices hold only those, the tables only their
|
|
99
|
+
rows and the links between them, the notes only their notes, and the clauses
|
|
100
|
+
mirrored are only the ones they cite. The output then says `Items: n of N`,
|
|
101
|
+
because a partial document read as a whole one misleads. An identifier the
|
|
102
|
+
graph does not hold is a usage error (exit 2), and nothing is written.
|
|
103
|
+
|
|
98
104
|
A quick run is silent. When a step — reading the graph, asking the tool to
|
|
99
105
|
write the document, writing the file — has run for a second, one line on
|
|
100
106
|
stderr says which, because a composed graph fetching its sources for the first
|
|
@@ -117,8 +123,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
|
|
|
117
123
|
resolved rather than asserted.
|
|
118
124
|
|
|
119
125
|
```bash
|
|
120
|
-
tl
|
|
121
|
-
tl
|
|
126
|
+
tl -C idd check --strict # the grounding gate
|
|
127
|
+
tl -C idd docs --check # idd/docs/spec.md must match the graph
|
|
122
128
|
tl-transform html -C idd # and the tool over its own graph
|
|
123
129
|
```
|
|
124
130
|
|
|
@@ -43,8 +43,7 @@ Office formats, which are written from their own specifications.
|
|
|
43
43
|
|
|
44
44
|
Every graph is read through `tl`, which composes a graph that declares
|
|
45
45
|
`[[sources]]` itself, so a borrowed clause is written with the reference number
|
|
46
|
-
a conformance document exists to carry
|
|
47
|
-
same program.
|
|
46
|
+
a conformance document exists to carry.
|
|
48
47
|
The tool is found beside this package's interpreter first and on the path
|
|
49
48
|
second, and is run as a command — its command line is the surface it publishes.
|
|
50
49
|
|
|
@@ -67,6 +66,13 @@ knows them without git — the editor holds them from its clone — states them
|
|
|
67
66
|
`--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
|
|
68
67
|
is then not consulted.
|
|
69
68
|
|
|
69
|
+
`--only UID[,UID…]`, given once or more, narrows any format to the items it
|
|
70
|
+
names: the catalogue, table and matrices hold only those, the tables only their
|
|
71
|
+
rows and the links between them, the notes only their notes, and the clauses
|
|
72
|
+
mirrored are only the ones they cite. The output then says `Items: n of N`,
|
|
73
|
+
because a partial document read as a whole one misleads. An identifier the
|
|
74
|
+
graph does not hold is a usage error (exit 2), and nothing is written.
|
|
75
|
+
|
|
70
76
|
A quick run is silent. When a step — reading the graph, asking the tool to
|
|
71
77
|
write the document, writing the file — has run for a second, one line on
|
|
72
78
|
stderr says which, because a composed graph fetching its sources for the first
|
|
@@ -89,8 +95,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
|
|
|
89
95
|
resolved rather than asserted.
|
|
90
96
|
|
|
91
97
|
```bash
|
|
92
|
-
tl
|
|
93
|
-
tl
|
|
98
|
+
tl -C idd check --strict # the grounding gate
|
|
99
|
+
tl -C idd docs --check # idd/docs/spec.md must match the graph
|
|
94
100
|
tl-transform html -C idd # and the tool over its own graph
|
|
95
101
|
```
|
|
96
102
|
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "throughline-transform"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.5.0"
|
|
8
8
|
description = "Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.11"
|
|
@@ -37,11 +37,11 @@ classifiers = [
|
|
|
37
37
|
]
|
|
38
38
|
# The prose of every output is the tool's own: this package asks `tl docs` for the
|
|
39
39
|
# Markdown and `tl dump` for the structure, and writes nothing of an item itself
|
|
40
|
-
# (SR-0002). `tl:catalog` and `tl:sourced`
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
#
|
|
44
|
-
dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
|
|
40
|
+
# (SR-0002). `tl:catalog` and `tl:sourced` are the shapes this package reads
|
|
41
|
+
# (SR-0003). It was written against throughline 2.2.0 and throughline-compose
|
|
42
|
+
# 0.16.1; since 3.11.1 composition is the Tool's own (throughline UR-0037), `tl`
|
|
43
|
+
# renders both directives, and throughline is the one floor.
|
|
44
|
+
dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
|
|
45
45
|
|
|
46
46
|
[project.optional-dependencies]
|
|
47
47
|
dev = ["pytest>=8.0"]
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/cli.py
RENAMED
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
12
12
|
|
|
13
13
|
Any format takes --repository, --ref, --commit and --tree to state the
|
|
14
|
-
provenance instead of reading git (SR-0013)
|
|
14
|
+
provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
|
|
15
|
+
only the items named, saying how many of how many it holds (SR-0016).
|
|
15
16
|
|
|
16
17
|
Exit codes: 0 written · 1 the tool or the file system refused · 2 usage.
|
|
17
18
|
"""
|
|
@@ -20,7 +21,7 @@ from __future__ import annotations
|
|
|
20
21
|
|
|
21
22
|
import argparse
|
|
22
23
|
import sys
|
|
23
|
-
from dataclasses import
|
|
24
|
+
from dataclasses import replace
|
|
24
25
|
from pathlib import Path
|
|
25
26
|
|
|
26
27
|
from throughline.version import distribution_version as _v
|
|
@@ -28,7 +29,7 @@ from throughline.version import distribution_version as _v
|
|
|
28
29
|
from . import markdown as md
|
|
29
30
|
from .blocks import as_blocks, to_json
|
|
30
31
|
from .html import to_html
|
|
31
|
-
from .model import Graph, register_titles, source_titles
|
|
32
|
+
from .model import Graph, narrowed, register_titles, source_titles
|
|
32
33
|
from .notes import to_notes
|
|
33
34
|
from .office import to_docx, to_xlsx
|
|
34
35
|
from .package import Entry, archive, unpack, utf8
|
|
@@ -79,12 +80,29 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
79
80
|
default="one",
|
|
80
81
|
help="csv, xlsx: one table of everything, or one per register",
|
|
81
82
|
)
|
|
83
|
+
p.add_argument(
|
|
84
|
+
"--only",
|
|
85
|
+
action="append",
|
|
86
|
+
metavar="UID[,UID…]",
|
|
87
|
+
help="any format: hold only these items, and say so; may be given more than once",
|
|
88
|
+
)
|
|
82
89
|
return p
|
|
83
90
|
|
|
84
91
|
|
|
85
|
-
def
|
|
86
|
-
|
|
87
|
-
|
|
92
|
+
def named(values: list[str] | None) -> tuple[str, ...]:
|
|
93
|
+
"""The identifiers --only names, once each, in the order given (SR-0016)."""
|
|
94
|
+
seen: dict[str, None] = {}
|
|
95
|
+
for value in values or []:
|
|
96
|
+
for uid in value.split(","):
|
|
97
|
+
if uid.strip():
|
|
98
|
+
seen.setdefault(uid.strip(), None)
|
|
99
|
+
return tuple(seen)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _tables(graph: Graph, split: str, only: tuple[str, ...] = ()) -> tuple[list[Table], Table, list[Table]]:
|
|
103
|
+
held = narrowed(graph, only) if only else graph
|
|
104
|
+
tables = per_register(held) if split == "per-register" else [whole_graph(held)]
|
|
105
|
+
return tables, links_of(tables, narrowed=bool(only)), cited_sources(held)
|
|
88
106
|
|
|
89
107
|
|
|
90
108
|
def _about(provenance: Provenance, extra: list[list[str]] | None = None) -> Table:
|
|
@@ -103,7 +121,7 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
|
|
|
103
121
|
if fmt == "docx":
|
|
104
122
|
return to_docx(blocks), f"{stem}.docx"
|
|
105
123
|
if fmt == "blocks":
|
|
106
|
-
return utf8(to_json(blocks, provenance.lines(),
|
|
124
|
+
return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
|
|
107
125
|
return utf8(to_html(blocks, provenance)), f"{stem}.html"
|
|
108
126
|
|
|
109
127
|
if fmt == "notes":
|
|
@@ -112,7 +130,7 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
|
|
|
112
130
|
)
|
|
113
131
|
return to_notes(text, graph, provenance), f"{stem}-notes"
|
|
114
132
|
|
|
115
|
-
tables, links, sources = _tables(graph, opts.split)
|
|
133
|
+
tables, links, sources = _tables(graph, opts.split, opts.only)
|
|
116
134
|
if fmt == "xlsx":
|
|
117
135
|
return to_xlsx([*tables, links, *sources, _about(provenance)]), f"{stem}.xlsx"
|
|
118
136
|
|
|
@@ -148,15 +166,29 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
148
166
|
args = parser.parse_args(argv)
|
|
149
167
|
if args.folder and args.format not in FOLDERS:
|
|
150
168
|
parser.error(f"--folder applies to {' and '.join(FOLDERS)}, not {args.format}")
|
|
151
|
-
|
|
169
|
+
only = named(args.only)
|
|
170
|
+
if args.only is not None and not only:
|
|
171
|
+
parser.error("--only names no item")
|
|
172
|
+
opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only)
|
|
152
173
|
try:
|
|
153
174
|
root = find_graph(args.directory)
|
|
154
175
|
graph = load(root)
|
|
176
|
+
# SR-0016: an item asked for and not held is the caller's mistake, said
|
|
177
|
+
# before anything is written rather than a document quietly without it.
|
|
178
|
+
missing = [uid for uid in only if uid not in graph.items]
|
|
179
|
+
if missing:
|
|
180
|
+
parser.error(f"--only names what the graph does not hold: {', '.join(missing)}")
|
|
181
|
+
# UR-0003: the tool that produced the output, named as tl-ratify names itself —
|
|
182
|
+
# this package first, then the throughline that read the graph. The dump
|
|
183
|
+
# records throughline's bare distribution version.
|
|
184
|
+
producer = f"throughline-transform {_v('throughline-transform')} (throughline {graph.tool_version})"
|
|
155
185
|
provenance = (
|
|
156
|
-
stated(
|
|
186
|
+
stated(producer, args.repository, args.ref, args.commit, args.tree)
|
|
157
187
|
if any((args.repository, args.ref, args.commit, args.tree))
|
|
158
|
-
else provenance_of(root,
|
|
188
|
+
else provenance_of(root, producer)
|
|
159
189
|
)
|
|
190
|
+
if only:
|
|
191
|
+
provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
|
|
160
192
|
result, default = produce(graph, root, args.format, opts, provenance)
|
|
161
193
|
with slow(f"still writing {args.output or default}…"):
|
|
162
194
|
target = write(result, default, args.output, args.folder)
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/markdown.py
RENAMED
|
@@ -31,12 +31,27 @@ class Options:
|
|
|
31
31
|
markers: bool = False
|
|
32
32
|
#: For the tabular outputs: one table for everything, or one per register.
|
|
33
33
|
split: str = "one"
|
|
34
|
+
#: The items the output holds, where the caller named them (SR-0016);
|
|
35
|
+
#: empty for every item.
|
|
36
|
+
only: tuple[str, ...] = ()
|
|
34
37
|
|
|
35
38
|
|
|
36
39
|
def _region(directive: str) -> str:
|
|
37
40
|
return f"<!-- tl:{directive} -->\n<!-- tl:end -->"
|
|
38
41
|
|
|
39
42
|
|
|
43
|
+
def _within(expression: str, opts: Options) -> str:
|
|
44
|
+
"""A directive's filter, joined with the items named, so tl docs writes only those (SR-0016).
|
|
45
|
+
|
|
46
|
+
The identifiers are ones the graph holds (the command refuses any other), so
|
|
47
|
+
each is written as a quoted literal the filter language reads (tl:SR-0045).
|
|
48
|
+
"""
|
|
49
|
+
if not opts.only:
|
|
50
|
+
return expression
|
|
51
|
+
named = ", ".join(repr(uid) for uid in opts.only)
|
|
52
|
+
return f"({expression}) and (uid in [{named}])"
|
|
53
|
+
|
|
54
|
+
|
|
40
55
|
def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> str:
|
|
41
56
|
"""The document the tool is asked to fill."""
|
|
42
57
|
lines: list[str] = [f"# {provenance.repository} — requirements", ""]
|
|
@@ -44,9 +59,9 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
|
|
|
44
59
|
lines.append("")
|
|
45
60
|
|
|
46
61
|
if opts.stats:
|
|
47
|
-
lines += ["## Summary", "", _region("stats True"), ""]
|
|
62
|
+
lines += ["## Summary", "", _region(f"stats {_within('True', opts)}"), ""]
|
|
48
63
|
if opts.body in ("table", "both"):
|
|
49
|
-
lines += ["## Items", "", _region("table True"), ""]
|
|
64
|
+
lines += ["## Items", "", _region(f"table {_within('True', opts)}"), ""]
|
|
50
65
|
if opts.matrix:
|
|
51
66
|
# One matrix per grounding link type the graph declares, each over the
|
|
52
67
|
# items something actually reaches by that link. Over every item a
|
|
@@ -56,16 +71,16 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
|
|
|
56
71
|
lines += [
|
|
57
72
|
f"### {link_type.replace('_', ' ')}",
|
|
58
73
|
"",
|
|
59
|
-
_region(f"matrix incoming:{link_type} links.incoming(
|
|
74
|
+
_region(f"matrix incoming:{link_type} {_within(f'links.incoming({link_type!r})', opts)}"),
|
|
60
75
|
"",
|
|
61
76
|
]
|
|
62
77
|
if opts.body in ("catalog", "both"):
|
|
63
|
-
lines += ["## Every item", "", _region("catalog True"), ""]
|
|
78
|
+
lines += ["## Every item", "", _region(f"catalog {_within('True', opts)}"), ""]
|
|
64
79
|
# The words every cited clause answers to. Only over a composed graph: the
|
|
65
80
|
# directive is the composer's, and a graph adopting no source has nothing
|
|
66
81
|
# to mirror.
|
|
67
82
|
if graph.composed:
|
|
68
|
-
lines += ["## Clauses of adopted sources", "", _region("sourced True"), ""]
|
|
83
|
+
lines += ["## Clauses of adopted sources", "", _region(f"sourced {_within('True', opts)}"), ""]
|
|
69
84
|
return "\n".join(lines)
|
|
70
85
|
|
|
71
86
|
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/model.py
RENAMED
|
@@ -9,7 +9,8 @@ is not a rule — it is the same edges read the other way.
|
|
|
9
9
|
|
|
10
10
|
from __future__ import annotations
|
|
11
11
|
|
|
12
|
-
from
|
|
12
|
+
from collections.abc import Iterable
|
|
13
|
+
from dataclasses import dataclass, field, replace
|
|
13
14
|
from typing import Any
|
|
14
15
|
|
|
15
16
|
|
|
@@ -31,7 +32,7 @@ class Item:
|
|
|
31
32
|
normative: bool | None = None
|
|
32
33
|
links: list[Link] = field(default_factory=list)
|
|
33
34
|
attrs: dict[str, Any] = field(default_factory=dict)
|
|
34
|
-
#: The namespace a borrowed item came from, as ``tl
|
|
35
|
+
#: The namespace a borrowed item came from, as ``tl dump`` states it.
|
|
35
36
|
#: ``None`` on the graph's own items.
|
|
36
37
|
source: str | None = None
|
|
37
38
|
|
|
@@ -169,3 +170,22 @@ def source_titles(graph: Graph) -> dict[str, str]:
|
|
|
169
170
|
parts = [s.url or s.path or "", f"at {s.ref}" if s.ref else "", f"in {s.subdir}/" if s.subdir else ""]
|
|
170
171
|
out[s.namespace] = " ".join(p for p in parts if p)
|
|
171
172
|
return out
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def narrowed(graph: Graph, only: Iterable[str]) -> Graph:
|
|
176
|
+
"""The graph holding only the named items of its own (SR-0016).
|
|
177
|
+
|
|
178
|
+
Its registers, sources and clauses stay as they are: a clause is cited or
|
|
179
|
+
not by what is kept, and the writers already ask only for what is cited.
|
|
180
|
+
An edge from an item left out is not an edge of what is held.
|
|
181
|
+
"""
|
|
182
|
+
keep = set(only)
|
|
183
|
+
return replace(
|
|
184
|
+
graph,
|
|
185
|
+
items={uid: item for uid, item in graph.items.items() if uid in keep},
|
|
186
|
+
by_register={prefix: [i for i in items if i.uid in keep] for prefix, items in graph.by_register.items()},
|
|
187
|
+
incoming={
|
|
188
|
+
target: [(source, kind) for source, kind in edges if source in keep]
|
|
189
|
+
for target, edges in graph.incoming.items()
|
|
190
|
+
},
|
|
191
|
+
)
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/provenance.py
RENAMED
|
@@ -13,7 +13,7 @@ from __future__ import annotations
|
|
|
13
13
|
|
|
14
14
|
import re
|
|
15
15
|
import subprocess
|
|
16
|
-
from dataclasses import dataclass
|
|
16
|
+
from dataclasses import asdict, dataclass
|
|
17
17
|
from pathlib import Path
|
|
18
18
|
|
|
19
19
|
CLEAN = "clean"
|
|
@@ -31,15 +31,29 @@ class Provenance:
|
|
|
31
31
|
commit: str
|
|
32
32
|
tree: str
|
|
33
33
|
tool: str
|
|
34
|
+
#: How many of the graph's items the output holds, where the caller named
|
|
35
|
+
#: them (SR-0016) — "2 of 7". Empty for an output of every item, which then
|
|
36
|
+
#: says nothing more than it always did.
|
|
37
|
+
items: str = ""
|
|
34
38
|
|
|
35
39
|
def lines(self) -> list[str]:
|
|
36
|
-
|
|
40
|
+
lines = [
|
|
37
41
|
f"Repository: {self.repository}",
|
|
38
42
|
f"Ref: {self.ref or 'none'}",
|
|
39
43
|
f"Commit: {self.commit or 'none'}",
|
|
40
44
|
f"Working tree: {self.tree}",
|
|
41
45
|
f"Produced by: {self.tool}",
|
|
42
46
|
]
|
|
47
|
+
if self.items:
|
|
48
|
+
lines.append(f"Items: {self.items}")
|
|
49
|
+
return lines
|
|
50
|
+
|
|
51
|
+
def record(self) -> dict[str, str]:
|
|
52
|
+
"""The fields as data, for the blocks output; ``items`` only where a selection was made."""
|
|
53
|
+
fields = asdict(self)
|
|
54
|
+
if not self.items:
|
|
55
|
+
del fields["items"]
|
|
56
|
+
return fields
|
|
43
57
|
|
|
44
58
|
@property
|
|
45
59
|
def stem(self) -> str:
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/tables.py
RENAMED
|
@@ -121,12 +121,15 @@ def cited_sources(graph: Graph) -> list[Table]:
|
|
|
121
121
|
]
|
|
122
122
|
|
|
123
123
|
|
|
124
|
-
def links_of(tables: list[Table]) -> Table:
|
|
124
|
+
def links_of(tables: list[Table], narrowed: bool = False) -> Table:
|
|
125
125
|
"""Every link as a row of its own (SR-0006).
|
|
126
126
|
|
|
127
127
|
The item tables are read, not the graph: the links table names each end by
|
|
128
128
|
the sheet its row is on in this export, which depends on how the export was
|
|
129
129
|
split. A link into an adopted source names the namespace as the sheet.
|
|
130
|
+
Where the export holds only the items its caller named, a link to one of
|
|
131
|
+
the graph's own items left out is not given: both ends of every link are
|
|
132
|
+
in the export (SR-0016).
|
|
130
133
|
"""
|
|
131
134
|
sheet_of: dict[str, str] = {}
|
|
132
135
|
for table in tables:
|
|
@@ -144,6 +147,8 @@ def links_of(tables: list[Table]) -> Table:
|
|
|
144
147
|
continue
|
|
145
148
|
for target in row[c].split(", "):
|
|
146
149
|
home = sheet_of.get(target)
|
|
150
|
+
if narrowed and home is None and not is_borrowed(target):
|
|
151
|
+
continue
|
|
147
152
|
to_sheet = home if home is not None else (target.split(":")[0] if ":" in target else "")
|
|
148
153
|
rows.append([table.name, source, link_type, to_sheet, target])
|
|
149
154
|
return Table(name=LINKS_TABLE, columns=list(LINK_COLUMNS), rows=rows)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Turn a throughline requirements graph on disk, committed or not, into the forms its readers open: Markdown, a folder of Obsidian notes, CSV, an Excel workbook, a Word document, or a print-ready HTML document. Ships the tl-transform CLI.
|
|
5
5
|
Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -71,8 +71,7 @@ Office formats, which are written from their own specifications.
|
|
|
71
71
|
|
|
72
72
|
Every graph is read through `tl`, which composes a graph that declares
|
|
73
73
|
`[[sources]]` itself, so a borrowed clause is written with the reference number
|
|
74
|
-
a conformance document exists to carry
|
|
75
|
-
same program.
|
|
74
|
+
a conformance document exists to carry.
|
|
76
75
|
The tool is found beside this package's interpreter first and on the path
|
|
77
76
|
second, and is run as a command — its command line is the surface it publishes.
|
|
78
77
|
|
|
@@ -95,6 +94,13 @@ knows them without git — the editor holds them from its clone — states them
|
|
|
95
94
|
`--repository`, `--ref`, `--commit` and `--tree clean|dirty|untracked`, and git
|
|
96
95
|
is then not consulted.
|
|
97
96
|
|
|
97
|
+
`--only UID[,UID…]`, given once or more, narrows any format to the items it
|
|
98
|
+
names: the catalogue, table and matrices hold only those, the tables only their
|
|
99
|
+
rows and the links between them, the notes only their notes, and the clauses
|
|
100
|
+
mirrored are only the ones they cite. The output then says `Items: n of N`,
|
|
101
|
+
because a partial document read as a whole one misleads. An identifier the
|
|
102
|
+
graph does not hold is a usage error (exit 2), and nothing is written.
|
|
103
|
+
|
|
98
104
|
A quick run is silent. When a step — reading the graph, asking the tool to
|
|
99
105
|
write the document, writing the file — has run for a second, one line on
|
|
100
106
|
stderr says which, because a composed graph fetching its sources for the first
|
|
@@ -117,8 +123,8 @@ clause of the tool it reads (`satisfies: tl:SR-0111`) and have the citation
|
|
|
117
123
|
resolved rather than asserted.
|
|
118
124
|
|
|
119
125
|
```bash
|
|
120
|
-
tl
|
|
121
|
-
tl
|
|
126
|
+
tl -C idd check --strict # the grounding gate
|
|
127
|
+
tl -C idd docs --check # idd/docs/spec.md must match the graph
|
|
122
128
|
tl-transform html -C idd # and the tool over its own graph
|
|
123
129
|
```
|
|
124
130
|
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""An output of only the items its caller names (UR-0007, SR-0016).
|
|
4
|
+
|
|
5
|
+
The plain fixture holds seven items. Two are named here, UR-0002 and SR-0002,
|
|
6
|
+
in two --only flags: SR-0002 implements UR-0002, so exactly one link has both
|
|
7
|
+
ends in the output, while SR-0002 also relates to SR-0001, UR-0002 derives from
|
|
8
|
+
INT-0001 and SR-0003 implements UR-0002 — three links with one end left out.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import csv
|
|
14
|
+
import io
|
|
15
|
+
import json
|
|
16
|
+
import re
|
|
17
|
+
import zipfile
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
import pytest
|
|
21
|
+
|
|
22
|
+
from throughline_transform.cli import main
|
|
23
|
+
|
|
24
|
+
ONLY = ["--only", "UR-0002", "--only", "SR-0002"]
|
|
25
|
+
HELD = {"UR-0002", "SR-0002"}
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _rows(data: bytes) -> list[list[str]]:
|
|
29
|
+
return list(csv.reader(io.StringIO(data.decode("utf-8"))))
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def test_the_markdown_holds_the_named_items_and_says_so(plain_graph: Path, tmp_path: Path):
|
|
33
|
+
out = tmp_path / "only.md"
|
|
34
|
+
assert main(["md", "-C", str(plain_graph), "-o", str(out), "--matrix", "--body", "both", *ONLY]) == 0
|
|
35
|
+
text = out.read_text(encoding="utf-8")
|
|
36
|
+
assert "- Items: 2 of 7" in text
|
|
37
|
+
# Written by tl docs, catalogue and table alike: the two named, and no other.
|
|
38
|
+
assert set(re.findall(r"^\*\*([A-Z]+-\d{4}) — ", text, re.M)) == HELD
|
|
39
|
+
table = text.split("## Items", 1)[1].split("##", 1)[0]
|
|
40
|
+
assert set(re.findall(r"^\| ([A-Z]+-\d{4}) \|", table, re.M)) == HELD
|
|
41
|
+
# Each matrix has rows only for what is held: UR-0002's realizers, and no intent.
|
|
42
|
+
implements = text.split("### implements", 1)[1].split("##", 1)[0]
|
|
43
|
+
assert set(re.findall(r"^\| ([A-Z]+-\d{4}) \|", implements, re.M)) == {"UR-0002"}
|
|
44
|
+
derives = text.split("### derives from", 1)[1].split("##", 1)[0]
|
|
45
|
+
assert re.findall(r"^\| ([A-Z]+-\d{4}) \|", derives, re.M) == []
|
|
46
|
+
assert "- **Items:** 2 — " in text
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def test_the_tables_hold_the_named_rows_and_only_the_links_between_them(plain_graph: Path, tmp_path: Path):
|
|
50
|
+
target = tmp_path / "csv"
|
|
51
|
+
assert main(["csv", "-C", str(plain_graph), "-o", str(target), "--folder", *ONLY]) == 0
|
|
52
|
+
items = _rows((target / "All items.csv").read_bytes())
|
|
53
|
+
assert {row[0] for row in items[1:]} == HELD
|
|
54
|
+
links = _rows((target / "links.csv").read_bytes())
|
|
55
|
+
assert links[1:] == [["All items", "SR-0002", "implements", "All items", "UR-0002"]]
|
|
56
|
+
about = dict(tuple(row) for row in _rows((target / "about-this-export.csv").read_bytes())[1:])
|
|
57
|
+
assert about["Items"] == "2 of 7"
|
|
58
|
+
|
|
59
|
+
split = tmp_path / "split"
|
|
60
|
+
assert main(["csv", "-C", str(plain_graph), "-o", str(split), "--folder", "--split", "per-register", *ONLY]) == 0
|
|
61
|
+
# A register holding nothing named is no table at all.
|
|
62
|
+
assert sorted(p.name for p in split.iterdir()) == [
|
|
63
|
+
"System requirements.csv", "User requirements.csv", "about-this-export.csv", "links.csv",
|
|
64
|
+
]
|
|
65
|
+
assert _rows((split / "links.csv").read_bytes())[1:] == [
|
|
66
|
+
["System requirements", "SR-0002", "implements", "User requirements", "UR-0002"],
|
|
67
|
+
]
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def test_the_workbook_holds_two_item_rows_and_one_link(plain_graph: Path, tmp_path: Path):
|
|
71
|
+
out = tmp_path / "only.xlsx"
|
|
72
|
+
assert main(["xlsx", "-C", str(plain_graph), "-o", str(out), *ONLY]) == 0
|
|
73
|
+
with zipfile.ZipFile(out) as zf:
|
|
74
|
+
workbook = zf.read("xl/workbook.xml").decode()
|
|
75
|
+
names = re.findall(r'<sheet name="([^"]+)"', workbook)
|
|
76
|
+
sheets = {name: zf.read(f"xl/worksheets/sheet{i + 1}.xml").decode() for i, name in enumerate(names)}
|
|
77
|
+
# A header row, then one row per item or link.
|
|
78
|
+
assert sheets["All items"].count("<row ") == 3
|
|
79
|
+
assert sheets["Links"].count("<row ") == 2
|
|
80
|
+
# The workbook writes its strings inline, so the About sheet reads as written.
|
|
81
|
+
assert ">Items</t>" in sheets["About this export"] and ">2 of 7</t>" in sheets["About this export"]
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def test_the_notes_hold_the_named_items_and_link_to_nothing_left_out(plain_graph: Path, tmp_path: Path):
|
|
85
|
+
target = tmp_path / "vault"
|
|
86
|
+
assert main(["notes", "-C", str(plain_graph), "-o", str(target), "--folder", *ONLY]) == 0
|
|
87
|
+
notes = sorted(str(p.relative_to(target)) for p in target.rglob("*.md"))
|
|
88
|
+
assert notes == ["About this export.md", "System requirements/SR-0002.md", "User requirements/UR-0002.md"]
|
|
89
|
+
for path in notes:
|
|
90
|
+
body = (target / path).read_text(encoding="utf-8").split("\n---\n", 1)[-1]
|
|
91
|
+
for linked in re.findall(r"(?<!\\)\[\[([^\]|]+)", body):
|
|
92
|
+
assert linked in HELD, f"{path} links to {linked}"
|
|
93
|
+
sr2 = (target / "System requirements/SR-0002.md").read_text(encoding="utf-8")
|
|
94
|
+
assert "*Implements:* [[UR-0002]]" in sr2 and "*Relates:* SR-0001" in sr2
|
|
95
|
+
ur2 = (target / "User requirements/UR-0002.md").read_text(encoding="utf-8")
|
|
96
|
+
assert "*Implements this:* [[SR-0002]]" in ur2 and "SR-0003" not in ur2
|
|
97
|
+
about = (target / "About this export.md").read_text(encoding="utf-8")
|
|
98
|
+
assert "- Items: 2 of 7" in about and "This export holds 2 items." in about
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def test_the_blocks_and_documents_say_what_they_hold(plain_graph: Path, tmp_path: Path):
|
|
102
|
+
out = tmp_path / "only.json"
|
|
103
|
+
assert main(["blocks", "-C", str(plain_graph), "-o", str(out), *ONLY]) == 0
|
|
104
|
+
doc = json.loads(out.read_text(encoding="utf-8"))
|
|
105
|
+
assert doc["provenance"]["items"] == "2 of 7"
|
|
106
|
+
assert doc["provenance_lines"][-1] == "Items: 2 of 7"
|
|
107
|
+
assert {b["item"]["uid"] for b in doc["blocks"] if "item" in b} == HELD
|
|
108
|
+
for fmt in ("docx", "html"):
|
|
109
|
+
target = tmp_path / f"only.{fmt}"
|
|
110
|
+
assert main([fmt, "-C", str(plain_graph), "-o", str(target), *ONLY]) == 0
|
|
111
|
+
data = target.read_bytes()
|
|
112
|
+
text = zipfile.ZipFile(io.BytesIO(data)).read("word/document.xml").decode() if fmt == "docx" else data.decode()
|
|
113
|
+
assert "Items: 2 of 7" in text
|
|
114
|
+
assert "SR-0002" in text and "SR-0003" not in text
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def test_a_composed_output_mirrors_only_what_the_named_items_cite(composed_graph: Path, tmp_path: Path):
|
|
118
|
+
citing = tmp_path / "citing.md"
|
|
119
|
+
assert main(["md", "-C", str(composed_graph), "-o", str(citing), "--only", "SR-0001"]) == 0
|
|
120
|
+
assert "**src:SR-0001 — " in citing.read_text(encoding="utf-8")
|
|
121
|
+
other = tmp_path / "other.md"
|
|
122
|
+
assert main(["md", "-C", str(composed_graph), "-o", str(other), "--only", "UR-0001"]) == 0
|
|
123
|
+
assert "**src:SR-0001 — " not in other.read_text(encoding="utf-8")
|
|
124
|
+
target = tmp_path / "csv"
|
|
125
|
+
assert main(["csv", "-C", str(composed_graph), "-o", str(target), "--folder", "--only", "UR-0001"]) == 0
|
|
126
|
+
assert not (target / "src.csv").exists()
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def test_an_identifier_the_graph_lacks_is_refused_and_nothing_is_written(
|
|
130
|
+
plain_graph: Path, tmp_path: Path, capsys: pytest.CaptureFixture
|
|
131
|
+
):
|
|
132
|
+
out = tmp_path / "never.md"
|
|
133
|
+
with pytest.raises(SystemExit) as exc:
|
|
134
|
+
main(["md", "-C", str(plain_graph), "-o", str(out), "--only", "SR-0002,SR-0099,NOPE-1"])
|
|
135
|
+
assert exc.value.code == 2
|
|
136
|
+
assert "SR-0099, NOPE-1" in capsys.readouterr().err
|
|
137
|
+
assert not out.exists()
|
|
138
|
+
with pytest.raises(SystemExit) as exc:
|
|
139
|
+
main(["md", "-C", str(plain_graph), "-o", str(out), "--only", " , "])
|
|
140
|
+
assert exc.value.code == 2
|
|
141
|
+
assert not out.exists()
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def test_named_nothing_an_output_says_nothing_more(plain_graph: Path, tmp_path: Path):
|
|
145
|
+
out = tmp_path / "all.json"
|
|
146
|
+
assert main(["blocks", "-C", str(plain_graph), "-o", str(out)]) == 0
|
|
147
|
+
doc = json.loads(out.read_text(encoding="utf-8"))
|
|
148
|
+
assert "items" not in doc["provenance"]
|
|
149
|
+
assert not any(line.startswith("Items:") for line in doc["provenance_lines"])
|
|
150
|
+
assert len([b for b in doc["blocks"] if "item" in b]) == 7
|
|
@@ -322,6 +322,15 @@ def test_provenance_reads_git_and_notices_uncommitted_changes(git_graph: Path):
|
|
|
322
322
|
subprocess.run(["git", "-C", str(git_graph), "checkout", "--", "."], check=True)
|
|
323
323
|
|
|
324
324
|
|
|
325
|
+
def test_the_output_names_the_tool_that_produced_it(plain_graph: Path, tmp_path: Path):
|
|
326
|
+
# UR-0003: "the tool that produced it" is this package, named first, and then the
|
|
327
|
+
# throughline that read the graph; the dump records only throughline's version.
|
|
328
|
+
out = tmp_path / "named.md"
|
|
329
|
+
assert main(["md", "-C", str(plain_graph), "-o", str(out), "--repository", "r"]) == 0
|
|
330
|
+
line = next(l for l in out.read_text().splitlines() if "Produced by:" in l)
|
|
331
|
+
assert re.search(r"Produced by: throughline-transform \S+ \(throughline \S+\)$", line), line
|
|
332
|
+
|
|
333
|
+
|
|
325
334
|
# --- the command (UR-0001, SR-0011) -----------------------------------------
|
|
326
335
|
|
|
327
336
|
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/blocks.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/notes.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/progress.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/project.py
RENAMED
|
File without changes
|
{throughline_transform-0.4.0 → throughline_transform-0.5.0}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|