throughline-transform 0.6.0__tar.gz → 0.7.1__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.6.0/src/throughline_transform.egg-info → throughline_transform-0.7.1}/PKG-INFO +29 -5
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/README.md +25 -3
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/pyproject.toml +4 -2
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/cli.py +5 -23
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/markdown.py +38 -16
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/model.py +0 -4
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/project.py +0 -8
- {throughline_transform-0.6.0 → throughline_transform-0.7.1/src/throughline_transform.egg-info}/PKG-INFO +29 -5
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/SOURCES.txt +0 -2
- throughline_transform-0.7.1/src/throughline_transform.egg-info/requires.txt +4 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/conftest.py +28 -8
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_outputs.py +6 -4
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_surface.py +3 -1
- throughline_transform-0.6.0/src/throughline_transform/assistant.py +0 -133
- throughline_transform-0.6.0/src/throughline_transform.egg-info/requires.txt +0 -4
- throughline_transform-0.6.0/tests/test_assistant.py +0 -149
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/LICENSE +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/MANIFEST.in +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/NOTICE +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/setup.cfg +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/__init__.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/blocks.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/html.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/notes.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/office.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/package.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/progress.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/provenance.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/shape.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/tables.py +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/dependency_links.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/entry_points.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform.egg-info/top_level.txt +0 -0
- {throughline_transform-0.6.0 → throughline_transform-0.7.1}/tests/test_only.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.1
|
|
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
|
|
@@ -15,13 +15,15 @@ Classifier: Operating System :: OS Independent
|
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
16
|
Classifier: Programming Language :: Python :: 3.11
|
|
17
17
|
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
20
|
Classifier: Topic :: Software Development :: Documentation
|
|
19
21
|
Classifier: Topic :: Office/Business
|
|
20
22
|
Requires-Python: >=3.11
|
|
21
23
|
Description-Content-Type: text/markdown
|
|
22
24
|
License-File: LICENSE
|
|
23
25
|
License-File: NOTICE
|
|
24
|
-
Requires-Dist: throughline>=3.
|
|
26
|
+
Requires-Dist: throughline>=3.11.1
|
|
25
27
|
Provides-Extra: dev
|
|
26
28
|
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
29
|
Dynamic: license-file
|
|
@@ -32,7 +34,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
|
|
|
32
34
|
disk — committed or not — in the forms its readers open. One command, one file:
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
|
-
|
|
37
|
+
uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
|
|
36
38
|
|
|
37
39
|
tl-transform md -C idd # Markdown, written by the tool itself
|
|
38
40
|
tl-transform notes -C idd # a folder of notes for Obsidian (zip)
|
|
@@ -41,7 +43,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
|
|
|
41
43
|
tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
|
|
42
44
|
tl-transform docx -C idd # a Word document: title page, contents, a heading per item
|
|
43
45
|
tl-transform html -C idd # a print-ready page — print it to PDF from any browser
|
|
44
|
-
tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
|
|
45
46
|
```
|
|
46
47
|
|
|
47
48
|
It is the command-line half of the
|
|
@@ -51,6 +52,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
|
|
|
51
52
|
tree, and the output says whether that tree was clean, carried uncommitted
|
|
52
53
|
changes, or was not under version control at all.
|
|
53
54
|
|
|
55
|
+
`--managed-python` has uv use its own build of Python rather than the operating
|
|
56
|
+
system's, so an OS Python upgrade does not break the install;
|
|
57
|
+
`--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
|
|
58
|
+
from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
59
|
+
If you use pipx instead: `pipx install --include-deps throughline-transform`.
|
|
60
|
+
|
|
61
|
+
## If `tl-transform` says `bad interpreter` after a Python upgrade
|
|
62
|
+
|
|
63
|
+
A tool installed with pipx (or into any virtual environment) runs on the Python it
|
|
64
|
+
was installed with. When your operating system upgrades its Python and removes the
|
|
65
|
+
old one, every command in that environment fails before any of its code runs, with
|
|
66
|
+
`bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
|
|
67
|
+
to be rebuilt on the new Python:
|
|
68
|
+
|
|
69
|
+
| Installed with | Rebuild with |
|
|
70
|
+
|---|---|
|
|
71
|
+
| pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
|
|
72
|
+
| pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
|
|
73
|
+
| uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
|
|
74
|
+
|
|
75
|
+
An install made with uv's `--managed-python` does not hit this: the operating system
|
|
76
|
+
does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
|
|
77
|
+
which Python runs `tl` and how it was installed.
|
|
78
|
+
|
|
54
79
|
## What it does not do
|
|
55
80
|
|
|
56
81
|
**It never renders an item's words.** The Markdown is asked of `tl docs` over a
|
|
@@ -86,7 +111,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
86
111
|
| `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
|
|
87
112
|
| `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
|
|
88
113
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
89
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
90
114
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
91
115
|
|
|
92
116
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -4,7 +4,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
|
|
|
4
4
|
disk — committed or not — in the forms its readers open. One command, one file:
|
|
5
5
|
|
|
6
6
|
```bash
|
|
7
|
-
|
|
7
|
+
uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
|
|
8
8
|
|
|
9
9
|
tl-transform md -C idd # Markdown, written by the tool itself
|
|
10
10
|
tl-transform notes -C idd # a folder of notes for Obsidian (zip)
|
|
@@ -13,7 +13,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
|
|
|
13
13
|
tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
|
|
14
14
|
tl-transform docx -C idd # a Word document: title page, contents, a heading per item
|
|
15
15
|
tl-transform html -C idd # a print-ready page — print it to PDF from any browser
|
|
16
|
-
tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
|
|
17
16
|
```
|
|
18
17
|
|
|
19
18
|
It is the command-line half of the
|
|
@@ -23,6 +22,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
|
|
|
23
22
|
tree, and the output says whether that tree was clean, carried uncommitted
|
|
24
23
|
changes, or was not under version control at all.
|
|
25
24
|
|
|
25
|
+
`--managed-python` has uv use its own build of Python rather than the operating
|
|
26
|
+
system's, so an OS Python upgrade does not break the install;
|
|
27
|
+
`--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
|
|
28
|
+
from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
29
|
+
If you use pipx instead: `pipx install --include-deps throughline-transform`.
|
|
30
|
+
|
|
31
|
+
## If `tl-transform` says `bad interpreter` after a Python upgrade
|
|
32
|
+
|
|
33
|
+
A tool installed with pipx (or into any virtual environment) runs on the Python it
|
|
34
|
+
was installed with. When your operating system upgrades its Python and removes the
|
|
35
|
+
old one, every command in that environment fails before any of its code runs, with
|
|
36
|
+
`bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
|
|
37
|
+
to be rebuilt on the new Python:
|
|
38
|
+
|
|
39
|
+
| Installed with | Rebuild with |
|
|
40
|
+
|---|---|
|
|
41
|
+
| pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
|
|
42
|
+
| pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
|
|
43
|
+
| uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
|
|
44
|
+
|
|
45
|
+
An install made with uv's `--managed-python` does not hit this: the operating system
|
|
46
|
+
does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
|
|
47
|
+
which Python runs `tl` and how it was installed.
|
|
48
|
+
|
|
26
49
|
## What it does not do
|
|
27
50
|
|
|
28
51
|
**It never renders an item's words.** The Markdown is asked of `tl docs` over a
|
|
@@ -58,7 +81,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
58
81
|
| `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
|
|
59
82
|
| `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
|
|
60
83
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
61
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
62
84
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
63
85
|
|
|
64
86
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -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.7.1"
|
|
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"
|
|
@@ -32,6 +32,8 @@ classifiers = [
|
|
|
32
32
|
"Programming Language :: Python :: 3",
|
|
33
33
|
"Programming Language :: Python :: 3.11",
|
|
34
34
|
"Programming Language :: Python :: 3.12",
|
|
35
|
+
"Programming Language :: Python :: 3.13",
|
|
36
|
+
"Programming Language :: Python :: 3.14",
|
|
35
37
|
"Topic :: Software Development :: Documentation",
|
|
36
38
|
"Topic :: Office/Business",
|
|
37
39
|
]
|
|
@@ -41,7 +43,7 @@ classifiers = [
|
|
|
41
43
|
# (SR-0003). It was written against throughline 2.2.0 and throughline-compose
|
|
42
44
|
# 0.16.1; since 3.11.1 composition is the Tool's own (throughline UR-0037), `tl`
|
|
43
45
|
# renders both directives, and throughline is the one floor.
|
|
44
|
-
dependencies = ["throughline>=3.
|
|
46
|
+
dependencies = ["throughline>=3.11.1"] # composition is the Tool's own since 3.11.1 (throughline UR-0037)
|
|
45
47
|
|
|
46
48
|
[project.optional-dependencies]
|
|
47
49
|
dev = ["pytest>=8.0"]
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/cli.py
RENAMED
|
@@ -9,7 +9,6 @@
|
|
|
9
9
|
tl-transform docx [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
10
10
|
tl-transform html [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
11
11
|
tl-transform blocks [-C DIR] [-o FILE] [--body …] [--matrix] [--no-stats]
|
|
12
|
-
tl-transform assistant [-C DIR] [-o DIR] [--wrap json|md]
|
|
13
12
|
|
|
14
13
|
Any format takes --repository, --ref, --commit and --tree to state the
|
|
15
14
|
provenance instead of reading git (SR-0013), and --only UID[,UID…] to hold
|
|
@@ -29,22 +28,19 @@ from throughline.version import distribution_version as _v
|
|
|
29
28
|
|
|
30
29
|
from . import markdown as md
|
|
31
30
|
from .blocks import as_blocks, to_json
|
|
32
|
-
from .assistant import WRAPS, to_assistant
|
|
33
31
|
from .html import to_html
|
|
34
32
|
from .model import Graph, narrowed, register_titles, source_titles
|
|
35
33
|
from .notes import to_notes
|
|
36
34
|
from .office import to_docx, to_xlsx
|
|
37
35
|
from .package import Entry, archive, unpack, utf8
|
|
38
36
|
from .progress import slow
|
|
39
|
-
from .project import TransformError,
|
|
37
|
+
from .project import TransformError, find_graph, load
|
|
40
38
|
from .provenance import TREE_WORDS, Provenance, provenance_of, stated
|
|
41
39
|
from .tables import Table, cited_sources, file_name, links_of, per_register, to_csv, whole_graph
|
|
42
40
|
|
|
43
|
-
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks"
|
|
41
|
+
FORMATS = ("md", "notes", "csv", "xlsx", "docx", "html", "blocks")
|
|
44
42
|
PROSE = ("md", "docx", "html", "blocks")
|
|
45
|
-
FOLDERS = ("notes", "csv"
|
|
46
|
-
#: Always a folder, never an archive: an assistant cannot open one (SR-0017).
|
|
47
|
-
FOLDER_ONLY = ("assistant",)
|
|
43
|
+
FOLDERS = ("notes", "csv")
|
|
48
44
|
|
|
49
45
|
|
|
50
46
|
def version_string() -> str:
|
|
@@ -70,12 +66,6 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
70
66
|
p.add_argument("--matrix", action="store_true", help="md, docx, html, blocks: add a traceability matrix per grounding link")
|
|
71
67
|
p.add_argument("--no-stats", dest="stats", action="store_false", help="md, docx, html, blocks: leave out the tool's summary")
|
|
72
68
|
p.add_argument("--markers", action="store_true", help="md: keep the tool's region markers so `tl docs` can refill the file")
|
|
73
|
-
p.add_argument(
|
|
74
|
-
"--wrap",
|
|
75
|
-
choices=WRAPS,
|
|
76
|
-
default="json",
|
|
77
|
-
help="assistant: each file as JSON, or as Markdown holding one fenced JSON block for an assistant that will not read a .json file",
|
|
78
|
-
)
|
|
79
69
|
p.add_argument("--repository", metavar="OWNER/NAME", help="state the repository instead of reading git")
|
|
80
70
|
p.add_argument("--ref", metavar="REF", help="state the ref instead of reading git")
|
|
81
71
|
p.add_argument("--commit", metavar="SHA", help="state the commit instead of reading git")
|
|
@@ -134,12 +124,6 @@ def produce(graph: Graph, root: Path, fmt: str, opts: md.Options, provenance: Pr
|
|
|
134
124
|
return utf8(to_json(blocks, provenance.lines(), provenance.record())), f"{stem}-blocks.json"
|
|
135
125
|
return utf8(to_html(blocks, provenance)), f"{stem}.html"
|
|
136
126
|
|
|
137
|
-
if fmt == "assistant":
|
|
138
|
-
entries = to_assistant(
|
|
139
|
-
graph.raw, provenance, change_set_format(root, graph.composed), wrap=opts.wrap, only=opts.only
|
|
140
|
-
)
|
|
141
|
-
return entries, f"{stem}-assistant"
|
|
142
|
-
|
|
143
127
|
if fmt == "notes":
|
|
144
128
|
text = md.to_markdown(
|
|
145
129
|
root, graph, replace(opts, body="catalog", matrix=False, stats=False, markers=False), provenance
|
|
@@ -185,9 +169,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
185
169
|
only = named(args.only)
|
|
186
170
|
if args.only is not None and not only:
|
|
187
171
|
parser.error("--only names no item")
|
|
188
|
-
opts = md.Options(
|
|
189
|
-
body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only, wrap=args.wrap
|
|
190
|
-
)
|
|
172
|
+
opts = md.Options(body=args.body, matrix=args.matrix, stats=args.stats, markers=args.markers, split=args.split, only=only)
|
|
191
173
|
try:
|
|
192
174
|
root = find_graph(args.directory)
|
|
193
175
|
graph = load(root)
|
|
@@ -209,7 +191,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
209
191
|
provenance = replace(provenance, items=f"{len(only)} of {len(graph.items)}")
|
|
210
192
|
result, default = produce(graph, root, args.format, opts, provenance)
|
|
211
193
|
with slow(f"still writing {args.output or default}…"):
|
|
212
|
-
target = write(result, default, args.output, args.folder
|
|
194
|
+
target = write(result, default, args.output, args.folder)
|
|
213
195
|
except (TransformError, OSError, ValueError) as exc:
|
|
214
196
|
print(f"tl-transform: {exc}", file=sys.stderr)
|
|
215
197
|
return 1
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/markdown.py
RENAMED
|
@@ -31,9 +31,6 @@ 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
|
-
#: For the assistant form: each file as JSON, or as Markdown holding one
|
|
35
|
-
#: fenced JSON block.
|
|
36
|
-
wrap: str = "json"
|
|
37
34
|
#: The items the output holds, where the caller named them (SR-0016);
|
|
38
35
|
#: empty for every item.
|
|
39
36
|
only: tuple[str, ...] = ()
|
|
@@ -43,28 +40,53 @@ def _region(directive: str) -> str:
|
|
|
43
40
|
return f"<!-- tl:{directive} -->\n<!-- tl:end -->"
|
|
44
41
|
|
|
45
42
|
|
|
46
|
-
|
|
47
|
-
"""
|
|
43
|
+
class _Filters:
|
|
44
|
+
"""Filters written in the language the graph declares (SR-0021).
|
|
48
45
|
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
tl reads every filter of a project in the one language its configuration names
|
|
47
|
+
as ``filter_language`` under ``[project]`` (tl:SR-0337): ``gql`` for a graph
|
|
48
|
+
made or migrated by tl 6, the earlier expression language where it names none.
|
|
49
|
+
The tool never guesses a filter's language from its text, so neither does this.
|
|
51
50
|
"""
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
51
|
+
|
|
52
|
+
def __init__(self, graph: Graph) -> None:
|
|
53
|
+
project = graph.config.get("project") or {}
|
|
54
|
+
self.gql = project.get("filter_language") == "gql"
|
|
55
|
+
|
|
56
|
+
@property
|
|
57
|
+
def every(self) -> str:
|
|
58
|
+
return "TRUE" if self.gql else "True"
|
|
59
|
+
|
|
60
|
+
def incoming(self, link_type: str) -> str:
|
|
61
|
+
if self.gql:
|
|
62
|
+
return f"EXISTS {{ (item)<-[:{link_type}]-() }}"
|
|
63
|
+
return f"links.incoming({link_type!r})"
|
|
64
|
+
|
|
65
|
+
def within(self, expression: str, opts: Options) -> str:
|
|
66
|
+
"""A directive's filter, joined with the items named, so tl docs writes only those (SR-0016).
|
|
67
|
+
|
|
68
|
+
The identifiers are ones the graph holds (the command refuses any other), so
|
|
69
|
+
each is written as a quoted literal the filter language reads (tl:SR-0045).
|
|
70
|
+
"""
|
|
71
|
+
if not opts.only:
|
|
72
|
+
return expression
|
|
73
|
+
named = ", ".join(repr(uid) for uid in opts.only)
|
|
74
|
+
if self.gql:
|
|
75
|
+
return f"({expression}) AND (item.uid IN [{named}])"
|
|
76
|
+
return f"({expression}) and (uid in [{named}])"
|
|
56
77
|
|
|
57
78
|
|
|
58
79
|
def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> str:
|
|
59
80
|
"""The document the tool is asked to fill."""
|
|
81
|
+
f = _Filters(graph)
|
|
60
82
|
lines: list[str] = [f"# {provenance.repository} — requirements", ""]
|
|
61
83
|
lines += [f"- {line}" for line in provenance.lines()]
|
|
62
84
|
lines.append("")
|
|
63
85
|
|
|
64
86
|
if opts.stats:
|
|
65
|
-
lines += ["## Summary", "", _region(f"stats {
|
|
87
|
+
lines += ["## Summary", "", _region(f"stats {f.within(f.every, opts)}"), ""]
|
|
66
88
|
if opts.body in ("table", "both"):
|
|
67
|
-
lines += ["## Items", "", _region(f"table {
|
|
89
|
+
lines += ["## Items", "", _region(f"table {f.within(f.every, opts)}"), ""]
|
|
68
90
|
if opts.matrix:
|
|
69
91
|
# One matrix per grounding link type the graph declares, each over the
|
|
70
92
|
# items something actually reaches by that link. Over every item a
|
|
@@ -74,16 +96,16 @@ def directive_document(graph: Graph, opts: Options, provenance: Provenance) -> s
|
|
|
74
96
|
lines += [
|
|
75
97
|
f"### {link_type.replace('_', ' ')}",
|
|
76
98
|
"",
|
|
77
|
-
_region(f"matrix incoming:{link_type} {
|
|
99
|
+
_region(f"matrix incoming:{link_type} {f.within(f.incoming(link_type), opts)}"),
|
|
78
100
|
"",
|
|
79
101
|
]
|
|
80
102
|
if opts.body in ("catalog", "both"):
|
|
81
|
-
lines += ["## Every item", "", _region(f"catalog {
|
|
103
|
+
lines += ["## Every item", "", _region(f"catalog {f.within(f.every, opts)}"), ""]
|
|
82
104
|
# The words every cited clause answers to. Only over a composed graph: the
|
|
83
105
|
# directive is the composer's, and a graph adopting no source has nothing
|
|
84
106
|
# to mirror.
|
|
85
107
|
if graph.composed:
|
|
86
|
-
lines += ["## Clauses of adopted sources", "", _region(f"sourced {
|
|
108
|
+
lines += ["## Clauses of adopted sources", "", _region(f"sourced {f.within(f.every, opts)}"), ""]
|
|
87
109
|
return "\n".join(lines)
|
|
88
110
|
|
|
89
111
|
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/model.py
RENAMED
|
@@ -72,9 +72,6 @@ class Graph:
|
|
|
72
72
|
#: What the tool called itself in the dump.
|
|
73
73
|
tool_version: str
|
|
74
74
|
composed: bool
|
|
75
|
-
#: The dump itself, as the tool wrote it, for the assistant form that hands
|
|
76
|
-
#: it on unreshaped (SR-0017).
|
|
77
|
-
raw: dict[str, Any] = field(default_factory=dict)
|
|
78
75
|
|
|
79
76
|
|
|
80
77
|
def prefix_of(uid: str) -> str:
|
|
@@ -152,7 +149,6 @@ def index(dump: dict[str, Any], composed: bool) -> Graph:
|
|
|
152
149
|
sources=sources,
|
|
153
150
|
tool_version=str(meta.get("tool_version") or "?"),
|
|
154
151
|
composed=composed,
|
|
155
|
-
raw=dump,
|
|
156
152
|
)
|
|
157
153
|
|
|
158
154
|
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/project.py
RENAMED
|
@@ -141,14 +141,6 @@ def load(root: Path) -> Graph:
|
|
|
141
141
|
return index(raw, composed)
|
|
142
142
|
|
|
143
143
|
|
|
144
|
-
def change_set_format(root: Path, composed: bool) -> str:
|
|
145
|
-
"""The change-set form ``tl apply`` accepts, as the tool itself states it
|
|
146
|
-
(SR-0018): taken from the command, never written here, so what an assistant
|
|
147
|
-
is told to write cannot drift from what apply reads."""
|
|
148
|
-
with slow(f"still asking {_tool(composed)} for the change-set format…"):
|
|
149
|
-
return run(root, ["apply", "--describe"], composed)
|
|
150
|
-
|
|
151
|
-
|
|
152
144
|
def docs(root: Path, document: str, composed: bool) -> str:
|
|
153
145
|
"""Hand the tool a document of directives and read back what it wrote.
|
|
154
146
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline-transform
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.1
|
|
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
|
|
@@ -15,13 +15,15 @@ Classifier: Operating System :: OS Independent
|
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
16
|
Classifier: Programming Language :: Python :: 3.11
|
|
17
17
|
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
20
|
Classifier: Topic :: Software Development :: Documentation
|
|
19
21
|
Classifier: Topic :: Office/Business
|
|
20
22
|
Requires-Python: >=3.11
|
|
21
23
|
Description-Content-Type: text/markdown
|
|
22
24
|
License-File: LICENSE
|
|
23
25
|
License-File: NOTICE
|
|
24
|
-
Requires-Dist: throughline>=3.
|
|
26
|
+
Requires-Dist: throughline>=3.11.1
|
|
25
27
|
Provides-Extra: dev
|
|
26
28
|
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
29
|
Dynamic: license-file
|
|
@@ -32,7 +34,7 @@ A [throughline](https://github.com/rhodium-org/throughline) requirements graph o
|
|
|
32
34
|
disk — committed or not — in the forms its readers open. One command, one file:
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
|
-
|
|
37
|
+
uv tool install --python 3.13 --managed-python throughline-transform --with-executables-from throughline # tl too
|
|
36
38
|
|
|
37
39
|
tl-transform md -C idd # Markdown, written by the tool itself
|
|
38
40
|
tl-transform notes -C idd # a folder of notes for Obsidian (zip)
|
|
@@ -41,7 +43,6 @@ tl-transform csv -C idd # one row per item, a links file, a file
|
|
|
41
43
|
tl-transform xlsx -C idd # the same as a read-only workbook that still sorts and filters
|
|
42
44
|
tl-transform docx -C idd # a Word document: title page, contents, a heading per item
|
|
43
45
|
tl-transform html -C idd # a print-ready page — print it to PDF from any browser
|
|
44
|
-
tl-transform assistant -C idd # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer
|
|
45
46
|
```
|
|
46
47
|
|
|
47
48
|
It is the command-line half of the
|
|
@@ -51,6 +52,30 @@ disk. The editor needs the graph on GitHub. This does not — it reads the worki
|
|
|
51
52
|
tree, and the output says whether that tree was clean, carried uncommitted
|
|
52
53
|
changes, or was not under version control at all.
|
|
53
54
|
|
|
55
|
+
`--managed-python` has uv use its own build of Python rather than the operating
|
|
56
|
+
system's, so an OS Python upgrade does not break the install;
|
|
57
|
+
`--with-executables-from throughline` puts `tl` on your `PATH` beside it. Get uv
|
|
58
|
+
from [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
59
|
+
If you use pipx instead: `pipx install --include-deps throughline-transform`.
|
|
60
|
+
|
|
61
|
+
## If `tl-transform` says `bad interpreter` after a Python upgrade
|
|
62
|
+
|
|
63
|
+
A tool installed with pipx (or into any virtual environment) runs on the Python it
|
|
64
|
+
was installed with. When your operating system upgrades its Python and removes the
|
|
65
|
+
old one, every command in that environment fails before any of its code runs, with
|
|
66
|
+
`bad interpreter` or `No module named ...`. Your graphs are fine; the environment has
|
|
67
|
+
to be rebuilt on the new Python:
|
|
68
|
+
|
|
69
|
+
| Installed with | Rebuild with |
|
|
70
|
+
|---|---|
|
|
71
|
+
| pipx | `pipx reinstall-all --python python3` (or the new Python's full path) |
|
|
72
|
+
| pipx, when `pipx` itself is broken too | `uvx pipx reinstall-all --python python3` |
|
|
73
|
+
| uv | `uv tool install --reinstall --python 3.13 --managed-python throughline-transform --with-executables-from throughline` |
|
|
74
|
+
|
|
75
|
+
An install made with uv's `--managed-python` does not hit this: the operating system
|
|
76
|
+
does not touch the Python uv manages. `tl doctor` (throughline releases after 6.0.0) says
|
|
77
|
+
which Python runs `tl` and how it was installed.
|
|
78
|
+
|
|
54
79
|
## What it does not do
|
|
55
80
|
|
|
56
81
|
**It never renders an item's words.** The Markdown is asked of `tl docs` over a
|
|
@@ -86,7 +111,6 @@ second, and is run as a command — its command line is the surface it publishes
|
|
|
86
111
|
| `xlsx` | The same as sheets, read-only by recommendation with the structure locked and no password. Sorting and filtering stay allowed; a spreadsheet nobody can sort is one nobody can review. |
|
|
87
112
|
| `docx` | A title page with the provenance, a contents field Word fills in, a section per register, a heading per item with its type and status beneath, its words as a quotation, its rationale, its attributes in small print, and one appendix per cited source. |
|
|
88
113
|
| `html` | The same document as one self-contained page with print typography, A4 page rules and a contents list of links. Print it to PDF; the browser numbers the pages. |
|
|
89
|
-
| `assistant` | A folder for an assistant that reads only a few files and cannot run `tl` — Microsoft 365 Copilot in a controlled environment reads at most fifty: one file per register carrying its items exactly as `tl dump` gives them, each with its fingerprint, and a manifest naming the repository, ref, commit and tree state, the file of each register, the `tl` that wrote it, and the change-set form `tl apply` accepts, taken from `tl apply --describe`, with the instruction to answer with a change set quoting each fingerprint and never with rewritten files. `--wrap md` writes each file as Markdown holding one fenced JSON block, for an assistant that will not read a `.json` file. Always a folder, never an archive. |
|
|
90
114
|
| `blocks` | The document's structure as JSON — the same list of headings, quotations, paragraphs, attribute lines, tables and appendices the Word and HTML outputs are built from — for a front end that lays out its own pages. The editor's PDF is laid out from it. |
|
|
91
115
|
|
|
92
116
|
Every output carries the repository, ref, commit, working-tree state and tool
|
|
@@ -4,7 +4,6 @@ NOTICE
|
|
|
4
4
|
README.md
|
|
5
5
|
pyproject.toml
|
|
6
6
|
src/throughline_transform/__init__.py
|
|
7
|
-
src/throughline_transform/assistant.py
|
|
8
7
|
src/throughline_transform/blocks.py
|
|
9
8
|
src/throughline_transform/cli.py
|
|
10
9
|
src/throughline_transform/html.py
|
|
@@ -25,7 +24,6 @@ src/throughline_transform.egg-info/entry_points.txt
|
|
|
25
24
|
src/throughline_transform.egg-info/requires.txt
|
|
26
25
|
src/throughline_transform.egg-info/top_level.txt
|
|
27
26
|
tests/conftest.py
|
|
28
|
-
tests/test_assistant.py
|
|
29
27
|
tests/test_only.py
|
|
30
28
|
tests/test_outputs.py
|
|
31
29
|
tests/test_surface.py
|
|
@@ -17,6 +17,8 @@ import subprocess
|
|
|
17
17
|
import sys
|
|
18
18
|
from pathlib import Path
|
|
19
19
|
|
|
20
|
+
import tomllib
|
|
21
|
+
|
|
20
22
|
import pytest
|
|
21
23
|
|
|
22
24
|
BIN = Path(sys.executable).parent
|
|
@@ -69,13 +71,14 @@ implements = { from = ["system_requirement"], to = ["user_requirement"] }
|
|
|
69
71
|
|
|
70
72
|
"""
|
|
71
73
|
config.write_text(head + model + tail, encoding="utf-8")
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
("
|
|
75
|
-
("
|
|
76
|
-
("
|
|
74
|
+
# tl 6 makes a register with the item type it holds (tl SR-0351).
|
|
75
|
+
for prefix, folder, title, type_ in (
|
|
76
|
+
("INT", "intents", "Intents", "intent"),
|
|
77
|
+
("NG", "non-goals", "Non-goals", "non_goal"),
|
|
78
|
+
("UR", "user-requirements", "User requirements", "user_requirement"),
|
|
79
|
+
("SR", "system-requirements", "System requirements", "system_requirement"),
|
|
77
80
|
):
|
|
78
|
-
_tl(root, "register", "new", prefix, folder, "--title", title)
|
|
81
|
+
_tl(root, "register", "new", prefix, folder, "--title", title, "--type", type_)
|
|
79
82
|
|
|
80
83
|
|
|
81
84
|
def _new(root: Path, prefix: str, type_: str, title: str, text: str, **kw: str) -> str:
|
|
@@ -108,7 +111,8 @@ def plain_graph(tmp_path_factory: pytest.TempPathFactory) -> Path:
|
|
|
108
111
|
_tl(root, "link", sr2, sr1, "--type", "relates")
|
|
109
112
|
_tl(root, "link", sr3, sr1, "--type", "refines")
|
|
110
113
|
_tl(root, "amend", sr1, "--rationale", "Because a second renderer drifts. Rejected: writing it here.")
|
|
111
|
-
|
|
114
|
+
# Sound, not signed: tl 6's --strict also refuses an unsigned item.
|
|
115
|
+
_tl(root, "check")
|
|
112
116
|
return root
|
|
113
117
|
|
|
114
118
|
|
|
@@ -125,7 +129,7 @@ def composed_graph(tmp_path_factory: pytest.TempPathFactory, plain_graph: Path)
|
|
|
125
129
|
ur = _new(root, "UR", "user_requirement", "Cite a clause", "One requirement satisfies a borrowed clause.", ground=intent, ground_type="derives_from")
|
|
126
130
|
sr = _new(root, "SR", "system_requirement", "Satisfies the source", "It does what the clause says.", ground=ur, ground_type="implements", attr_priority="must")
|
|
127
131
|
_tl(root, "link", sr, "src:SR-0001", "--type", "satisfies", compose=True)
|
|
128
|
-
_tl(root, "check",
|
|
132
|
+
_tl(root, "check", compose=True)
|
|
129
133
|
return root
|
|
130
134
|
|
|
131
135
|
|
|
@@ -142,3 +146,19 @@ def git_graph(tmp_path_factory: pytest.TempPathFactory, plain_graph: Path) -> Pa
|
|
|
142
146
|
git("add", ".")
|
|
143
147
|
git("commit", "-q", "-m", "fixture")
|
|
144
148
|
return repo / "idd"
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def born(root: Path) -> str:
|
|
152
|
+
"""The status the fixture graph's tl gave its items at birth: ``draft`` before
|
|
153
|
+
tl 6, ``proposed`` from it. Read from an item, so the suite runs on either."""
|
|
154
|
+
for line in (root / "system-requirements" / "SR-0001.yml").read_text(encoding="utf-8").splitlines():
|
|
155
|
+
if line.startswith("status:"):
|
|
156
|
+
return line.split(":", 1)[1].strip()
|
|
157
|
+
raise AssertionError("SR-0001 has no status")
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def every(root: Path) -> str:
|
|
161
|
+
"""The filter that selects every item, in the language the graph declares."""
|
|
162
|
+
with open(root / "throughline.toml", "rb") as fh:
|
|
163
|
+
project = tomllib.load(fh).get("project", {})
|
|
164
|
+
return "TRUE" if project.get("filter_language") == "gql" else "True"
|
|
@@ -13,6 +13,8 @@ from pathlib import Path
|
|
|
13
13
|
|
|
14
14
|
import pytest
|
|
15
15
|
|
|
16
|
+
from conftest import born, every
|
|
17
|
+
|
|
16
18
|
from throughline_transform import markdown as md
|
|
17
19
|
from throughline_transform.blocks import as_blocks
|
|
18
20
|
from throughline_transform.cli import main, produce
|
|
@@ -84,7 +86,7 @@ def test_markdown_is_written_by_the_tool(plain_graph: Path):
|
|
|
84
86
|
|
|
85
87
|
def test_markdown_keeps_markers_when_asked(plain_graph: Path):
|
|
86
88
|
_, text = _md(plain_graph, markers=True)
|
|
87
|
-
assert "<!-- tl:catalog
|
|
89
|
+
assert f"<!-- tl:catalog {every(plain_graph)} -->" in text and "<!-- tl:end -->" in text
|
|
88
90
|
|
|
89
91
|
|
|
90
92
|
def test_markdown_options_change_the_document(plain_graph: Path):
|
|
@@ -115,7 +117,7 @@ def test_blocks_read_the_shape_of_the_tools_output(plain_graph: Path):
|
|
|
115
117
|
items = [b for b in blocks if b.item]
|
|
116
118
|
assert len(items) == 7
|
|
117
119
|
sr1 = next(b for b in items if b.item["uid"] == "SR-0001")
|
|
118
|
-
assert sr1.heading == 4 and sr1.item["status"] ==
|
|
120
|
+
assert sr1.heading == 4 and sr1.item["status"] == born(plain_graph)
|
|
119
121
|
assert 'a colon, "quotes" & <angles>' in sr1.text
|
|
120
122
|
quotes = [b for b in blocks if b.quote]
|
|
121
123
|
assert any("The tool writes the Markdown." in b.text for b in quotes)
|
|
@@ -234,11 +236,11 @@ def test_notes_are_one_per_item_with_front_matter_and_links(plain_graph: Path):
|
|
|
234
236
|
assert "System requirements/SR-0001.md" in entries and "Intents/INT-0001.md" in entries
|
|
235
237
|
sr2 = entries["System requirements/SR-0002.md"].decode()
|
|
236
238
|
assert sr2.startswith('---\nuid: "SR-0002"\n')
|
|
237
|
-
assert 'priority: "should"' in sr2 and ' - "type/system_requirement"' in sr2 and ' - "status/
|
|
239
|
+
assert 'priority: "should"' in sr2 and ' - "type/system_requirement"' in sr2 and f' - "status/{born(plain_graph)}"' in sr2
|
|
238
240
|
# The body is the tool's block reshaped for a note (SR-0009): a heading,
|
|
239
241
|
# the type and status beneath, no attribute line, the incoming links.
|
|
240
242
|
body = sr2.split("\n---\n", 1)[1]
|
|
241
|
-
assert body.startswith("# SR-0002 — Declare it in \\[\\[sources\\]\\]\nsystem requirement ·
|
|
243
|
+
assert body.startswith(f"# SR-0002 — Declare it in \\[\\[sources\\]\\]\nsystem requirement · {born(plain_graph)}\n")
|
|
242
244
|
assert "**priority**" not in body and "**origin**" not in body
|
|
243
245
|
assert "*Relates:* [[SR-0001]]" in sr2
|
|
244
246
|
assert "*Implements:* [[UR-0002]]" in sr2
|
|
@@ -13,6 +13,8 @@ from pathlib import Path
|
|
|
13
13
|
|
|
14
14
|
import pytest
|
|
15
15
|
|
|
16
|
+
from conftest import born
|
|
17
|
+
|
|
16
18
|
from throughline_transform import project
|
|
17
19
|
from throughline_transform.cli import main
|
|
18
20
|
from throughline_transform.provenance import CLEAN, DIRTY, UNTRACKED, stated
|
|
@@ -31,7 +33,7 @@ def test_blocks_output_is_the_documents_structure(plain_graph: Path, tmp_path: P
|
|
|
31
33
|
items = [b for b in blocks if "item" in b]
|
|
32
34
|
assert len(items) == 7
|
|
33
35
|
sr1 = next(b for b in items if b["item"]["uid"] == "SR-0001")
|
|
34
|
-
assert sr1["heading"] == 4 and sr1["item"]["type"] == "system_requirement" and sr1["item"]["status"] ==
|
|
36
|
+
assert sr1["heading"] == 4 and sr1["item"]["type"] == "system_requirement" and sr1["item"]["status"] == born(plain_graph)
|
|
35
37
|
assert any(b.get("quote") for b in blocks) and any(b.get("small") for b in blocks)
|
|
36
38
|
assert any(b.get("group") and b["text"] == "System requirements" for b in blocks)
|
|
37
39
|
assert any("table" in b for b in blocks) # --body both carries the table of items
|
|
@@ -1,133 +0,0 @@
|
|
|
1
|
-
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
-
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
-
"""The graph handed to an assistant that reads a few files and cannot run tl
|
|
4
|
-
(UR-0008, SR-0017, SR-0018).
|
|
5
|
-
|
|
6
|
-
Such an assistant — Microsoft 365 Copilot in a controlled environment reads at
|
|
7
|
-
most fifty files, runs no command and returns only text — has to read the whole
|
|
8
|
-
graph from a handful of files and be told, in those files, how to send changes
|
|
9
|
-
back. This form is a folder: one file per register, each carrying that
|
|
10
|
-
register's items exactly as ``tl dump`` gives them, fingerprint included, and a
|
|
11
|
-
manifest that says what the export was true of, which file holds which
|
|
12
|
-
register, which tl wrote it, and the change-set form ``tl apply`` accepts —
|
|
13
|
-
taken from the tool, never written here, so it cannot drift from what apply
|
|
14
|
-
reads. One file per register because the assistant's cap counts files, not
|
|
15
|
-
items; a folder rather than an archive because an assistant cannot open one.
|
|
16
|
-
|
|
17
|
-
Nothing of an item is reshaped or computed here (NG-0001): the words and the
|
|
18
|
-
fingerprint are the dump's. What this module adds is the file boundaries, the
|
|
19
|
-
wrapping, and the manifest.
|
|
20
|
-
"""
|
|
21
|
-
|
|
22
|
-
from __future__ import annotations
|
|
23
|
-
|
|
24
|
-
import json
|
|
25
|
-
from typing import Any
|
|
26
|
-
|
|
27
|
-
from .model import prefix_of
|
|
28
|
-
from .package import Entry, utf8
|
|
29
|
-
from .provenance import Provenance
|
|
30
|
-
|
|
31
|
-
#: How each file is written: JSON, or Markdown holding one fenced JSON block for
|
|
32
|
-
#: an assistant that will not read a ``.json`` file.
|
|
33
|
-
WRAPS = ("json", "md")
|
|
34
|
-
|
|
35
|
-
#: The version of this form, stated in the manifest.
|
|
36
|
-
FORM_VERSION = 1
|
|
37
|
-
|
|
38
|
-
MANIFEST = "manifest"
|
|
39
|
-
|
|
40
|
-
#: What the manifest tells the assistant to do, beside the form it must write.
|
|
41
|
-
INSTRUCTION = (
|
|
42
|
-
"Read every file named under \"files\" before you answer — each has the same "
|
|
43
|
-
"extension as this manifest: together they are the whole graph as it stood at "
|
|
44
|
-
"the commit named under \"provenance\". Send changes "
|
|
45
|
-
"back as one change set in the form given under \"change_set_format\", quoting "
|
|
46
|
-
"each item's \"fingerprint\" exactly as these files give it. Never send a "
|
|
47
|
-
"rewritten item file, and never a file at all: a change set is text, and the "
|
|
48
|
-
"person who gave you this folder will apply it."
|
|
49
|
-
)
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
def _json(data: dict[str, Any]) -> str:
|
|
53
|
-
return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
def _entry(name: str, title: str, data: dict[str, Any], wrap: str, after: str = "") -> Entry:
|
|
57
|
-
"""One file of the folder: the JSON itself, or Markdown holding it in one
|
|
58
|
-
fenced block, with ``after`` — Markdown of its own — following the block."""
|
|
59
|
-
text = _json(data)
|
|
60
|
-
if wrap == "json":
|
|
61
|
-
return (f"{name}.json", utf8(text))
|
|
62
|
-
body = f"# {title}\n\n```json\n{text}```\n"
|
|
63
|
-
if after:
|
|
64
|
-
body += f"\n{after}"
|
|
65
|
-
return (f"{name}.md", utf8(body))
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
def to_assistant(
|
|
69
|
-
dump: dict[str, Any],
|
|
70
|
-
provenance: Provenance,
|
|
71
|
-
change_set_format: str,
|
|
72
|
-
*,
|
|
73
|
-
wrap: str = "json",
|
|
74
|
-
only: tuple[str, ...] = (),
|
|
75
|
-
) -> list[Entry]:
|
|
76
|
-
"""The folder's files, the manifest first.
|
|
77
|
-
|
|
78
|
-
``dump`` is ``tl dump``'s document, unreshaped; ``change_set_format`` is what
|
|
79
|
-
``tl apply --describe`` printed. With ``only``, the register files hold the
|
|
80
|
-
items named and the clauses they cite, and the manifest says how many of how
|
|
81
|
-
many, as every narrowed output does (SR-0016).
|
|
82
|
-
"""
|
|
83
|
-
if wrap not in WRAPS:
|
|
84
|
-
raise ValueError(f"wrap must be one of {', '.join(WRAPS)}, not {wrap!r}")
|
|
85
|
-
items: list[dict[str, Any]] = list(dump.get("items") or [])
|
|
86
|
-
if only:
|
|
87
|
-
keep = set(only)
|
|
88
|
-
own = [i for i in items if not i.get("source") and i["uid"] in keep]
|
|
89
|
-
cited = {link["target"] for i in own for link in i.get("links") or []}
|
|
90
|
-
items = own + [i for i in items if i.get("source") and i["uid"] in cited]
|
|
91
|
-
registers: list[dict[str, Any]] = list(dump.get("registers") or [])
|
|
92
|
-
by_register: dict[str, list[dict[str, Any]]] = {r["prefix"]: [] for r in registers}
|
|
93
|
-
borrowed: dict[str, list[dict[str, Any]]] = {}
|
|
94
|
-
for item in items:
|
|
95
|
-
if item.get("source"):
|
|
96
|
-
borrowed.setdefault(str(item["source"]), []).append(item)
|
|
97
|
-
else:
|
|
98
|
-
by_register.setdefault(prefix_of(item["uid"]), []).append(item)
|
|
99
|
-
|
|
100
|
-
files: list[dict[str, Any]] = []
|
|
101
|
-
entries: list[Entry] = []
|
|
102
|
-
for register in registers:
|
|
103
|
-
prefix = register["prefix"]
|
|
104
|
-
title = register.get("title") or prefix
|
|
105
|
-
held = by_register.get(prefix, [])
|
|
106
|
-
entries.append(_entry(prefix, f"{title} ({prefix})", {"register": register, "items": held}, wrap))
|
|
107
|
-
files.append({"file": prefix, "register": prefix, "title": title, "items": len(held)})
|
|
108
|
-
for namespace, clauses in sorted(borrowed.items()):
|
|
109
|
-
name = f"source-{namespace}"
|
|
110
|
-
entries.append(
|
|
111
|
-
_entry(name, f"Clauses of the adopted source {namespace}", {"source": namespace, "items": clauses}, wrap)
|
|
112
|
-
)
|
|
113
|
-
files.append({"file": name, "source": namespace, "items": len(clauses)})
|
|
114
|
-
|
|
115
|
-
meta = dump.get("throughline_dump") or {}
|
|
116
|
-
# The manifest is the same in either wrapping, so a file is named by its stem:
|
|
117
|
-
# the reader holds the files, and sees their kind.
|
|
118
|
-
manifest: dict[str, Any] = {
|
|
119
|
-
"throughline_assistant_form": FORM_VERSION,
|
|
120
|
-
"provenance": provenance.record(),
|
|
121
|
-
"provenance_lines": provenance.lines(),
|
|
122
|
-
"tl": str(meta.get("tool_version") or "?"),
|
|
123
|
-
"dump_schema_version": meta.get("dump_schema_version"),
|
|
124
|
-
"files": files,
|
|
125
|
-
"config": dump.get("config") or {},
|
|
126
|
-
}
|
|
127
|
-
if dump.get("composition"):
|
|
128
|
-
manifest["composition"] = dump["composition"]
|
|
129
|
-
manifest["instruction"] = INSTRUCTION
|
|
130
|
-
manifest["change_set_format"] = change_set_format
|
|
131
|
-
readable = f"## How to answer\n\n{INSTRUCTION}\n\n{change_set_format}" if wrap == "md" else ""
|
|
132
|
-
entries.insert(0, _entry(MANIFEST, "Manifest", manifest, wrap, readable))
|
|
133
|
-
return entries
|
|
@@ -1,149 +0,0 @@
|
|
|
1
|
-
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
-
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
-
"""The assistant form (UR-0008, SR-0017, SR-0018): one file per register, each
|
|
4
|
-
carrying the register's items exactly as ``tl dump`` gives them, and a manifest
|
|
5
|
-
that says what the folder was true of and how to answer."""
|
|
6
|
-
|
|
7
|
-
from __future__ import annotations
|
|
8
|
-
|
|
9
|
-
import json
|
|
10
|
-
import re
|
|
11
|
-
import subprocess
|
|
12
|
-
import sys
|
|
13
|
-
from pathlib import Path
|
|
14
|
-
|
|
15
|
-
from throughline_transform.assistant import FORM_VERSION, INSTRUCTION, to_assistant
|
|
16
|
-
from throughline_transform.cli import main
|
|
17
|
-
from throughline_transform.project import change_set_format, load, run
|
|
18
|
-
from throughline_transform.provenance import CLEAN, Provenance, provenance_of
|
|
19
|
-
|
|
20
|
-
PROV = Provenance(repository="example/fixture", ref="main", commit="0" * 40, tree=CLEAN, tool="tl 2.2.0")
|
|
21
|
-
FENCE = re.compile(r"^```json\n(.*?)^```\n", re.S | re.M)
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
def _dump(root: Path) -> dict:
|
|
25
|
-
return json.loads(run(root, ["dump"], False))
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
def _folder(root: Path, out: Path, *extra: str) -> dict[str, str]:
|
|
29
|
-
assert main(["assistant", "-C", str(root), "-o", str(out), *extra]) == 0
|
|
30
|
-
assert out.is_dir() and not out.with_suffix(".zip").exists()
|
|
31
|
-
return {p.name: p.read_text(encoding="utf-8") for p in sorted(out.iterdir())}
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
def _block(text: str) -> dict:
|
|
35
|
-
blocks = FENCE.findall(text)
|
|
36
|
-
assert len(blocks) == 1, "one fenced JSON block per file"
|
|
37
|
-
return json.loads(blocks[0])
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
# --- SR-0017: one file per register, the dump's items unreshaped ----------------
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
def test_the_folder_holds_one_file_per_register_and_the_manifest(plain_graph: Path, tmp_path: Path):
|
|
44
|
-
files = _folder(plain_graph, tmp_path / "form")
|
|
45
|
-
dump = _dump(plain_graph)
|
|
46
|
-
prefixes = [r["prefix"] for r in dump["registers"]]
|
|
47
|
-
assert sorted(files) == sorted([f"{p}.json" for p in prefixes] + ["manifest.json"])
|
|
48
|
-
seen = []
|
|
49
|
-
for prefix in prefixes:
|
|
50
|
-
data = json.loads(files[f"{prefix}.json"])
|
|
51
|
-
assert data["register"]["prefix"] == prefix
|
|
52
|
-
for item in data["items"]:
|
|
53
|
-
assert item["uid"].startswith(prefix + "-")
|
|
54
|
-
seen.append(item)
|
|
55
|
-
# every item, and every link on it, appears exactly once and unchanged
|
|
56
|
-
assert sorted(seen, key=lambda i: i["uid"]) == dump["items"]
|
|
57
|
-
assert all("fingerprint" in item for item in seen)
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
def test_md_wrapping_holds_the_same_content_in_one_fenced_block(plain_graph: Path, tmp_path: Path):
|
|
61
|
-
as_json = _folder(plain_graph, tmp_path / "json")
|
|
62
|
-
as_md = _folder(plain_graph, tmp_path / "md", "--wrap", "md")
|
|
63
|
-
assert sorted(as_md) == sorted(n.replace(".json", ".md") for n in as_json)
|
|
64
|
-
for name, text in as_json.items():
|
|
65
|
-
assert _block(as_md[name.replace(".json", ".md")]) == json.loads(text)
|
|
66
|
-
# the manifest's Markdown also states the form in words the assistant can read
|
|
67
|
-
assert "## How to answer" in as_md["manifest.md"] and "`tl apply` accepts" in as_md["manifest.md"]
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
def test_a_composed_graph_lends_its_clauses_in_a_file_of_their_source(composed_graph: Path, tmp_path: Path):
|
|
71
|
-
files = _folder(composed_graph, tmp_path / "form")
|
|
72
|
-
dump = json.loads(run(composed_graph, ["dump"], True))
|
|
73
|
-
assert "source-src.json" in files
|
|
74
|
-
clauses = json.loads(files["source-src.json"])["items"]
|
|
75
|
-
assert [c["uid"] for c in clauses] == [i["uid"] for i in dump["items"] if i.get("source")]
|
|
76
|
-
own = [i for name, text in files.items() if name not in ("manifest.json", "source-src.json")
|
|
77
|
-
for i in json.loads(text)["items"]]
|
|
78
|
-
assert sorted(i["uid"] for i in own) == sorted(i["uid"] for i in dump["items"] if not i.get("source"))
|
|
79
|
-
manifest = json.loads(files["manifest.json"])
|
|
80
|
-
assert any(f.get("source") == "src" for f in manifest["files"])
|
|
81
|
-
assert manifest["composition"]["sources"][0]["namespace"] == "src"
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
def test_only_narrows_the_files_and_the_manifest_says_so(plain_graph: Path, tmp_path: Path):
|
|
85
|
-
graph = load(plain_graph)
|
|
86
|
-
sr1 = graph.by_register["SR"][0].uid
|
|
87
|
-
files = _folder(plain_graph, tmp_path / "form", "--only", sr1)
|
|
88
|
-
held = [i["uid"] for name, text in files.items() if name != "manifest.json" for i in json.loads(text)["items"]]
|
|
89
|
-
assert held == [sr1]
|
|
90
|
-
manifest = json.loads(files["manifest.json"])
|
|
91
|
-
assert manifest["provenance"]["items"] == f"1 of {len(graph.items)}"
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
def test_the_form_is_a_folder_never_an_archive(plain_graph: Path, tmp_path: Path):
|
|
95
|
-
out = tmp_path / "form"
|
|
96
|
-
assert main(["assistant", "-C", str(plain_graph), "-o", str(out), "--folder"]) == 0
|
|
97
|
-
assert out.is_dir()
|
|
98
|
-
assert main(["assistant", "-C", str(plain_graph), "-o", str(tmp_path / "again")]) == 0
|
|
99
|
-
assert (tmp_path / "again").is_dir() and not list(tmp_path.glob("*.zip"))
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
def test_the_same_graph_gives_the_same_bytes(plain_graph: Path, tmp_path: Path):
|
|
103
|
-
first = _folder(plain_graph, tmp_path / "a", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
|
|
104
|
-
second = _folder(plain_graph, tmp_path / "b", "--repository", "x/y", "--ref", "main", "--commit", "0" * 40, "--tree", "clean")
|
|
105
|
-
assert first == second
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
# --- SR-0018: the manifest -------------------------------------------------------
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
def test_the_manifest_names_what_the_folder_was_true_of_and_how_to_answer(git_graph: Path, tmp_path: Path):
|
|
112
|
-
files = _folder(git_graph, tmp_path / "form")
|
|
113
|
-
manifest = json.loads(files["manifest.json"])
|
|
114
|
-
expected = provenance_of(git_graph, "x")
|
|
115
|
-
assert manifest["throughline_assistant_form"] == FORM_VERSION
|
|
116
|
-
assert manifest["provenance"]["repository"] == expected.repository == "example/fixture"
|
|
117
|
-
assert manifest["provenance"]["ref"] == expected.ref
|
|
118
|
-
assert manifest["provenance"]["commit"] == expected.commit and len(expected.commit) == 40
|
|
119
|
-
assert manifest["provenance"]["tree"] == expected.tree
|
|
120
|
-
assert manifest["tl"] == load(git_graph).tool_version
|
|
121
|
-
assert {f["register"] for f in manifest["files"]} == {r.prefix for r in load(git_graph).registers}
|
|
122
|
-
assert all((tmp_path / "form" / f"{f['file']}.json").is_file() for f in manifest["files"])
|
|
123
|
-
assert manifest["instruction"] == INSTRUCTION
|
|
124
|
-
assert "fingerprint" in manifest["instruction"] and "change set" in manifest["instruction"]
|
|
125
|
-
# the form is the tool's own words, taken from the command, never written here
|
|
126
|
-
assert manifest["change_set_format"] == change_set_format(git_graph, False)
|
|
127
|
-
described = subprocess.run([str(Path(sys.executable).parent / "tl"), "apply", "--describe"],
|
|
128
|
-
capture_output=True, text=True, encoding="utf-8")
|
|
129
|
-
assert manifest["change_set_format"] == described.stdout
|
|
130
|
-
assert '"op": "amend"' in manifest["change_set_format"]
|
|
131
|
-
assert "config" in manifest and "grounding" in manifest["config"]
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
def test_a_stated_provenance_is_written_as_given(plain_graph: Path, tmp_path: Path):
|
|
135
|
-
files = _folder(plain_graph, tmp_path / "form", "--repository", "octo/graph", "--ref", "main",
|
|
136
|
-
"--commit", "f" * 40, "--tree", "dirty")
|
|
137
|
-
manifest = json.loads(files["manifest.json"])
|
|
138
|
-
assert manifest["provenance"] == {"repository": "octo/graph", "ref": "main", "commit": "f" * 40,
|
|
139
|
-
"tree": "uncommitted changes", "tool": manifest["provenance"]["tool"]}
|
|
140
|
-
assert "Working tree: uncommitted changes" in manifest["provenance_lines"]
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
def test_the_writer_reshapes_nothing(plain_graph: Path):
|
|
144
|
-
dump = _dump(plain_graph)
|
|
145
|
-
entries = dict(to_assistant(dump, PROV, "THE FORM"))
|
|
146
|
-
assert set(entries) == {f"{r['prefix']}.json" for r in dump["registers"]} | {"manifest.json"}
|
|
147
|
-
items = [i for name, data in entries.items() if name != "manifest.json" for i in json.loads(data)["items"]]
|
|
148
|
-
assert sorted(items, key=lambda i: i["uid"]) == dump["items"]
|
|
149
|
-
assert json.loads(entries["manifest.json"])["change_set_format"] == "THE FORM"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/__init__.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/blocks.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/html.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/notes.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/office.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/package.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/progress.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/provenance.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/shape.py
RENAMED
|
File without changes
|
{throughline_transform-0.6.0 → throughline_transform-0.7.1}/src/throughline_transform/tables.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|