tro-utils 0.5.2__tar.gz → 0.5.3__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.
Files changed (91) hide show
  1. {tro_utils-0.5.2 → tro_utils-0.5.3}/PKG-INFO +2 -1
  2. {tro_utils-0.5.2 → tro_utils-0.5.3}/README.md +7 -3
  3. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/installation.md +1 -1
  4. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/usage.md +88 -2
  5. {tro_utils-0.5.2 → tro_utils-0.5.3}/pyproject.toml +1 -0
  6. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/conftest.py +3 -1
  7. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_cli.py +115 -0
  8. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_performances.py +54 -0
  9. tro_utils-0.5.3/tests/test_tro_signature_verification.py +871 -0
  10. tro_utils-0.5.3/tests/test_tro_timestamping.py +345 -0
  11. tro_utils-0.5.3/tests/test_trs_keys.py +207 -0
  12. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/_version.py +3 -3
  13. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/cli.py +189 -8
  14. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/tro.py +3 -1
  15. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/tro_utils.py +309 -7
  16. tro_utils-0.5.3/tro_utils/trs_keys.py +251 -0
  17. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/PKG-INFO +2 -1
  18. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/SOURCES.txt +3 -0
  19. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/requires.txt +1 -0
  20. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/scm_file_list.json +4 -1
  21. tro_utils-0.5.3/tro_utils.egg-info/scm_version.json +8 -0
  22. tro_utils-0.5.2/tests/test_tro_timestamping.py +0 -167
  23. tro_utils-0.5.2/tro_utils.egg-info/scm_version.json +0 -8
  24. {tro_utils-0.5.2 → tro_utils-0.5.3}/.coveragerc +0 -0
  25. {tro_utils-0.5.2 → tro_utils-0.5.3}/.editorconfig +0 -0
  26. {tro_utils-0.5.2 → tro_utils-0.5.3}/.github/ISSUE_TEMPLATE.md +0 -0
  27. {tro_utils-0.5.2 → tro_utils-0.5.3}/.github/workflows/release.yml +0 -0
  28. {tro_utils-0.5.2 → tro_utils-0.5.3}/.github/workflows/test.yml +0 -0
  29. {tro_utils-0.5.2 → tro_utils-0.5.3}/.gitignore +0 -0
  30. {tro_utils-0.5.2 → tro_utils-0.5.3}/.readthedocs.yaml +0 -0
  31. {tro_utils-0.5.2 → tro_utils-0.5.3}/.travis.yml +0 -0
  32. {tro_utils-0.5.2 → tro_utils-0.5.3}/LICENSE +0 -0
  33. {tro_utils-0.5.2 → tro_utils-0.5.3}/MANIFEST.in +0 -0
  34. {tro_utils-0.5.2 → tro_utils-0.5.3}/Makefile +0 -0
  35. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/Makefile +0 -0
  36. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/authors.md +0 -0
  37. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/conf.py +0 -0
  38. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/contributing.md +0 -0
  39. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/history.md +0 -0
  40. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/index.md +0 -0
  41. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/make.bat +0 -0
  42. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/readme.md +0 -0
  43. {tro_utils-0.5.2 → tro_utils-0.5.3}/docs/requirements.txt +0 -0
  44. {tro_utils-0.5.2 → tro_utils-0.5.3}/pytest.ini +0 -0
  45. {tro_utils-0.5.2 → tro_utils-0.5.3}/requirements_dev.txt +0 -0
  46. {tro_utils-0.5.2 → tro_utils-0.5.3}/setup.cfg +0 -0
  47. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/__init__.py +0 -0
  48. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/helpers.py +0 -0
  49. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_arrangement_determinism.py +0 -0
  50. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_extra_context.py +0 -0
  51. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_agent.py +0 -0
  52. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_artifact_arrangement.py +0 -0
  53. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_artifact_composition.py +0 -0
  54. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_artifact_location.py +0 -0
  55. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_composition_fingerprint.py +0 -0
  56. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_hash_value.py +0 -0
  57. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_performance.py +0 -0
  58. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_research_artifact.py +0 -0
  59. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_transparent_research_object.py +0 -0
  60. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_trs.py +0 -0
  61. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_models_tsa.py +0 -0
  62. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_replication_package_model.py +0 -0
  63. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_replication_package_verification.py +0 -0
  64. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_arrangements.py +0 -0
  65. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_creation.py +0 -0
  66. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_hashing.py +0 -0
  67. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_reporting.py +0 -0
  68. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_save_load.py +0 -0
  69. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_signing.py +0 -0
  70. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_utility_methods.py +0 -0
  71. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_tro_workflow.py +0 -0
  72. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_trs_identifier.py +0 -0
  73. {tro_utils-0.5.2 → tro_utils-0.5.3}/tests/test_version.py +0 -0
  74. {tro_utils-0.5.2 → tro_utils-0.5.3}/tox.ini +0 -0
  75. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/__init__.py +0 -0
  76. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/default.jinja2 +0 -0
  77. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/__init__.py +0 -0
  78. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/_base.py +0 -0
  79. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/agent.py +0 -0
  80. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/arrangement.py +0 -0
  81. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/artifact.py +0 -0
  82. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/attribute.py +0 -0
  83. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/composition.py +0 -0
  84. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/hash_value.py +0 -0
  85. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/performance.py +0 -0
  86. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/trs.py +0 -0
  87. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/models/tsa.py +0 -0
  88. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils/replication_package.py +0 -0
  89. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/dependency_links.txt +0 -0
  90. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/entry_points.txt +0 -0
  91. {tro_utils-0.5.2 → tro_utils-0.5.3}/tro_utils.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tro-utils
3
- Version: 0.5.2
3
+ Version: 0.5.3
4
4
  Summary: Utilities for creating, editing and interacting with TROs
5
5
  Author-email: Kacper Kowalik <xarthisius.kk@gmail.com>, Craig Willis <willis8@illinois.edu>
6
6
  Maintainer-email: Kacper Kowalik <xarthisius.kk@gmail.com>
@@ -54,6 +54,7 @@ Requires-Dist: requests
54
54
  Requires-Dist: packaging
55
55
  Requires-Dist: python-gnupg
56
56
  Requires-Dist: python-magic
57
+ Requires-Dist: pyyaml
57
58
  Requires-Dist: rfc3161ng
58
59
  Requires-Dist: graphviz
59
60
  Requires-Dist: rich
@@ -14,7 +14,9 @@ It uses the `Click` library to define commands and options. Here's a summary of
14
14
 
15
15
  2. **Commands**: The script defines several commands, each with its own set of options and arguments. The commands include:
16
16
 
17
- - `verify-timestamp`: Verifies the RFC 3161 timestamp and GPG signature on the TRO.
17
+ - `verify-timestamp`: Verifies the RFC 3161 timestamp on the TRO.
18
+
19
+ - `verify-signature`: Verifies the TRS's GPG signature on the TRO against your keyring. Import the TRS's public key from a source you trust first, or pass the key file the TRS publishes with `--keyring`; `--fingerprint` requires a given signing key. `--trs-keys` checks the key against a list of the TRS's keys with their validity dates, at the time of the TRO's timestamp. `--use-embedded-key` alone only checks that the TRO is self-consistent.
18
20
 
19
21
  - `verify-package`: Verifies a replication package (directory or `.zip`) against the hashes stored in an arrangement.
20
22
 
@@ -22,7 +24,7 @@ It uses the `Click` library to define commands and options. Here's a summary of
22
24
 
23
25
  - `composition`: Manages compositions in the TRO. It has a subcommand `info` that gets info about the current composition.
24
26
 
25
- - `performance`: Manages performances in the TRO. It has a subcommand `add` that adds a performance to the TRO.
27
+ - `performance`: Manages performances in the TRO. Subcommands: `add` (adds a performance to the TRO) and `list` (lists the performances recorded in the TRO; `-v` also shows start/end times, accessed and contributed arrangements with their mount paths, and performance attributes).
26
28
 
27
29
  - `sign`: Signs the TRO. This records the public half of the signing key as `trov:publicKey` in the declaration, saves the declaration, and then produces the signature and the RFC 3161 timestamp over it.
28
30
 
@@ -59,7 +61,7 @@ $ brew install gnupg openssl python3 # on macOS with Home
59
61
  ```
60
62
 
61
63
  If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
62
- GPG is not required; OpenSSL still is.
64
+ GPG is not required; OpenSSL still is. `verify-signature` needs GPG.
63
65
 
64
66
  ## Example Usage
65
67
 
@@ -127,6 +129,8 @@ $ tro-utils --declaration sample_tro.jsonld performance add \
127
129
  -a trov:InternetAccessRecording \
128
130
  -A arrangement/0 \
129
131
  -M arrangement/1
132
+ $ tro-utils --declaration sample_tro.jsonld performance list
133
+ Performance(id=trp/0): My magic workflow
130
134
  $ tro-utils --declaration sample_tro.jsonld sign
131
135
  $ tro-utils --declaration sample_tro.jsonld verify-timestamp
132
136
  ...
@@ -15,7 +15,7 @@ $ brew install gnupg openssl python3 # on macOS with Home
15
15
  ```
16
16
 
17
17
  If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
18
- GPG is not required; OpenSSL still is.
18
+ GPG is not required; OpenSSL still is. `verify-signature` needs GPG.
19
19
 
20
20
  ## Stable release
21
21
 
@@ -79,7 +79,61 @@ the default `schema:creator` reference.
79
79
  ```
80
80
  tro-utils verify-timestamp <declaration>
81
81
  ```
82
- Verifies the RFC 3161 timestamp and GPG signature on the TRO.
82
+ Verifies the RFC 3161 timestamp on the TRO.
83
+
84
+ ```
85
+ tro-utils verify-signature <declaration> [--gnupghome DIR | --keyring FILE | --use-embedded-key] [--fingerprint FPR ...] [--trs-keys FILE]
86
+ ```
87
+ Verifies the TRS's GPG signature against the declaration as stored on disk.
88
+ How a TRS key comes to be trusted (the TRS's website, a registry, a fingerprint
89
+ published by a journal) is up to you, so tro-utils does not trust the
90
+ `trov:publicKey` embedded in the TRO. Where the key is looked up:
91
+
92
+ - By default, in your keyring (or in `--gnupghome`). If the key is missing, the
93
+ command fails and prints its fingerprint; GnuPG is not allowed to fetch it by
94
+ itself. If the key is in your keyring but you have not certified it
95
+ (`gpg --lsign-key`), the command warns.
96
+ - `--keyring FILE`: only in a key file you obtained from the TRS, armored
97
+ (`.asc`) or binary (`.gpg`). Your own keyring is neither used nor changed.
98
+ - `--use-embedded-key`: in the key embedded in the TRO, which on its own only
99
+ shows that the TRO is self-consistent, not who signed it.
100
+
101
+ `--fingerprint` gives the fingerprint the signing key must have, as the TRS
102
+ publishes it (spaces are ignored; it can be given more than once, e.g. across
103
+ a key change). A signature by any other key fails. With a fingerprint you
104
+ trust, even `--use-embedded-key` is a sound check, e.g. for a SIVACOR TRO:
105
+
106
+ ```
107
+ tro-utils verify-signature tro/tro-<id>.jsonld --use-embedded-key \
108
+ --fingerprint "F7DB 4853 9F20 7AD4 612D C408 D8BB 2071 862A FF4A"
109
+ ```
110
+
111
+ `--trs-keys FILE` goes further: it reads a key list saying which keys a TRS
112
+ signed with and when, as JSON, or as YAML if the file ends in `.yaml`/`.yml`.
113
+ The key is judged at the time of the TRO's trusted timestamp (the `.tsr`, which
114
+ is verified too), not by its current OpenPGP state, so a TRO signed before a
115
+ key was retired, or before it was compromised, still verifies. Unless
116
+ `--keyring` or `--gnupghome` is given, the key embedded in the TRO is used,
117
+ since the list vouches for its fingerprint.
118
+
119
+ ```yaml
120
+ format: https://w3id.org/trace/trs-keys/v1
121
+ updated: 2026-11-16T00:00:00Z
122
+ systems:
123
+ - ids: [https://sivacor.org/] # every @id the TRS has used in trov:wasAssembledBy
124
+ name: SIVACOR
125
+ keys:
126
+ - fingerprint: F7DB 4853 9F20 7AD4 612D C408 D8BB 2071 862A FF4A
127
+ valid_from: 2025-11-13 # a bare date is midnight UTC
128
+ status: current # or retired (needs valid_until),
129
+ # or compromised (needs compromised_since)
130
+ ```
131
+
132
+ The signature fails if the list has no entry for the TRO's TRS, if the signing
133
+ key is not listed for it, if the timestamp falls outside the key's
134
+ `valid_from`..`valid_until`, or if it is at or after `compromised_since`. A
135
+ key compromised only after the timestamp passes with a warning. Without a
136
+ `.tsr`, only a `current` key passes, with a warning.
83
137
 
84
138
  ```
85
139
  tro-utils verify-package <declaration> <package> [-a ARRANGEMENT] [-s SUBPATH] [-v]
@@ -102,8 +156,10 @@ Shows artifacts in the current composition with their MIME type and hash.
102
156
 
103
157
  ```
104
158
  tro-utils performance add [-m COMMENT] [-s START] [-e END] [-a ATTRIBUTE] [-A ACCESSED] [-M CONTRIBUTED]
159
+ tro-utils performance list [-v]
105
160
  ```
106
- Records a `TrustedResearchPerformance` entry in the TRO.
161
+ `add` records a `TrustedResearchPerformance` entry in the TRO; `list` lists the recorded
162
+ performances.
107
163
  `-A` and `-M` can be repeated to reference multiple input or output arrangements:
108
164
 
109
165
  ```bash
@@ -113,6 +169,23 @@ tro-utils --declaration my.jsonld performance add \
113
169
  -M arrangement/2
114
170
  ```
115
171
 
172
+ `performance list` prints one line per performance; `-v` adds the start and end times, the
173
+ accessed and contributed arrangements (with their mount paths, if bound), and the
174
+ performance attributes:
175
+
176
+ ```
177
+ $ tro-utils --declaration my.jsonld performance list -v
178
+ Performance(id=trp/0): Processing run
179
+ - Started: 2024-03-01T09:22:01+00:00
180
+ - Ended: 2024-03-02T10:00:11+00:00
181
+ - Accessed:
182
+ - arrangement/0 (bound to /mnt/input)
183
+ - Contributed to:
184
+ - arrangement/1
185
+ - Attributes:
186
+ - trov:InternetIsolation
187
+ ```
188
+
116
189
  ```
117
190
  tro-utils sign
118
191
  ```
@@ -306,12 +379,25 @@ tro.add_performance(
306
379
  modified_arrangement="arrangement/1", # str | (id, path) tuple | list | None
307
380
  )
308
381
 
382
+ # List what has been recorded (JSON-LD dicts, in insertion order).
383
+ # trov:accessedArrangement / trov:contributedToArrangement are always lists here.
384
+ for a in tro.list_arrangements():
385
+ print(a["@id"], a["rdfs:comment"])
386
+ for p in tro.list_performances():
387
+ print(p["@id"], p["rdfs:comment"], p.get("trov:startedAtTime"))
388
+ for b in p["trov:accessedArrangement"]:
389
+ print(" accessed", b["trov:arrangement"]["@id"], b.get("trov:boundTo"))
390
+
309
391
  # Save, sign, and timestamp. request_timestamp() attaches trov:publicKey and
310
392
  # re-saves the declaration before signing, so the .sig and .tsr always cover the
311
393
  # declaration as it exists on disk.
312
394
  tro.save()
313
395
  tro.request_timestamp()
314
396
  tro.verify_timestamp() # needs neither a key nor the gpg binary
397
+ tro.verify_signature() # needs the TRS's key in your keyring
398
+ tro.verify_signature(keyring="trs.asc") # only the keys in that file
399
+ tro.verify_signature(fingerprints=["<full fingerprint published by the TRS>"])
400
+ tro.verify_signature(trs_keys="trs-keys.yaml") # judged at the timestamp's time
315
401
 
316
402
  # Verify a replication package
317
403
  result = tro.verify_replication_package(
@@ -21,6 +21,7 @@ dependencies = [
21
21
  "packaging",
22
22
  "python-gnupg",
23
23
  "python-magic",
24
+ "pyyaml",
24
25
  "rfc3161ng",
25
26
  "graphviz",
26
27
  "rich",
@@ -5,6 +5,7 @@ import json
5
5
  import gnupg
6
6
  import pytest
7
7
 
8
+ from tro_utils.tro_utils import _kill_gpg_agent
8
9
 
9
10
  # ---------------------------------------------------------------------------
10
11
  # Fixtures
@@ -64,13 +65,14 @@ def gpg_setup(tmp_path_factory):
64
65
  keyid = k["keyid"]
65
66
  break
66
67
 
67
- return {
68
+ yield {
68
69
  "gpg_home": str(gpg_home),
69
70
  "gpg": gpg,
70
71
  "fingerprint": fingerprint,
71
72
  "keyid": keyid,
72
73
  "passphrase": "test_passphrase",
73
74
  }
75
+ _kill_gpg_agent(str(gpg_home))
74
76
 
75
77
 
76
78
  @pytest.fixture(scope="session")
@@ -669,6 +669,121 @@ class TestCLIPerformance:
669
669
  assert by_id["arrangement/0"]["trov:boundTo"] == "/mnt/a"
670
670
  assert "trov:boundTo" not in by_id["arrangement/1"]
671
671
 
672
+ def _add_performance(self, runner, tro_file, comment, *extra):
673
+ result = runner.invoke(
674
+ cli,
675
+ [
676
+ "--declaration",
677
+ str(tro_file),
678
+ "performance",
679
+ "add",
680
+ "--comment",
681
+ comment,
682
+ "--start",
683
+ "2024-01-01T10:00:00+00:00",
684
+ "--end",
685
+ "2024-01-01T11:00:00+00:00",
686
+ *extra,
687
+ ],
688
+ )
689
+ assert result.exit_code == 0, result.output
690
+
691
+ def test_performance_list(self, runner, tmp_path, temp_workspace, trs_profile):
692
+ """performance list prints one line per performance, in order."""
693
+ tro_file = tmp_path / "test_tro.jsonld"
694
+ self._setup_tro_with_arrangements(runner, tro_file, trs_profile, temp_workspace)
695
+ self._add_performance(
696
+ runner, tro_file, "First run", "-A", "arrangement/0", "-M", "arrangement/1"
697
+ )
698
+ self._add_performance(runner, tro_file, "Second run", "-A", "arrangement/1")
699
+ result = runner.invoke(
700
+ cli, ["--declaration", str(tro_file), "performance", "list"]
701
+ )
702
+ assert result.exit_code == 0, result.output
703
+ lines = result.output.splitlines()
704
+ assert lines == [
705
+ "Performance(id=trp/0): First run",
706
+ "Performance(id=trp/1): Second run",
707
+ ]
708
+
709
+ def test_performance_list_verbose(
710
+ self, runner, tmp_path, temp_workspace, trs_profile
711
+ ):
712
+ """performance list -v shows times, bound arrangements and attributes."""
713
+ tro_file = tmp_path / "test_tro.jsonld"
714
+ self._setup_tro_with_arrangements(runner, tro_file, trs_profile, temp_workspace)
715
+ self._add_performance(
716
+ runner,
717
+ tro_file,
718
+ "Run",
719
+ "-a",
720
+ "trov:InternetIsolation",
721
+ "-A",
722
+ "arrangement/0:/mnt/input",
723
+ "-M",
724
+ "arrangement/1",
725
+ )
726
+ # A second run that only reads: no contributed or attribute sections.
727
+ self._add_performance(runner, tro_file, "Read-only", "-A", "arrangement/1")
728
+ result = runner.invoke(
729
+ cli, ["--declaration", str(tro_file), "performance", "list", "-v"]
730
+ )
731
+ assert result.exit_code == 0, result.output
732
+ out, read_only = result.output.split("Performance(id=trp/1): Read-only\n")
733
+ assert "Contributed to:" not in read_only
734
+ assert "Attributes:" not in read_only
735
+ assert " - arrangement/1\n" in read_only
736
+ assert "Performance(id=trp/0): Run" in out
737
+ assert "Started: 2024-01-01T10:00:00+00:00" in out
738
+ assert "Ended: 2024-01-01T11:00:00+00:00" in out
739
+ assert "Accessed:" in out
740
+ assert " - arrangement/0 (bound to /mnt/input)" in out
741
+ assert "Contributed to:" in out
742
+ assert " - arrangement/1\n" in out
743
+ assert "Attributes:" in out
744
+ assert " - trov:InternetIsolation" in out
745
+
746
+ def test_performance_list_empty(
747
+ self, runner, tmp_path, temp_workspace, trs_profile
748
+ ):
749
+ """performance list on a TRO without performances prints nothing."""
750
+ tro_file = tmp_path / "test_tro.jsonld"
751
+ self._setup_tro_with_arrangements(runner, tro_file, trs_profile, temp_workspace)
752
+ result = runner.invoke(
753
+ cli, ["--declaration", str(tro_file), "performance", "list"]
754
+ )
755
+ assert result.exit_code == 0, result.output
756
+ assert result.output == ""
757
+
758
+ def test_performance_list_declaration_without_extension(
759
+ self, runner, tmp_path, temp_workspace, trs_profile
760
+ ):
761
+ """--declaration resolves to <stem>.jsonld, as for every other command."""
762
+ tro_file = tmp_path / "test_tro.jsonld"
763
+ self._setup_tro_with_arrangements(runner, tro_file, trs_profile, temp_workspace)
764
+ self._add_performance(runner, tro_file, "Run")
765
+ result = runner.invoke(
766
+ cli, ["--declaration", str(tmp_path / "test_tro"), "performance", "list"]
767
+ )
768
+ assert result.exit_code == 0, result.output
769
+ assert result.output == "Performance(id=trp/0): Run\n"
770
+
771
+ @pytest.mark.parametrize("group", ["performance", "arrangement"])
772
+ def test_list_missing_declaration(self, runner, tmp_path, group):
773
+ """list fails instead of printing an empty, freshly created TRO."""
774
+ missing = tmp_path / "typo.jsonl"
775
+ result = runner.invoke(cli, ["--declaration", str(missing), group, "list"])
776
+ assert result.exit_code != 0
777
+ assert "does not exist" in result.output
778
+ assert not missing.exists()
779
+
780
+ @pytest.mark.parametrize("group", ["performance", "arrangement"])
781
+ def test_list_without_declaration(self, runner, group):
782
+ """list requires --declaration."""
783
+ result = runner.invoke(cli, [group, "list"])
784
+ assert result.exit_code != 0
785
+ assert "--declaration is required" in result.output
786
+
672
787
 
673
788
  class TestExtraContextCLI:
674
789
  """Tests for --extra-context CLI option."""
@@ -252,3 +252,57 @@ class TestTROPerformances:
252
252
  )
253
253
  perf = tro.data["@graph"][0]["trov:hasPerformance"][0]
254
254
  assert perf["trov:customAttr"] == "customValue"
255
+
256
+ def test_list_performances(self, temp_workspace, tmp_path, gpg_setup, trs_profile):
257
+ """list_performances returns the JSON-LD performances, in order."""
258
+ tro = create_tro_with_gpg(
259
+ filepath=str(tmp_path / "test_tro.jsonld"),
260
+ gpg_setup=gpg_setup,
261
+ profile=trs_profile,
262
+ )
263
+ assert tro.list_performances() == []
264
+
265
+ tro.add_arrangement(str(temp_workspace), comment="A")
266
+ (temp_workspace / "output.txt").write_text("y")
267
+ tro.add_arrangement(str(temp_workspace), comment="B")
268
+ for comment in ("first", "second"):
269
+ tro.add_performance(
270
+ start_time=datetime.datetime(2024, 1, 1, 10, 0, 0),
271
+ end_time=datetime.datetime(2024, 1, 1, 11, 0, 0),
272
+ comment=comment,
273
+ accessed_arrangement="arrangement/0",
274
+ modified_arrangement="arrangement/1",
275
+ )
276
+
277
+ performances = tro.list_performances()
278
+ assert [p["@id"] for p in performances] == ["trp/0", "trp/1"]
279
+ assert [p["rdfs:comment"] for p in performances] == ["first", "second"]
280
+ # Single bindings are serialised as a bare dict in the declaration, but
281
+ # list_performances always returns lists.
282
+ stored = tro.data["@graph"][0]["trov:hasPerformance"][0]
283
+ assert isinstance(stored["trov:accessedArrangement"], dict)
284
+ for p in performances:
285
+ assert [
286
+ b["trov:arrangement"]["@id"] for b in p["trov:accessedArrangement"]
287
+ ] == ["arrangement/0"]
288
+ assert [
289
+ b["trov:arrangement"]["@id"] for b in p["trov:contributedToArrangement"]
290
+ ] == ["arrangement/1"]
291
+
292
+ def test_list_performances_without_bindings(
293
+ self, temp_workspace, tmp_path, gpg_setup, trs_profile
294
+ ):
295
+ """Binding keys are present as empty lists when nothing is bound."""
296
+ tro = create_tro_with_gpg(
297
+ filepath=str(tmp_path / "test_tro.jsonld"),
298
+ gpg_setup=gpg_setup,
299
+ profile=trs_profile,
300
+ )
301
+ tro.add_performance(
302
+ start_time=datetime.datetime(2024, 1, 1, 10, 0, 0),
303
+ end_time=datetime.datetime(2024, 1, 1, 11, 0, 0),
304
+ comment="unbound",
305
+ )
306
+ (perf,) = tro.list_performances()
307
+ assert perf["trov:accessedArrangement"] == []
308
+ assert perf["trov:contributedToArrangement"] == []