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.
- {tro_utils-0.5.0 → tro_utils-0.5.2}/PKG-INFO +1 -1
- tro_utils-0.5.2/README.md +173 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/usage.md +25 -3
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/conftest.py +15 -7
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_cli.py +15 -7
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_performance.py +6 -2
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_transparent_research_object.py +4 -1
- tro_utils-0.5.2/tests/test_models_trs.py +102 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_creation.py +1 -1
- tro_utils-0.5.2/tests/test_tro_reporting.py +164 -0
- tro_utils-0.5.2/tests/test_trs_identifier.py +388 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/_version.py +3 -3
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/default.jinja2 +16 -10
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/arrangement.py +1 -1
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/artifact.py +1 -1
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/tro.py +26 -3
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/trs.py +121 -16
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/PKG-INFO +1 -1
- tro_utils-0.5.2/tro_utils.egg-info/scm_version.json +8 -0
- tro_utils-0.5.0/README.md +0 -121
- tro_utils-0.5.0/tests/test_models_trs.py +0 -59
- tro_utils-0.5.0/tests/test_tro_reporting.py +0 -67
- tro_utils-0.5.0/tests/test_trs_identifier.py +0 -181
- tro_utils-0.5.0/tro_utils.egg-info/scm_version.json +0 -8
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.coveragerc +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.editorconfig +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/ISSUE_TEMPLATE.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/workflows/release.yml +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.github/workflows/test.yml +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.gitignore +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.readthedocs.yaml +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/.travis.yml +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/LICENSE +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/MANIFEST.in +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/Makefile +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/Makefile +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/authors.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/conf.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/contributing.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/history.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/index.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/installation.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/make.bat +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/readme.md +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/docs/requirements.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/pyproject.toml +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/pytest.ini +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/requirements_dev.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/setup.cfg +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/__init__.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/helpers.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_arrangement_determinism.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_extra_context.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_agent.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_arrangement.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_composition.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_artifact_location.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_composition_fingerprint.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_hash_value.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_research_artifact.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_models_tsa.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_replication_package_model.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_replication_package_verification.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_arrangements.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_hashing.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_performances.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_save_load.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_signing.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_timestamping.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_utility_methods.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_tro_workflow.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tests/test_version.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tox.ini +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/__init__.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/cli.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/__init__.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/_base.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/agent.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/attribute.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/composition.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/hash_value.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/performance.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/models/tsa.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/replication_package.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils/tro_utils.py +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/SOURCES.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/dependency_links.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/entry_points.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/requires.txt +0 -0
- {tro_utils-0.5.0 → tro_utils-0.5.2}/tro_utils.egg-info/scm_file_list.json +0 -0
- {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.
|
|
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
|
+
[](https://pypi.python.org/pypi/tro-utils)
|
|
4
|
+
[](https://zenodo.org/doi/10.5281/zenodo.11130420)
|
|
5
|
+
[](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
|
-
"
|
|
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 `
|
|
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
|
-
|
|
85
|
-
|
|
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
|
-
|
|
88
|
-
|
|
89
|
-
"
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
{
|
|
44
|
-
|
|
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
|
|
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
|
|
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(
|
|
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
|
|
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
|
-
"
|
|
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",
|
|
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",
|
|
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(
|
|
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["
|
|
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}"
|