tro-utils 0.5.0__tar.gz → 0.5.2__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.0 → tro_utils-0.5.2}/PKG-INFO +1 -1
  2. tro_utils-0.5.2/README.md +173 -0
  3. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/usage.md +25 -3
  4. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/conftest.py +15 -7
  5. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_cli.py +15 -7
  6. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_performance.py +6 -2
  7. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_transparent_research_object.py +4 -1
  8. tro_utils-0.5.2/tests/test_models_trs.py +102 -0
  9. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_creation.py +1 -1
  10. tro_utils-0.5.2/tests/test_tro_reporting.py +164 -0
  11. tro_utils-0.5.2/tests/test_trs_identifier.py +388 -0
  12. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/_version.py +3 -3
  13. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/default.jinja2 +16 -10
  14. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/arrangement.py +1 -1
  15. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/artifact.py +1 -1
  16. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/tro.py +26 -3
  17. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/trs.py +121 -16
  18. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/PKG-INFO +1 -1
  19. tro_utils-0.5.2/tro_utils.egg-info/scm_version.json +8 -0
  20. tro_utils-0.5.0/README.md +0 -121
  21. tro_utils-0.5.0/tests/test_models_trs.py +0 -59
  22. tro_utils-0.5.0/tests/test_tro_reporting.py +0 -67
  23. tro_utils-0.5.0/tests/test_trs_identifier.py +0 -181
  24. tro_utils-0.5.0/tro_utils.egg-info/scm_version.json +0 -8
  25. {tro_utils-0.5.0 → tro_utils-0.5.2}/.coveragerc +0 -0
  26. {tro_utils-0.5.0 → tro_utils-0.5.2}/.editorconfig +0 -0
  27. {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/ISSUE_TEMPLATE.md +0 -0
  28. {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/workflows/release.yml +0 -0
  29. {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/workflows/test.yml +0 -0
  30. {tro_utils-0.5.0 → tro_utils-0.5.2}/.gitignore +0 -0
  31. {tro_utils-0.5.0 → tro_utils-0.5.2}/.readthedocs.yaml +0 -0
  32. {tro_utils-0.5.0 → tro_utils-0.5.2}/.travis.yml +0 -0
  33. {tro_utils-0.5.0 → tro_utils-0.5.2}/LICENSE +0 -0
  34. {tro_utils-0.5.0 → tro_utils-0.5.2}/MANIFEST.in +0 -0
  35. {tro_utils-0.5.0 → tro_utils-0.5.2}/Makefile +0 -0
  36. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/Makefile +0 -0
  37. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/authors.md +0 -0
  38. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/conf.py +0 -0
  39. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/contributing.md +0 -0
  40. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/history.md +0 -0
  41. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/index.md +0 -0
  42. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/installation.md +0 -0
  43. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/make.bat +0 -0
  44. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/readme.md +0 -0
  45. {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/requirements.txt +0 -0
  46. {tro_utils-0.5.0 → tro_utils-0.5.2}/pyproject.toml +0 -0
  47. {tro_utils-0.5.0 → tro_utils-0.5.2}/pytest.ini +0 -0
  48. {tro_utils-0.5.0 → tro_utils-0.5.2}/requirements_dev.txt +0 -0
  49. {tro_utils-0.5.0 → tro_utils-0.5.2}/setup.cfg +0 -0
  50. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/__init__.py +0 -0
  51. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/helpers.py +0 -0
  52. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_arrangement_determinism.py +0 -0
  53. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_extra_context.py +0 -0
  54. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_agent.py +0 -0
  55. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_arrangement.py +0 -0
  56. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_composition.py +0 -0
  57. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_location.py +0 -0
  58. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_composition_fingerprint.py +0 -0
  59. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_hash_value.py +0 -0
  60. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_research_artifact.py +0 -0
  61. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_tsa.py +0 -0
  62. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_replication_package_model.py +0 -0
  63. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_replication_package_verification.py +0 -0
  64. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_arrangements.py +0 -0
  65. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_hashing.py +0 -0
  66. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_performances.py +0 -0
  67. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_save_load.py +0 -0
  68. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_signing.py +0 -0
  69. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_timestamping.py +0 -0
  70. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_utility_methods.py +0 -0
  71. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_workflow.py +0 -0
  72. {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_version.py +0 -0
  73. {tro_utils-0.5.0 → tro_utils-0.5.2}/tox.ini +0 -0
  74. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/__init__.py +0 -0
  75. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/cli.py +0 -0
  76. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/__init__.py +0 -0
  77. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/_base.py +0 -0
  78. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/agent.py +0 -0
  79. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/attribute.py +0 -0
  80. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/composition.py +0 -0
  81. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/hash_value.py +0 -0
  82. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/performance.py +0 -0
  83. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/tsa.py +0 -0
  84. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/replication_package.py +0 -0
  85. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/tro_utils.py +0 -0
  86. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/SOURCES.txt +0 -0
  87. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/dependency_links.txt +0 -0
  88. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/entry_points.txt +0 -0
  89. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/requires.txt +0 -0
  90. {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/scm_file_list.json +0 -0
  91. {tro_utils-0.5.0 → tro_utils-0.5.2}/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.0
3
+ Version: 0.5.2
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>
@@ -0,0 +1,173 @@
1
+ # Transparent Research Object utils
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/tro_utils.svg)](https://pypi.python.org/pypi/tro-utils)
4
+ [![Zenodo](https://zenodo.org/badge/765298086.svg)](https://zenodo.org/doi/10.5281/zenodo.11130420)
5
+ [![Documentation Status](https://readthedocs.org/projects/tro-utils/badge/?version=latest)](https://tro-utils.readthedocs.io/en/latest/?version=latest)
6
+
7
+ This package provides a set of utilities for working with Transparent Research Objects (TROs). It is designed to be used in conjunction with the [TRO specification](https://transparency-certified.github.io/trace-specification/docs/specifications/tro/0.1/index.html).
8
+
9
+ **📚 [Read the Full Documentation](https://tro-utils.readthedocs.io/en/latest/?version=latest)**
10
+
11
+ It uses the `Click` library to define commands and options. Here's a summary of the main features:
12
+
13
+ 1. **Global Options**: The script defines several global options that can be used with any command, such as `--declaration`, `--profile`, `--gpg-fingerprint`, `--gpg-passphrase`, `--tro-creator`, `--tro-creator-type`, `--tro-name`, and `--tro-description`. These options can be used to specify various parameters for the TRO.
14
+
15
+ 2. **Commands**: The script defines several commands, each with its own set of options and arguments. The commands include:
16
+
17
+ - `verify-timestamp`: Verifies the RFC 3161 timestamp and GPG signature on the TRO.
18
+
19
+ - `verify-package`: Verifies a replication package (directory or `.zip`) against the hashes stored in an arrangement.
20
+
21
+ - `arrangement`: Manages arrangements in the TRO. An arrangement is a snapshot of where files sat at one point in time; adding one records a location per file and registers any file the TRO has not seen before in the composition. Subcommands: `add` (scans a directory, or replays a pre-computed snapshot with `--from-snapshot`), `snapshot` (computes a reusable snapshot file from a directory without touching a TRO, so an expensive scan can be done once and shared across runs — see [Arrangement snapshots](https://tro-utils.readthedocs.io/en/latest/usage.html#arrangement-snapshots)) and `list` (lists available arrangements in the TRO).
22
+
23
+ - `composition`: Manages compositions in the TRO. It has a subcommand `info` that gets info about the current composition.
24
+
25
+ - `performance`: Manages performances in the TRO. It has a subcommand `add` that adds a performance to the TRO.
26
+
27
+ - `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
+
29
+ - `report`: Generates a report of the TRO.
30
+
31
+ 3. **TRO Interaction**: The script interacts with the TRO using the `TRO` class from the `tro_utils` module. It uses this class to create a new TRO, add arrangements and performances to the TRO, verify the TRO, and generate a report of the TRO.
32
+
33
+ 4. **GPG is only used for signing**: `--gpg-fingerprint` and `--gpg-passphrase` are recorded but never resolved against a keyring until `sign` runs. Building, inspecting, reporting on and verifying a TRO therefore need no GPG key — and no `gpg` binary at all. As a consequence, `trov:publicKey` appears in the declaration only from `sign` onwards, and is by construction the public half of the key that produced the signature (a value supplied by a TRS profile acts as a default until then).
34
+
35
+ 5. **The TRS is identified by a stable IRI**: the `@id` of the TRS a declaration defines must be an absolute IRI, or a compact IRI whose prefix is not `trov`, so that the same TRS carries the same identifier in every document that mentions it. A bare `"trs"` does not qualify — it resolves against whichever document happens to contain it. The identifier is taken from the profile's `@id`, else its `schema:url`, else a placeholder saying the TRS is unidentified; a non-conforming `@id` is reported rather than quietly replaced, and a declaration carrying one cannot be saved. Whatever the TRS ends up with is also what `trov:wasConductedBy` and the default `schema:creator` reference.
36
+
37
+ 6. **Capabilities are named by an IRI too**: a capability belongs to the TRS, not to one declaration, so the `@id` a profile gives it — and therefore the `trov:warrantedBy` that each performance attribute points at — must be a compact or absolute IRI. The usual identifier is the capability's own term, so a profile may simply omit `@id` and let the `@type` serve. Unlike the TRS `@id`, the `trov` prefix is allowed here. A relative id such as `trs/capability/1` is reported rather than quietly rewritten, and a declaration carrying one cannot be saved.
38
+
39
+ 7. **`schema:creator` is a person or an organization**: it serialises as a `schema:Person` or `schema:Organization` node rather than a bare name, including for defaults. `--tro-creator` supplies the name and `--tro-creator-type` says which of the two it is (default: `organization`); with neither given, the TRO credits the TRS that assembled it, by the TRS's own `@id` and `schema:name`.
40
+
41
+ 8. **Timestamps are timezone-aware**: `trov:startedAtTime`, `trov:endedAtTime` and `schema:dateCreated` always carry a UTC offset. A value given without one — `--start 2024-03-01T09:22:01`, or an offset-less timestamp in an older declaration — is read as local wall-clock time and stamped with the local offset, preserving the instant rather than relabelling it. Pass an explicit offset when the recording host and the reading host may sit in different zones.
42
+
43
+ 9. **Declarations are reproducible**: artifacts and their locations are ordered by path, not by the order the filesystem happened to report them, so scanning the same tree twice — on two machines, or on two filesystems — yields the same artifact `@id`s and byte-identical output.
44
+
45
+ ## Installation
46
+
47
+ ### Pre-requisites
48
+ Before you begin, you need to have the following installed on your system:
49
+
50
+ - GPG (only needed to `sign` a TRO)
51
+ - OpenSSL
52
+ - Python 3.8+
53
+
54
+ You can do this by running the following commands:
55
+
56
+ ```bash
57
+ $ sudo apt-get install gnupg openssl python3 python3-pip # on Debian/Ubuntu
58
+ $ brew install gnupg openssl python3 # on macOS with Homebrew
59
+ ```
60
+
61
+ If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
62
+ GPG is not required; OpenSSL still is.
63
+
64
+ ## Example Usage
65
+
66
+ Assumes that:
67
+
68
+ * this package is installed
69
+ * your GPG key is present (needed for the `sign` step only)
70
+ * `trs.jsonld` is available and defines TRS capabilities (see below for an example).
71
+ The TRS is a `schema:Organization`, so it is described with schema.org
72
+ properties — `schema:name`, `schema:description`, `schema:url`, `schema:email`,
73
+ `schema:owner` — rather than `trov:` terms, which the TROV vocabulary does not
74
+ define for it.
75
+
76
+ Example workflow:
77
+
78
+ ```bash
79
+ $ cd /tmp
80
+ $ cat trs.jsonld
81
+ {
82
+ "@id": "http://127.0.0.1/",
83
+ "rdfs:comment": "TRS that can monitor netowork accesses or provide Internet isolation",
84
+ "trov:hasCapability": [
85
+ {
86
+ "@id": "trov:CanRecordInternetAccess",
87
+ "@type": "trov:CanRecordInternetAccess"
88
+ },
89
+ {
90
+ "@id": "trov:CanProvideInternetIsolation",
91
+ "@type": "trov:CanProvideInternetIsolation"
92
+ }
93
+ ],
94
+ "schema:owner": {
95
+ "@id": "https://orcid.org/0000-0003-1709-3744",
96
+ "@type": "schema:Person",
97
+ "schema:name": "Kacper Kowalik"
98
+ },
99
+ "schema:description": "My local system",
100
+ "schema:email": "root@dev.null",
101
+ "schema:url": "http://127.0.0.1/",
102
+ "schema:name": "shakuras"
103
+ }
104
+ $ export GPG_FINGERPRINT=...
105
+ $ export GPG_PASSPHRASE=...
106
+ $ git clone https://github.com/transparency-certified/sample-trace-workflow /tmp/sample
107
+ # It's sufficient to pass the profile only once
108
+ $ tro-utils --declaration sample_tro.jsonld --profile trs.jsonld arrangement add /tmp/sample \
109
+ -m "Before executing workflow" -i .git
110
+ Loading profile from trs.jsonld
111
+ $ tro-utils --declaration sample_tro.jsonld arrangement list
112
+ Arrangement(id=arrangement/0): Before executing workflow
113
+ $ pushd /tmp/sample && \
114
+ docker build -t xarthisius/sample . && \
115
+ ./run_locally.sh latest xarthisius && \
116
+ popd
117
+ $ tro-utils --declaration sample_tro.jsonld arrangement add /tmp/sample \
118
+ -m "After executing workflow" -i .git
119
+ $ tro-utils --declaration sample_tro.jsonld arrangement list
120
+ Arrangement(id=arrangement/0): Before executing workflow
121
+ Arrangement(id=arrangement/1): After executing workflow
122
+ $ tro-utils --declaration sample_tro.jsonld performance add \
123
+ -m "My magic workflow" \
124
+ -s 2024-03-01T09:22:01+00:00 \
125
+ -e 2024-03-02T10:00:11+00:00 \
126
+ -a trov:InternetIsolation \
127
+ -a trov:InternetAccessRecording \
128
+ -A arrangement/0 \
129
+ -M arrangement/1
130
+ $ tro-utils --declaration sample_tro.jsonld sign
131
+ $ tro-utils --declaration sample_tro.jsonld verify-timestamp
132
+ ...
133
+ Verification: OK
134
+ $ curl -LO https://raw.githubusercontent.com/craig-willis/trace-report/main/templates/tro.md.jinja2
135
+ $ tro-utils --declaration sample_tro.jsonld report --template tro.md.jinja2 -o report.md
136
+ ```
137
+
138
+ ## Upgrading to 0.5.0
139
+
140
+ Declarations written by 0.4.x still load, but three things changed in what gets
141
+ written, and a fourth in what is accepted:
142
+
143
+ - **A TRS profile's `@id` is now honoured.** 0.4.x discarded it and wrote a bare
144
+ `"trs"`; a profile that already declared a proper IRI silently lost it. If your
145
+ profile states an `@id`, it must now conform (see feature 5 above) — and if it
146
+ states none, the identifier comes from `schema:url`, which for most profiles
147
+ is the same string you would have chosen anyway.
148
+ - **An existing declaration whose TRS `@id` is `"trs"` cannot be saved.** It
149
+ loads fine, so reading, reporting and `verify-timestamp` keep working; writing
150
+ it back needs the identifier corrected first:
151
+
152
+ ```python
153
+ tro = TransparentResearchObject.load("old.jsonld")
154
+ tro.trs.trs_id = "https://example.org/trs"
155
+ tro.save("old.jsonld")
156
+ ```
157
+
158
+ - **`schema:creator` is a node, not a string**, so `tro.creator` is an `Agent`
159
+ with a `.name`, and anything reading the serialised value as text (a report
160
+ template, say) needs `["schema:name"]`.
161
+ - **A capability's `@id` must be an IRI.** 0.4.x profiles conventionally used
162
+ `trs/capability/{i}`, which `trov:warrantedBy` then copied into every
163
+ performance attribute. Drop the `@id` from each `trov:hasCapability` entry
164
+ and the capability's own term is used instead.
165
+ - **Serialised output differs even when nothing else changed**: timestamps gain
166
+ an offset and artifacts are path-ordered. Both change the bytes of a
167
+ re-serialised declaration, which matters because a signature covers those
168
+ bytes — re-saving a signed 0.4.x declaration invalidates its existing
169
+ signature, so sign again afterwards.
170
+
171
+ ## Credits
172
+
173
+ This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.
@@ -30,15 +30,37 @@ the same identifier in every declaration that mentions it:
30
30
  {
31
31
  "@id": "https://wholetale.org/",
32
32
  "schema:name": "Whole Tale",
33
- "trov:hasCapability": []
33
+ "schema:description": "A trusted research system",
34
+ "schema:url": "https://wholetale.org/",
35
+ "schema:email": "admin@wholetale.org",
36
+ "schema:owner": {
37
+ "@id": "https://orcid.org/0000-0002-1825-0097",
38
+ "@type": "schema:Person",
39
+ "schema:name": "Some Operator"
40
+ },
41
+ "trov:hasCapability": [
42
+ { "@type": "trov:CanProvideInternetIsolation" }
43
+ ]
34
44
  }
35
45
  ```
36
46
 
47
+ A capability is identified by the `@id` of its `trov:hasCapability` entry, and
48
+ that is what `trov:warrantedBy` points at from every performance attribute
49
+ claiming it. It must be a compact or absolute IRI; omitting `@id`, as above,
50
+ uses the capability's own term, which is the usual identifier for it. A
51
+ relative id such as `trs/capability/1` is rejected.
52
+
53
+ The TRS is a `schema:Organization`, so schema.org properties describe it.
54
+ `schema:name` and `schema:description` map onto typed fields; every other key,
55
+ schema.org or vendor-specific, is carried through to the declaration verbatim.
56
+
37
57
  A bare relative reference such as `"trs"` does not qualify — it resolves
38
58
  against whichever document happens to contain it — and is rejected rather than
39
- silently replaced. When the profile states no `@id`, its `trov:url` is used if
59
+ silently replaced. When the profile states no `@id`, its `schema:url` is used if
40
60
  it qualifies, and otherwise the TRS is recorded as
41
- `https://w3id.org/trace/tro-utils#unidentified-trs`.
61
+ `https://w3id.org/trace/tro-utils#unidentified-trs`. (`trov:url` is still read
62
+ as a fallback for profiles written before the TRS was described with
63
+ schema.org properties, but it was never a TROV term.)
42
64
 
43
65
  Declarations written before this rule carry `"@id": "trs"`. They still load, but
44
66
  saving one raises until its TRS identifier is corrected:
@@ -81,14 +81,22 @@ def trs_profile(tmp_path_factory):
81
81
  profile_data = {
82
82
  "rdfs:comment": "Test TRS for testing purposes",
83
83
  "trov:hasCapability": [
84
- {"@id": "trs/capability/1", "@type": "trov:CanRecordInternetAccess"},
85
- {"@id": "trs/capability/2", "@type": "trov:CanProvideInternetIsolation"},
84
+ # No @id: a capability is identified by its own term, which is
85
+ # what trov:warrantedBy has to point at.
86
+ {"@type": "trov:CanRecordInternetAccess"},
87
+ {"@type": "trov:CanProvideInternetIsolation"},
86
88
  ],
87
- "trov:owner": "Test User",
88
- "trov:description": "Test TRS",
89
- "trov:contact": "test@example.com",
90
- "trov:url": "http://localhost/",
91
- "trov:name": "test-trs",
89
+ # The TRS is a schema:Organization, so schema.org properties describe
90
+ # it; trov:owner/contact/url/name were never TROV terms.
91
+ "schema:owner": {
92
+ "@id": "https://orcid.org/0000-0002-1825-0097",
93
+ "@type": "schema:Person",
94
+ "schema:name": "Test User",
95
+ },
96
+ "schema:description": "Test TRS",
97
+ "schema:email": "test@example.com",
98
+ "schema:url": "http://localhost/",
99
+ "schema:name": "test-trs",
92
100
  }
93
101
  profile_file.write_text(json.dumps(profile_data, indent=2))
94
102
  return str(profile_file)
@@ -40,8 +40,14 @@ def trs_profile(tmp_path_factory):
40
40
  profile_data = {
41
41
  "rdfs:comment": "Test TRS for CLI testing",
42
42
  "trov:hasCapability": [
43
- {"@id": "trs/capability/1", "@type": "trov:CanRecordInternetAccess"},
44
- {"@id": "trs/capability/2", "@type": "trov:CanProvideInternetIsolation"},
43
+ {
44
+ "@id": "trov:CanRecordInternetAccess",
45
+ "@type": "trov:CanRecordInternetAccess",
46
+ },
47
+ {
48
+ "@id": "trov:CanProvideInternetIsolation",
49
+ "@type": "trov:CanProvideInternetIsolation",
50
+ },
45
51
  ],
46
52
  }
47
53
  profile_file.write_text(json.dumps(profile_data, indent=2))
@@ -826,14 +832,16 @@ class TestCreatorType:
826
832
  runner, tmp_path / "t.jsonld", temp_workspace, trs_profile
827
833
  )
828
834
  assert creator["@type"] == "schema:Organization"
829
- # This fixture profile states neither @id nor trov:url.
835
+ # This fixture profile states neither @id nor a URL.
830
836
  assert creator["@id"] == UNIDENTIFIED_TRS_ID
831
837
 
832
838
  def test_trs_id_from_profile_url(self, runner, tmp_path, temp_workspace):
833
- """A profile's trov:url identifies the TRS when it states no @id."""
839
+ """A profile's schema:url identifies the TRS when it states no @id."""
834
840
  profile = tmp_path / "trs.jsonld"
835
841
  profile.write_text(
836
- json.dumps({"trov:url": "https://wholetale.org/", "trov:hasCapability": []})
842
+ json.dumps(
843
+ {"schema:url": "https://wholetale.org/", "trov:hasCapability": []}
844
+ )
837
845
  )
838
846
  tro_file = tmp_path / "t.jsonld"
839
847
  creator = self._add_arrangement(runner, tro_file, temp_workspace, str(profile))
@@ -843,13 +851,13 @@ class TestCreatorType:
843
851
  assert graph["trov:wasAssembledBy"]["@id"] == "https://wholetale.org/"
844
852
 
845
853
  def test_trs_id_from_profile_id(self, runner, tmp_path, temp_workspace):
846
- """An explicit profile @id wins over trov:url."""
854
+ """An explicit profile @id wins over schema:url."""
847
855
  profile = tmp_path / "trs.jsonld"
848
856
  profile.write_text(
849
857
  json.dumps(
850
858
  {
851
859
  "@id": "ex:trs",
852
- "trov:url": "https://wholetale.org/",
860
+ "schema:url": "https://wholetale.org/",
853
861
  "trov:hasCapability": [],
854
862
  }
855
863
  )
@@ -15,7 +15,9 @@ class TestPerformanceAttribute:
15
15
 
16
16
  def test_to_from_jsonld(self):
17
17
  attr = PerformanceAttribute(
18
- "trp/0/attribute/0", "trov:InternetIsolation", "trs/cap/0"
18
+ "trp/0/attribute/0",
19
+ "trov:InternetIsolation",
20
+ "trov:CanProvideInternetIsolation",
19
21
  )
20
22
  jld = attr.to_jsonld()
21
23
  restored = PerformanceAttribute.from_jsonld(jld)
@@ -42,7 +44,9 @@ class TestTrustedResearchPerformance:
42
44
  ],
43
45
  attributes=[
44
46
  PerformanceAttribute(
45
- "trp/0/attribute/0", "trov:InternetIsolation", "trs/cap/0"
47
+ "trp/0/attribute/0",
48
+ "trov:InternetIsolation",
49
+ "trov:CanProvideInternetIsolation",
46
50
  )
47
51
  ],
48
52
  )
@@ -153,7 +153,10 @@ class TestTransparentResearchObject:
153
153
  trs=TrustedResearchSystem(
154
154
  trs_id="https://example.org/trs",
155
155
  capabilities=[
156
- TRSCapability("trs/cap/0", "trov:CanProvideInternetIsolation")
156
+ TRSCapability(
157
+ "trov:CanProvideInternetIsolation",
158
+ "trov:CanProvideInternetIsolation",
159
+ )
157
160
  ],
158
161
  ),
159
162
  )
@@ -0,0 +1,102 @@
1
+ """Unit tests for TRSCapability and TrustedResearchSystem."""
2
+
3
+ from tro_utils.models import TRSCapability, TrustedResearchSystem
4
+
5
+
6
+ class TestTRSCapability:
7
+ """Unit tests for TRSCapability."""
8
+
9
+ def test_to_from_jsonld(self):
10
+ cap = TRSCapability(
11
+ "trov:CanProvideInternetIsolation", "trov:CanProvideInternetIsolation"
12
+ )
13
+ jld = cap.to_jsonld()
14
+ restored = TRSCapability.from_jsonld(jld)
15
+ assert restored.capability_id == cap.capability_id
16
+ assert restored.capability_type == cap.capability_type
17
+
18
+
19
+ class TestTrustedResearchSystem:
20
+ """Unit tests for TrustedResearchSystem."""
21
+
22
+ def test_from_profile_typed_schema_fields(self):
23
+ """schema:name and schema:description become typed fields."""
24
+ trs = TrustedResearchSystem.from_profile(
25
+ {
26
+ "@id": "https://example.org/trs",
27
+ "schema:name": "My TRS",
28
+ "schema:description": "A system",
29
+ }
30
+ )
31
+ assert trs.name == "My TRS"
32
+ assert trs.description == "A system"
33
+ # Typed, so not duplicated into extra_fields.
34
+ assert "schema:name" not in trs.extra_fields
35
+
36
+ def test_from_profile_preserves_extra_fields(self):
37
+ """Everything not typed is carried through verbatim.
38
+
39
+ That covers the rest of the schema.org description of the
40
+ organization as well as vendor-specific keys.
41
+ """
42
+ profile = {
43
+ "schema:name": "My TRS",
44
+ "schema:url": "https://example.org/trs",
45
+ "schema:email": "admin@example.org",
46
+ "schema:owner": {
47
+ "@type": "schema:Person",
48
+ "schema:name": "Some Operator",
49
+ },
50
+ "trov:hasCapability": [
51
+ {
52
+ "@id": "trov:CanProvideInternetIsolation",
53
+ "@type": "trov:CanProvideInternetIsolation",
54
+ }
55
+ ],
56
+ "trov:publicKey": None,
57
+ "ex:custom": "value",
58
+ }
59
+ trs = TrustedResearchSystem.from_profile(profile)
60
+ assert trs.extra_fields.get("schema:url") == "https://example.org/trs"
61
+ assert trs.extra_fields.get("schema:email") == "admin@example.org"
62
+ assert trs.extra_fields["schema:owner"]["schema:name"] == "Some Operator"
63
+ assert trs.extra_fields.get("ex:custom") == "value"
64
+ assert len(trs.capabilities) == 1
65
+
66
+ def test_to_jsonld_includes_extra_fields(self):
67
+ trs = TrustedResearchSystem(
68
+ trs_id="https://example.org/trs",
69
+ extra_fields={"schema:url": "https://example.org/", "ex:custom": "bar"},
70
+ )
71
+ jld = trs.to_jsonld()
72
+ assert jld["schema:url"] == "https://example.org/"
73
+ assert jld["ex:custom"] == "bar"
74
+
75
+ def test_to_jsonld_describes_an_organization(self):
76
+ """The TRS node is typed as an organization, which is what makes the
77
+ schema.org properties above the right way to describe it."""
78
+ jld = TrustedResearchSystem(
79
+ trs_id="https://example.org/trs", name="My TRS"
80
+ ).to_jsonld()
81
+ assert "schema:Organization" in jld["@type"]
82
+ assert jld["schema:name"] == "My TRS"
83
+
84
+ def test_from_to_jsonld_roundtrip(self):
85
+ trs = TrustedResearchSystem(
86
+ trs_id="https://example.org/trs",
87
+ name="Test TRS",
88
+ description="desc",
89
+ capabilities=[
90
+ TRSCapability(
91
+ "trov:CanProvideInternetIsolation",
92
+ "trov:CanProvideInternetIsolation",
93
+ )
94
+ ],
95
+ extra_fields={"schema:url": "https://example.org/"},
96
+ )
97
+ jld = trs.to_jsonld()
98
+ restored = TrustedResearchSystem.from_jsonld(jld)
99
+ assert restored.trs_id == trs.trs_id
100
+ assert restored.name == trs.name
101
+ assert len(restored.capabilities) == 1
102
+ assert restored.extra_fields.get("schema:url") == "https://example.org/"
@@ -73,7 +73,7 @@ class TestTROCreation:
73
73
 
74
74
  # Check that profile was loaded
75
75
  trs_data = tro.data["@graph"][0]["trov:wasAssembledBy"]
76
- assert trs_data["trov:name"] == "test-trs"
76
+ assert trs_data["schema:name"] == "test-trs"
77
77
  assert len(trs_data["trov:hasCapability"]) == 2
78
78
 
79
79
  def test_tro_filenames(self, tmp_path, gpg_setup):
@@ -0,0 +1,164 @@
1
+ """Tests for TRO report generation."""
2
+
3
+ import datetime
4
+ import os
5
+ import pathlib
6
+
7
+ from tro_utils import TRPAttribute
8
+
9
+ import tro_utils
10
+
11
+ from tests.helpers import create_tro_with_gpg
12
+
13
+ #: The bundled template, resolved off the package as the CLI does rather than
14
+ #: relative to the working directory.
15
+ DEFAULT_TEMPLATE = (
16
+ pathlib.Path(tro_utils.__file__).parent / "default.jinja2"
17
+ ).resolve()
18
+
19
+
20
+ class TestTROReporting:
21
+ """Test TRO report generation."""
22
+
23
+ def test_generate_report(self, temp_workspace, tmp_path, gpg_setup, trs_profile):
24
+ """Test generating a report from a TRO."""
25
+ tro = create_tro_with_gpg(
26
+ filepath=str(tmp_path / "test_tro.jsonld"),
27
+ gpg_setup=gpg_setup,
28
+ profile=trs_profile,
29
+ gpg_fingerprint=gpg_setup["fingerprint"],
30
+ gpg_passphrase=gpg_setup["passphrase"],
31
+ )
32
+
33
+ # Create a workflow
34
+ tro.add_arrangement(str(temp_workspace), comment="Before")
35
+
36
+ (temp_workspace / "output.txt").write_text("processed")
37
+
38
+ tro.add_arrangement(str(temp_workspace), comment="After")
39
+
40
+ tro.add_performance(
41
+ start_time=datetime.datetime(2024, 1, 1, 10, 0, 0),
42
+ end_time=datetime.datetime(2024, 1, 1, 11, 0, 0),
43
+ comment="Test workflow",
44
+ accessed_arrangement="arrangement/0",
45
+ modified_arrangement="arrangement/1",
46
+ attrs=[TRPAttribute.NET_ISOLATION],
47
+ )
48
+
49
+ # Create a simple template
50
+ template_file = tmp_path / "template.jinja2"
51
+ template_file.write_text(
52
+ """
53
+ TRO Report
54
+ ==========
55
+ Name: {{ tro.name }}
56
+ Creator: {{ tro.creator }}
57
+ Description: {{ tro.description }}
58
+
59
+ Arrangements: {{ tro.arrangements | length }}
60
+ Performances: {{ tro.trps | length }}
61
+ """
62
+ )
63
+
64
+ report_file = tmp_path / "report.md"
65
+
66
+ # Generate report
67
+ tro.generate_report(str(template_file), str(report_file))
68
+
69
+ # Verify report was created
70
+ assert os.path.exists(report_file)
71
+
72
+ # Verify report content
73
+ report_content = report_file.read_text()
74
+ assert "TRO Report" in report_content
75
+ assert "Arrangements: 2" in report_content
76
+ assert "Performances: 1" in report_content
77
+
78
+
79
+ class TestTRSPropertiesInReport:
80
+ """The TRACE System table reads the organization's schema.org properties.
81
+
82
+ It previously read `trov:name`, `trov:owner`, `trov:contact` and
83
+ `trov:url` -- terms the TROV vocabulary never defined for a TRS. Jinja
84
+ renders a missing key as the empty string, so the whole table silently
85
+ went blank rather than failing.
86
+ """
87
+
88
+ def _render(self, tmp_path, profile_data):
89
+ import json
90
+
91
+ from tro_utils.tro_utils import TRO
92
+
93
+ workspace = tmp_path / "w"
94
+ workspace.mkdir()
95
+ (workspace / "main.py").write_text("print(1)")
96
+ profile = tmp_path / "trs.jsonld"
97
+ profile.write_text(json.dumps(profile_data))
98
+
99
+ tro = TRO(filepath=str(tmp_path / "t.jsonld"), profile=str(profile))
100
+ tro.add_arrangement(str(workspace), comment="snap")
101
+ tro.save()
102
+ report = tmp_path / "report.md"
103
+ tro.generate_report(str(DEFAULT_TEMPLATE), str(report))
104
+ return report.read_text()
105
+
106
+ def test_schema_properties_are_rendered(self, tmp_path):
107
+ body = self._render(
108
+ tmp_path,
109
+ {
110
+ "@id": "https://example.org/trs",
111
+ "schema:name": "shakuras",
112
+ "schema:description": "My local system",
113
+ "schema:email": "root@dev.null",
114
+ "schema:url": "https://example.org/trs",
115
+ "schema:owner": {
116
+ "@type": "schema:Person",
117
+ "schema:name": "Some Operator",
118
+ },
119
+ "trov:hasCapability": [],
120
+ },
121
+ )
122
+ assert "| Name | shakuras |" in body
123
+ assert "| Description | My local system |" in body
124
+ # schema:owner is a node, so the name has to be reached through it.
125
+ assert "| Owner | Some Operator |" in body
126
+ assert "| Contact | root@dev.null |" in body
127
+ assert "| URL | https://example.org/trs |" in body
128
+
129
+ def test_legacy_trov_properties_still_render(self, tmp_path):
130
+ """Reports over declarations written before the schema.org switch."""
131
+ body = self._render(
132
+ tmp_path,
133
+ {
134
+ "@id": "https://example.org/trs",
135
+ "trov:name": "old-trs",
136
+ "trov:description": "Old style",
137
+ "trov:owner": "Someone",
138
+ "trov:contact": "old@example.org",
139
+ "trov:url": "https://example.org/trs",
140
+ "trov:hasCapability": [],
141
+ },
142
+ )
143
+ assert "| Name | old-trs |" in body
144
+ assert "| Owner | Someone |" in body
145
+ assert "| Contact | old@example.org |" in body
146
+
147
+ def test_no_blank_trs_rows(self, tmp_path):
148
+ """The regression itself: every row must carry a value."""
149
+ body = self._render(
150
+ tmp_path,
151
+ {
152
+ "@id": "https://example.org/trs",
153
+ "schema:name": "shakuras",
154
+ "schema:description": "d",
155
+ "schema:email": "e@example.org",
156
+ "schema:url": "https://example.org/trs",
157
+ "trov:hasCapability": [],
158
+ },
159
+ )
160
+ trace = body.split("## TRACE System Information")[1]
161
+ for label in ("Name", "Description", "Contact", "URL"):
162
+ assert f"| {label}" in trace
163
+ row = next(l for l in trace.splitlines() if l.startswith(f"| {label}"))
164
+ assert row.split("|")[2].strip(), f"{label} rendered blank: {row!r}"