quick-spice-manager 0.2.0__tar.gz → 0.2.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.
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/PKG-INFO +90 -13
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/README.md +87 -11
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/pyproject.toml +5 -1
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/__init__.py +2 -2
- quick_spice_manager-0.2.2/src/quick_spice_manager/cli.py +316 -0
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/ftp.py +1 -1
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/spice_manager.py +548 -155
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/.gitignore +0 -0
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/LICENSE +0 -0
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/dirs.py +0 -0
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/locking.py +0 -0
- {quick_spice_manager-0.2.0 → quick_spice_manager-0.2.2}/src/quick_spice_manager/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: quick-spice-manager
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Project-URL: documentation, https://luca-penasa.github.io/quick-spice-manager
|
|
5
5
|
Project-URL: homepage, https://luca-penasa.github.io/quick-spice-manager
|
|
6
6
|
Project-URL: repository, https://github.com/luca-penasa/quick-spice-manager
|
|
@@ -20,6 +20,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
|
20
20
|
Classifier: Typing :: Typed
|
|
21
21
|
Requires-Python: <4.0,>=3.10
|
|
22
22
|
Requires-Dist: attrs>=24.2.0
|
|
23
|
+
Requires-Dist: click>=8.1
|
|
23
24
|
Requires-Dist: dotenv>=0.9.9
|
|
24
25
|
Requires-Dist: filelock>=3.13.0
|
|
25
26
|
Requires-Dist: importlib-metadata>=8.5.0
|
|
@@ -63,6 +64,48 @@ pip install quick-spice-manager
|
|
|
63
64
|
|
|
64
65
|
> **Note:** The `SpiceManager` name is a deprecated alias for `QuickSpiceManager` and will be removed in a future release. Use `QuickSpiceManager` in new code.
|
|
65
66
|
|
|
67
|
+
### Migrating from 0.1.x
|
|
68
|
+
|
|
69
|
+
| 0.1.x | 0.2.0 |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `SpiceManager` | `QuickSpiceManager` |
|
|
72
|
+
| `sm.tour_config` to get a `TourConfig` | `sm.get_tour_config()` |
|
|
73
|
+
| `sm.tour_config` only to load kernels | `sm.load_kernels()`; pass `exclusive=False` to keep what was loaded before |
|
|
74
|
+
|
|
75
|
+
`tour_config` loads through `planetary_coverage.TourConfig`, which **adds** to
|
|
76
|
+
the SPICE pool. `load_kernels()` defaults to `exclusive=True` and **clears**
|
|
77
|
+
the pool first, so code that loads two metakernels one after the other keeps
|
|
78
|
+
only the last one unless it passes `exclusive=False`.
|
|
79
|
+
|
|
80
|
+
## Command line
|
|
81
|
+
|
|
82
|
+
Installing the package also installs `qsm`:
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
qsm missions # supported missions and aliases
|
|
86
|
+
qsm list -s juice --filter plan # metakernels on the ESA FTP server
|
|
87
|
+
qsm download plan -s juice # download the metakernel and its kernels
|
|
88
|
+
qsm resolve plan -s juice # same, then print a furnshable metakernel path
|
|
89
|
+
qsm info plan -s juice # what's cached, without using the network
|
|
90
|
+
qsm cache list # size and location of each cached mission
|
|
91
|
+
qsm cache clear juice # delete a mission's cached kernels
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`MK` is a shortcut (`plan`), a name (`juice_plan`), or the path to a local `.tm`
|
|
95
|
+
file, and defaults to `plan`. `--spacecraft` defaults to `JUICE`. `download` and
|
|
96
|
+
`resolve` also take `--version` to pin an SKD version, `--kernels-dir`, and
|
|
97
|
+
`--offline` to never use the network.
|
|
98
|
+
|
|
99
|
+
`qsm resolve` prints only the path, and all progress and warnings go to stderr,
|
|
100
|
+
so it can be used in scripts. It writes a copy of the metakernel with
|
|
101
|
+
`PATH_VALUES` pointing at your local kernels, in the mission's cache, or wherever
|
|
102
|
+
`-o FILE` says. It stays there until you clear the cache. Both `download` and
|
|
103
|
+
`resolve` exit with an error if any referenced kernel is missing.
|
|
104
|
+
|
|
105
|
+
Use `-v` or `-vv` before the command for more logging (`qsm -v download plan`).
|
|
106
|
+
The [environment variables](#environment-variable-overrides) apply here too, and
|
|
107
|
+
replace what's given on the command line; `qsm` prints a note when they're set.
|
|
108
|
+
|
|
66
109
|
## Usage
|
|
67
110
|
|
|
68
111
|
### Basic usage
|
|
@@ -157,12 +200,28 @@ sm.add_kernel(["/path/to/a.tls", "/path/to/b.bsp"]) # multiple files
|
|
|
157
200
|
### Saving the current pool state
|
|
158
201
|
|
|
159
202
|
Write the live SPICE pool to a portable metakernel file that can be re-furnished
|
|
160
|
-
later to reproduce the exact same set of loaded kernels:
|
|
203
|
+
later to reproduce the exact same set of loaded kernels, in the same order:
|
|
161
204
|
|
|
162
205
|
```python
|
|
163
206
|
sm.snapshot_pool("/tmp/pool_snapshot.tm")
|
|
164
207
|
```
|
|
165
208
|
|
|
209
|
+
The pool belongs to the process, not to a manager, so the same function is
|
|
210
|
+
available without one, whoever loaded the kernels (a manager, `spiceypy.furnsh`,
|
|
211
|
+
another library):
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
from quick_spice_manager import snapshot_pool
|
|
215
|
+
|
|
216
|
+
snapshot_pool("/tmp/pool_snapshot.tm")
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Kernels under one directory share a single `$KERNELS` path symbol; kernels
|
|
220
|
+
spread over unrelated trees get one symbol per directory. Strings longer than
|
|
221
|
+
SPICE's 80-character limit are split with `+` continuation. When the pool's
|
|
222
|
+
metakernel is known, its `SKD_VERSION` / `MK_IDENTIFIER` are copied into the
|
|
223
|
+
snapshot, and the kernels loaded on top of it are listed in its comments.
|
|
224
|
+
|
|
166
225
|
### Pool management
|
|
167
226
|
|
|
168
227
|
```python
|
|
@@ -173,8 +232,9 @@ sm.clean_pool() # unload extras and re-furnish missing kernels
|
|
|
173
232
|
|
|
174
233
|
### Inspecting the current configuration
|
|
175
234
|
|
|
176
|
-
`sm.config` returns a pandas DataFrame — spacecraft, version, the
|
|
177
|
-
metakernel
|
|
235
|
+
`sm.config` returns a pandas DataFrame — spacecraft, version, the
|
|
236
|
+
metakernel's own `SKD_VERSION` / `MK_IDENTIFIER` (when it declares them), the
|
|
237
|
+
resolved metakernel path, and kernels directory — resolved entirely from this
|
|
178
238
|
manager's own state. Unlike `tour_config` below, it does **not** require the
|
|
179
239
|
`planetary-coverage` extra and doesn't report target/instrument, since those
|
|
180
240
|
belong to `TourConfig`, not this manager:
|
|
@@ -200,6 +260,7 @@ info["version"] # 'v462_20260223_001' (or 'latest')
|
|
|
200
260
|
info["resolved_at"] # ISO-8601 UTC timestamp of when this was resolved --
|
|
201
261
|
# the closest thing to a version string when
|
|
202
262
|
# version='latest' was used
|
|
263
|
+
info["kernels_dir"] # directory the metakernel's kernels were loaded from
|
|
203
264
|
info["extra_kernels"] # kernels added beyond the metakernel, e.g. via add_kernel()
|
|
204
265
|
info["all_kernels"] # every kernel currently loaded, flattened
|
|
205
266
|
```
|
|
@@ -213,6 +274,12 @@ calling `load_kernels()` on this instance):
|
|
|
213
274
|
info = sm.kernel_provenance(source="pool")
|
|
214
275
|
```
|
|
215
276
|
|
|
277
|
+
The pool itself holds a temporary, localized copy of the metakernel;
|
|
278
|
+
`source="pool"` reports the real metakernel it was made from, also after the
|
|
279
|
+
manager that loaded it has been garbage-collected. (The temporary copy is
|
|
280
|
+
kept on disk while it is in the pool, and deleted by `unload_kernels()` or at
|
|
281
|
+
interpreter exit.)
|
|
282
|
+
|
|
216
283
|
### Cache management
|
|
217
284
|
|
|
218
285
|
```python
|
|
@@ -222,17 +289,27 @@ sm.clear_cache() # delete cached kernels (will re-download on next use)
|
|
|
222
289
|
|
|
223
290
|
### Using a local metakernel
|
|
224
291
|
|
|
225
|
-
Pass
|
|
292
|
+
Pass the path to an existing `.tm` file to skip FTP resolution. The kernels
|
|
293
|
+
are the ones the metakernel itself points to: its `PATH_VALUES`, resolved
|
|
294
|
+
relative to the metakernel's own folder. For an ESA kernel dataset (e.g.
|
|
295
|
+
`JUICE.zip`, whose metakernels use `PATH_VALUES = ( '..' )`) that is the
|
|
296
|
+
dataset's `kernels/` folder:
|
|
226
297
|
|
|
227
298
|
```python
|
|
228
|
-
sm = QuickSpiceManager(
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
)
|
|
233
|
-
|
|
299
|
+
sm = QuickSpiceManager(mk="/path/to/JUICE/kernels/mk/juice_crema_5_1_150lb_23_1_a3.tm")
|
|
300
|
+
sm.load_kernels() # loads /path/to/JUICE/kernels/...
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Pass `kernels_dir` (or set `SPICE_DIRECTORY`) to load the kernels from
|
|
304
|
+
another folder instead:
|
|
305
|
+
|
|
306
|
+
```python
|
|
307
|
+
sm = QuickSpiceManager(mk="/path/to/my_local.tm", kernels_dir="/path/to/kernels")
|
|
234
308
|
```
|
|
235
309
|
|
|
310
|
+
A local metakernel that doesn't declare exactly one `PATH_VALUES` entry falls
|
|
311
|
+
back to the download cache directory, as metakernels resolved via FTP do.
|
|
312
|
+
|
|
236
313
|
### planetary-coverage integration
|
|
237
314
|
|
|
238
315
|
`QuickSpiceManager` itself only handles SPICE kernels — it carries no
|
|
@@ -264,7 +341,7 @@ Two environment variables (readable from a `.env` file in the working directory)
|
|
|
264
341
|
| Variable | Effect |
|
|
265
342
|
|---|---|
|
|
266
343
|
| `SPICE_METAKERNEL` | Path to a local metakernel file. Disables automatic FTP download. |
|
|
267
|
-
| `SPICE_DIRECTORY` | Directory containing the kernel files referenced by the metakernel. |
|
|
344
|
+
| `SPICE_DIRECTORY` | Directory containing the kernel files referenced by the metakernel. Takes precedence over `kernels_dir` and over the metakernel's own `PATH_VALUES`. |
|
|
268
345
|
|
|
269
346
|
```sh
|
|
270
347
|
# .env
|
|
@@ -28,6 +28,48 @@ pip install quick-spice-manager
|
|
|
28
28
|
|
|
29
29
|
> **Note:** The `SpiceManager` name is a deprecated alias for `QuickSpiceManager` and will be removed in a future release. Use `QuickSpiceManager` in new code.
|
|
30
30
|
|
|
31
|
+
### Migrating from 0.1.x
|
|
32
|
+
|
|
33
|
+
| 0.1.x | 0.2.0 |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `SpiceManager` | `QuickSpiceManager` |
|
|
36
|
+
| `sm.tour_config` to get a `TourConfig` | `sm.get_tour_config()` |
|
|
37
|
+
| `sm.tour_config` only to load kernels | `sm.load_kernels()`; pass `exclusive=False` to keep what was loaded before |
|
|
38
|
+
|
|
39
|
+
`tour_config` loads through `planetary_coverage.TourConfig`, which **adds** to
|
|
40
|
+
the SPICE pool. `load_kernels()` defaults to `exclusive=True` and **clears**
|
|
41
|
+
the pool first, so code that loads two metakernels one after the other keeps
|
|
42
|
+
only the last one unless it passes `exclusive=False`.
|
|
43
|
+
|
|
44
|
+
## Command line
|
|
45
|
+
|
|
46
|
+
Installing the package also installs `qsm`:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
qsm missions # supported missions and aliases
|
|
50
|
+
qsm list -s juice --filter plan # metakernels on the ESA FTP server
|
|
51
|
+
qsm download plan -s juice # download the metakernel and its kernels
|
|
52
|
+
qsm resolve plan -s juice # same, then print a furnshable metakernel path
|
|
53
|
+
qsm info plan -s juice # what's cached, without using the network
|
|
54
|
+
qsm cache list # size and location of each cached mission
|
|
55
|
+
qsm cache clear juice # delete a mission's cached kernels
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`MK` is a shortcut (`plan`), a name (`juice_plan`), or the path to a local `.tm`
|
|
59
|
+
file, and defaults to `plan`. `--spacecraft` defaults to `JUICE`. `download` and
|
|
60
|
+
`resolve` also take `--version` to pin an SKD version, `--kernels-dir`, and
|
|
61
|
+
`--offline` to never use the network.
|
|
62
|
+
|
|
63
|
+
`qsm resolve` prints only the path, and all progress and warnings go to stderr,
|
|
64
|
+
so it can be used in scripts. It writes a copy of the metakernel with
|
|
65
|
+
`PATH_VALUES` pointing at your local kernels, in the mission's cache, or wherever
|
|
66
|
+
`-o FILE` says. It stays there until you clear the cache. Both `download` and
|
|
67
|
+
`resolve` exit with an error if any referenced kernel is missing.
|
|
68
|
+
|
|
69
|
+
Use `-v` or `-vv` before the command for more logging (`qsm -v download plan`).
|
|
70
|
+
The [environment variables](#environment-variable-overrides) apply here too, and
|
|
71
|
+
replace what's given on the command line; `qsm` prints a note when they're set.
|
|
72
|
+
|
|
31
73
|
## Usage
|
|
32
74
|
|
|
33
75
|
### Basic usage
|
|
@@ -122,12 +164,28 @@ sm.add_kernel(["/path/to/a.tls", "/path/to/b.bsp"]) # multiple files
|
|
|
122
164
|
### Saving the current pool state
|
|
123
165
|
|
|
124
166
|
Write the live SPICE pool to a portable metakernel file that can be re-furnished
|
|
125
|
-
later to reproduce the exact same set of loaded kernels:
|
|
167
|
+
later to reproduce the exact same set of loaded kernels, in the same order:
|
|
126
168
|
|
|
127
169
|
```python
|
|
128
170
|
sm.snapshot_pool("/tmp/pool_snapshot.tm")
|
|
129
171
|
```
|
|
130
172
|
|
|
173
|
+
The pool belongs to the process, not to a manager, so the same function is
|
|
174
|
+
available without one, whoever loaded the kernels (a manager, `spiceypy.furnsh`,
|
|
175
|
+
another library):
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
from quick_spice_manager import snapshot_pool
|
|
179
|
+
|
|
180
|
+
snapshot_pool("/tmp/pool_snapshot.tm")
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Kernels under one directory share a single `$KERNELS` path symbol; kernels
|
|
184
|
+
spread over unrelated trees get one symbol per directory. Strings longer than
|
|
185
|
+
SPICE's 80-character limit are split with `+` continuation. When the pool's
|
|
186
|
+
metakernel is known, its `SKD_VERSION` / `MK_IDENTIFIER` are copied into the
|
|
187
|
+
snapshot, and the kernels loaded on top of it are listed in its comments.
|
|
188
|
+
|
|
131
189
|
### Pool management
|
|
132
190
|
|
|
133
191
|
```python
|
|
@@ -138,8 +196,9 @@ sm.clean_pool() # unload extras and re-furnish missing kernels
|
|
|
138
196
|
|
|
139
197
|
### Inspecting the current configuration
|
|
140
198
|
|
|
141
|
-
`sm.config` returns a pandas DataFrame — spacecraft, version, the
|
|
142
|
-
metakernel
|
|
199
|
+
`sm.config` returns a pandas DataFrame — spacecraft, version, the
|
|
200
|
+
metakernel's own `SKD_VERSION` / `MK_IDENTIFIER` (when it declares them), the
|
|
201
|
+
resolved metakernel path, and kernels directory — resolved entirely from this
|
|
143
202
|
manager's own state. Unlike `tour_config` below, it does **not** require the
|
|
144
203
|
`planetary-coverage` extra and doesn't report target/instrument, since those
|
|
145
204
|
belong to `TourConfig`, not this manager:
|
|
@@ -165,6 +224,7 @@ info["version"] # 'v462_20260223_001' (or 'latest')
|
|
|
165
224
|
info["resolved_at"] # ISO-8601 UTC timestamp of when this was resolved --
|
|
166
225
|
# the closest thing to a version string when
|
|
167
226
|
# version='latest' was used
|
|
227
|
+
info["kernels_dir"] # directory the metakernel's kernels were loaded from
|
|
168
228
|
info["extra_kernels"] # kernels added beyond the metakernel, e.g. via add_kernel()
|
|
169
229
|
info["all_kernels"] # every kernel currently loaded, flattened
|
|
170
230
|
```
|
|
@@ -178,6 +238,12 @@ calling `load_kernels()` on this instance):
|
|
|
178
238
|
info = sm.kernel_provenance(source="pool")
|
|
179
239
|
```
|
|
180
240
|
|
|
241
|
+
The pool itself holds a temporary, localized copy of the metakernel;
|
|
242
|
+
`source="pool"` reports the real metakernel it was made from, also after the
|
|
243
|
+
manager that loaded it has been garbage-collected. (The temporary copy is
|
|
244
|
+
kept on disk while it is in the pool, and deleted by `unload_kernels()` or at
|
|
245
|
+
interpreter exit.)
|
|
246
|
+
|
|
181
247
|
### Cache management
|
|
182
248
|
|
|
183
249
|
```python
|
|
@@ -187,17 +253,27 @@ sm.clear_cache() # delete cached kernels (will re-download on next use)
|
|
|
187
253
|
|
|
188
254
|
### Using a local metakernel
|
|
189
255
|
|
|
190
|
-
Pass
|
|
256
|
+
Pass the path to an existing `.tm` file to skip FTP resolution. The kernels
|
|
257
|
+
are the ones the metakernel itself points to: its `PATH_VALUES`, resolved
|
|
258
|
+
relative to the metakernel's own folder. For an ESA kernel dataset (e.g.
|
|
259
|
+
`JUICE.zip`, whose metakernels use `PATH_VALUES = ( '..' )`) that is the
|
|
260
|
+
dataset's `kernels/` folder:
|
|
191
261
|
|
|
192
262
|
```python
|
|
193
|
-
sm = QuickSpiceManager(
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
)
|
|
198
|
-
|
|
263
|
+
sm = QuickSpiceManager(mk="/path/to/JUICE/kernels/mk/juice_crema_5_1_150lb_23_1_a3.tm")
|
|
264
|
+
sm.load_kernels() # loads /path/to/JUICE/kernels/...
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Pass `kernels_dir` (or set `SPICE_DIRECTORY`) to load the kernels from
|
|
268
|
+
another folder instead:
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
sm = QuickSpiceManager(mk="/path/to/my_local.tm", kernels_dir="/path/to/kernels")
|
|
199
272
|
```
|
|
200
273
|
|
|
274
|
+
A local metakernel that doesn't declare exactly one `PATH_VALUES` entry falls
|
|
275
|
+
back to the download cache directory, as metakernels resolved via FTP do.
|
|
276
|
+
|
|
201
277
|
### planetary-coverage integration
|
|
202
278
|
|
|
203
279
|
`QuickSpiceManager` itself only handles SPICE kernels — it carries no
|
|
@@ -229,7 +305,7 @@ Two environment variables (readable from a `.env` file in the working directory)
|
|
|
229
305
|
| Variable | Effect |
|
|
230
306
|
|---|---|
|
|
231
307
|
| `SPICE_METAKERNEL` | Path to a local metakernel file. Disables automatic FTP download. |
|
|
232
|
-
| `SPICE_DIRECTORY` | Directory containing the kernel files referenced by the metakernel. |
|
|
308
|
+
| `SPICE_DIRECTORY` | Directory containing the kernel files referenced by the metakernel. Takes precedence over `kernels_dir` and over the metakernel's own `PATH_VALUES`. |
|
|
233
309
|
|
|
234
310
|
```sh
|
|
235
311
|
# .env
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "quick-spice-manager"
|
|
3
|
-
version = "0.2.
|
|
3
|
+
version = "0.2.2"
|
|
4
4
|
description = ""
|
|
5
5
|
authors = [{ name = "Luca Penasa", email = "luca.penasa@gmail.com" }]
|
|
6
6
|
requires-python = ">=3.10, <4.0"
|
|
@@ -31,8 +31,12 @@ dependencies = [
|
|
|
31
31
|
"python-dotenv>=1.0.0",
|
|
32
32
|
"dotenv>=0.9.9",
|
|
33
33
|
"tqdm>=4.0",
|
|
34
|
+
"click>=8.1",
|
|
34
35
|
]
|
|
35
36
|
|
|
37
|
+
[project.scripts]
|
|
38
|
+
qsm = "quick_spice_manager.cli:main"
|
|
39
|
+
|
|
36
40
|
[project.optional-dependencies]
|
|
37
41
|
planetary-coverage = ["planetary-coverage>=1.1.1"]
|
|
38
42
|
|
|
@@ -31,9 +31,9 @@ def log_disable(mod: str = "quick_spice_manager") -> None:
|
|
|
31
31
|
log.disable(mod)
|
|
32
32
|
|
|
33
33
|
|
|
34
|
-
from .spice_manager import QuickSpiceManager
|
|
34
|
+
from .spice_manager import QuickSpiceManager, snapshot_pool
|
|
35
35
|
|
|
36
|
-
__all__ = ["QuickSpiceManager", "SpiceManager"]
|
|
36
|
+
__all__ = ["QuickSpiceManager", "SpiceManager", "snapshot_pool"]
|
|
37
37
|
|
|
38
38
|
|
|
39
39
|
def __getattr__(name: str) -> object:
|
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
"""``qsm``: download, cache and resolve ESA SPICE kernels from the shell.
|
|
2
|
+
|
|
3
|
+
Results go to stdout and everything else (progress, warnings, errors) to
|
|
4
|
+
stderr, so ``$(qsm resolve plan)`` is safe to use in scripts.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import functools
|
|
8
|
+
import hashlib
|
|
9
|
+
import json
|
|
10
|
+
import os
|
|
11
|
+
from collections.abc import Callable
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from shutil import copyfile
|
|
14
|
+
from typing import Any, NamedTuple
|
|
15
|
+
|
|
16
|
+
import click
|
|
17
|
+
|
|
18
|
+
from . import log_enable
|
|
19
|
+
from .dirs import get_user_kernels_cache_directory
|
|
20
|
+
from .ftp import (
|
|
21
|
+
_MISSION_ALIASES,
|
|
22
|
+
_MISSION_FTP_BASE,
|
|
23
|
+
_ftp_base,
|
|
24
|
+
list_metakernels_via_ftp,
|
|
25
|
+
)
|
|
26
|
+
from .spice_manager import (
|
|
27
|
+
QuickSpiceManager,
|
|
28
|
+
_lookup_localized,
|
|
29
|
+
_read_mk_keywords,
|
|
30
|
+
sizeof_fmt,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
_MAX_MISSING_SHOWN = 10
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class _Group(click.Group):
|
|
37
|
+
"""Report expected failures as a one-line error instead of a traceback."""
|
|
38
|
+
|
|
39
|
+
def invoke(self, ctx: click.Context) -> Any:
|
|
40
|
+
try:
|
|
41
|
+
return super().invoke(ctx)
|
|
42
|
+
except BrokenPipeError:
|
|
43
|
+
raise # click handles it: `qsm list | head` is not an error
|
|
44
|
+
except (ValueError, OSError) as exc:
|
|
45
|
+
raise click.ClickException(str(exc)) from exc
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class _Resolved(NamedTuple):
|
|
49
|
+
"""A metakernel made usable locally, and what it references."""
|
|
50
|
+
|
|
51
|
+
localized: Path # temp copy, deleted at interpreter exit
|
|
52
|
+
source: Path
|
|
53
|
+
kernels_dir: Path
|
|
54
|
+
kernels: frozenset[str]
|
|
55
|
+
|
|
56
|
+
@property
|
|
57
|
+
def missing(self) -> list[str]:
|
|
58
|
+
return sorted(k for k in self.kernels if not Path(k).exists())
|
|
59
|
+
|
|
60
|
+
@property
|
|
61
|
+
def size(self) -> int:
|
|
62
|
+
paths = (Path(k) for k in self.kernels)
|
|
63
|
+
return sum(p.stat().st_size for p in paths if p.exists())
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _resolve(sm: QuickSpiceManager) -> _Resolved:
|
|
67
|
+
"""Download what's missing (unless offline) and localize the metakernel."""
|
|
68
|
+
localized = sm.resolved_mk
|
|
69
|
+
info = _lookup_localized(localized)
|
|
70
|
+
assert info is not None # noqa: S101 - registered by resolved_mk
|
|
71
|
+
return _Resolved(localized, info.source, info.kernels_dir, info.kernels)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _require_complete(resolved: _Resolved) -> None:
|
|
75
|
+
missing = resolved.missing
|
|
76
|
+
if not missing:
|
|
77
|
+
return
|
|
78
|
+
shown = "\n".join(f" {path}" for path in missing[:_MAX_MISSING_SHOWN])
|
|
79
|
+
more = len(missing) - _MAX_MISSING_SHOWN
|
|
80
|
+
raise click.ClickException(
|
|
81
|
+
f"{len(missing)} of {len(resolved.kernels)} kernels referenced by "
|
|
82
|
+
f"{resolved.source.name} are missing:\n{shown}"
|
|
83
|
+
+ (f"\n ... and {more} more" if more > 0 else ""),
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _new_manager(
|
|
88
|
+
spacecraft: str, mk: str, version: str, kernels_dir: Path | None, *, offline: bool,
|
|
89
|
+
) -> QuickSpiceManager:
|
|
90
|
+
if not Path(mk).is_file():
|
|
91
|
+
_ftp_base(spacecraft) # reject an unknown mission before touching the cache
|
|
92
|
+
sm = QuickSpiceManager(
|
|
93
|
+
spacecraft=spacecraft,
|
|
94
|
+
mk=mk,
|
|
95
|
+
version=version,
|
|
96
|
+
kernels_dir=kernels_dir,
|
|
97
|
+
download_kernels=not offline,
|
|
98
|
+
)
|
|
99
|
+
# The manager's own warnings about these are silent unless -v is given,
|
|
100
|
+
# and they replace what was asked for on the command line.
|
|
101
|
+
for name in ("SPICE_METAKERNEL", "SPICE_DIRECTORY"):
|
|
102
|
+
if name in os.environ:
|
|
103
|
+
click.echo(f"note: using {name}={os.environ[name]}", err=True)
|
|
104
|
+
return sm
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _kernel_options(*, offline_flag: bool = True) -> Callable[..., Any]:
|
|
108
|
+
"""Add the options selecting a metakernel; the command receives ``sm``."""
|
|
109
|
+
|
|
110
|
+
def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
|
|
111
|
+
@functools.wraps(func)
|
|
112
|
+
def wrapper(
|
|
113
|
+
spacecraft: str,
|
|
114
|
+
mk: str,
|
|
115
|
+
version: str,
|
|
116
|
+
kernels_dir: Path | None,
|
|
117
|
+
offline: bool = True, # noqa: FBT001, FBT002 - click passes it by name
|
|
118
|
+
**kwargs: Any,
|
|
119
|
+
) -> Any:
|
|
120
|
+
sm = _new_manager(spacecraft, mk, version, kernels_dir, offline=offline)
|
|
121
|
+
return func(sm=sm, **kwargs)
|
|
122
|
+
|
|
123
|
+
if offline_flag:
|
|
124
|
+
wrapper = click.option(
|
|
125
|
+
"--offline",
|
|
126
|
+
is_flag=True,
|
|
127
|
+
help="Never use the network: only use what is already cached.",
|
|
128
|
+
)(wrapper)
|
|
129
|
+
wrapper = click.option(
|
|
130
|
+
"--kernels-dir",
|
|
131
|
+
# Absolute: it ends up in a metakernel used from other directories.
|
|
132
|
+
type=click.Path(file_okay=False, resolve_path=True, path_type=Path),
|
|
133
|
+
help="Kernels directory, instead of the user cache.",
|
|
134
|
+
)(wrapper)
|
|
135
|
+
wrapper = click.option(
|
|
136
|
+
"--version",
|
|
137
|
+
default="latest",
|
|
138
|
+
show_default=True,
|
|
139
|
+
help="SKD version tag to pin, e.g. v462_20260223_001.",
|
|
140
|
+
)(wrapper)
|
|
141
|
+
wrapper = click.option(
|
|
142
|
+
"-s",
|
|
143
|
+
"--spacecraft",
|
|
144
|
+
default="JUICE",
|
|
145
|
+
show_default=True,
|
|
146
|
+
help="Mission name or alias (see 'qsm missions').",
|
|
147
|
+
)(wrapper)
|
|
148
|
+
return click.argument("mk", default="plan")(wrapper)
|
|
149
|
+
|
|
150
|
+
return decorator
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@click.group(cls=_Group, context_settings={"help_option_names": ["-h", "--help"]})
|
|
154
|
+
@click.version_option(package_name="quick-spice-manager", prog_name="qsm")
|
|
155
|
+
@click.option(
|
|
156
|
+
"-v", "--verbose", count=True, help="Log progress (-v) or debug details (-vv).",
|
|
157
|
+
)
|
|
158
|
+
def cli(verbose: int) -> None:
|
|
159
|
+
"""Download, cache and resolve ESA SPICE kernels.
|
|
160
|
+
|
|
161
|
+
MK is a metakernel shortcut ('plan'), name ('juice_plan') or the path to
|
|
162
|
+
a local .tm file. It defaults to 'plan'.
|
|
163
|
+
"""
|
|
164
|
+
if verbose:
|
|
165
|
+
log_enable("DEBUG" if verbose > 1 else "INFO")
|
|
166
|
+
else:
|
|
167
|
+
# Failed downloads and offline fallbacks are only reported as FTP
|
|
168
|
+
# warnings: never hide that the kernels may not be the latest ones.
|
|
169
|
+
log_enable("WARNING", mod="quick_spice_manager.ftp")
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
@cli.command()
|
|
173
|
+
def missions() -> None:
|
|
174
|
+
"""List the supported missions and their aliases."""
|
|
175
|
+
for mission in sorted(_MISSION_FTP_BASE):
|
|
176
|
+
aliases = sorted(a for a, m in _MISSION_ALIASES.items() if m == mission)
|
|
177
|
+
click.echo(" ".join([mission, *aliases]))
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
@cli.command("list")
|
|
181
|
+
@click.option(
|
|
182
|
+
"-s",
|
|
183
|
+
"--spacecraft",
|
|
184
|
+
default="JUICE",
|
|
185
|
+
show_default=True,
|
|
186
|
+
help="Mission name or alias (see 'qsm missions').",
|
|
187
|
+
)
|
|
188
|
+
@click.option("-f", "--filter", "text", help="Only names containing this text.")
|
|
189
|
+
def list_metakernels(spacecraft: str, text: str | None) -> None:
|
|
190
|
+
"""List the metakernels available on the ESA FTP server."""
|
|
191
|
+
for name in sorted(list_metakernels_via_ftp(spacecraft)):
|
|
192
|
+
if text is None or text.lower() in name.lower():
|
|
193
|
+
click.echo(name)
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@cli.command()
|
|
197
|
+
@_kernel_options()
|
|
198
|
+
def download(sm: QuickSpiceManager) -> None:
|
|
199
|
+
"""Download a metakernel and its kernels into the cache.
|
|
200
|
+
|
|
201
|
+
Files already cached are not downloaded again. Exits with an error if any
|
|
202
|
+
kernel is still missing afterwards.
|
|
203
|
+
"""
|
|
204
|
+
resolved = _resolve(sm)
|
|
205
|
+
_require_complete(resolved)
|
|
206
|
+
click.echo(f"metakernel: {resolved.source}")
|
|
207
|
+
click.echo(f"kernels_dir: {resolved.kernels_dir}")
|
|
208
|
+
click.echo(f"kernels: {len(resolved.kernels)} ({sizeof_fmt(resolved.size)})")
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@cli.command()
|
|
212
|
+
@_kernel_options()
|
|
213
|
+
@click.option(
|
|
214
|
+
"-o",
|
|
215
|
+
"--output",
|
|
216
|
+
type=click.Path(dir_okay=False, path_type=Path),
|
|
217
|
+
help="Where to write the metakernel, instead of the cache.",
|
|
218
|
+
)
|
|
219
|
+
def resolve(sm: QuickSpiceManager, output: Path | None) -> None:
|
|
220
|
+
"""Download what is needed and print the path of a furnshable metakernel.
|
|
221
|
+
|
|
222
|
+
The file is a copy of the metakernel with PATH_VALUES pointing at the
|
|
223
|
+
local kernels, and it stays there until the cache is cleared:
|
|
224
|
+
|
|
225
|
+
python my_script.py "$(qsm resolve plan)"
|
|
226
|
+
"""
|
|
227
|
+
resolved = _resolve(sm)
|
|
228
|
+
_require_complete(resolved)
|
|
229
|
+
if output is None:
|
|
230
|
+
# The original metakernel can't be used here: its PATH_VALUES is
|
|
231
|
+
# relative to the working directory. Neither can resolved.localized:
|
|
232
|
+
# it's deleted when this process exits.
|
|
233
|
+
key = f"{resolved.source}|{resolved.kernels_dir}".encode()
|
|
234
|
+
digest = hashlib.sha256(key).hexdigest()[:8]
|
|
235
|
+
output = (
|
|
236
|
+
sm.user_kernels_cache_directory
|
|
237
|
+
/ "localized"
|
|
238
|
+
/ f"{resolved.source.stem}-{digest}.tm"
|
|
239
|
+
)
|
|
240
|
+
output.parent.mkdir(parents=True, exist_ok=True)
|
|
241
|
+
copyfile(resolved.localized, output)
|
|
242
|
+
click.echo(output.resolve())
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
@cli.command()
|
|
246
|
+
@_kernel_options(offline_flag=False)
|
|
247
|
+
@click.option("--json", "as_json", is_flag=True, help="Print as JSON.")
|
|
248
|
+
def info(sm: QuickSpiceManager, *, as_json: bool) -> None:
|
|
249
|
+
"""Show what is cached for a metakernel, without using the network."""
|
|
250
|
+
try:
|
|
251
|
+
resolved = _resolve(sm)
|
|
252
|
+
except FileNotFoundError as exc:
|
|
253
|
+
message = f"{exc}\nRun 'qsm download' first."
|
|
254
|
+
raise click.ClickException(message) from exc
|
|
255
|
+
skd_version, mk_identifier = _read_mk_keywords(resolved.source)
|
|
256
|
+
fields = {
|
|
257
|
+
"metakernel": str(resolved.source),
|
|
258
|
+
"skd_version": skd_version,
|
|
259
|
+
"mk_identifier": mk_identifier,
|
|
260
|
+
"kernels_dir": str(resolved.kernels_dir),
|
|
261
|
+
"kernels": len(resolved.kernels),
|
|
262
|
+
"missing": len(resolved.missing),
|
|
263
|
+
"size": resolved.size if as_json else sizeof_fmt(resolved.size),
|
|
264
|
+
}
|
|
265
|
+
if as_json:
|
|
266
|
+
click.echo(json.dumps(fields, indent=2))
|
|
267
|
+
return
|
|
268
|
+
for key, value in fields.items():
|
|
269
|
+
click.echo(f"{key + ':':<15}{'-' if value is None else value}")
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
@cli.group()
|
|
273
|
+
def cache() -> None:
|
|
274
|
+
"""Inspect or clear the kernels cache."""
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def _directory_size(directory: Path) -> int:
|
|
278
|
+
return sum(f.stat().st_size for f in directory.glob("**/*") if f.is_file())
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
@cache.command("list")
|
|
282
|
+
def cache_list() -> None:
|
|
283
|
+
"""Show the cached missions, their size and location."""
|
|
284
|
+
root = get_user_kernels_cache_directory()
|
|
285
|
+
dirs = sorted(
|
|
286
|
+
d
|
|
287
|
+
for d in (root.iterdir() if root.is_dir() else ())
|
|
288
|
+
if d.is_dir() and not d.name.startswith(".") # lock directories
|
|
289
|
+
)
|
|
290
|
+
if not dirs:
|
|
291
|
+
click.echo(f"Nothing cached in {root}", err=True)
|
|
292
|
+
for directory in dirs:
|
|
293
|
+
size = sizeof_fmt(_directory_size(directory))
|
|
294
|
+
click.echo(f"{directory.name}\t{size}\t{directory}")
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
@cache.command("clear")
|
|
298
|
+
@click.argument("mission")
|
|
299
|
+
@click.option("-y", "--yes", is_flag=True, help="Do not ask for confirmation.")
|
|
300
|
+
def cache_clear(mission: str, *, yes: bool) -> None:
|
|
301
|
+
"""Delete the cached kernels of MISSION.
|
|
302
|
+
|
|
303
|
+
Don't run this while another process is downloading into the same cache.
|
|
304
|
+
"""
|
|
305
|
+
_ftp_base(mission)
|
|
306
|
+
sm = QuickSpiceManager(spacecraft=mission)
|
|
307
|
+
if not yes:
|
|
308
|
+
click.confirm(
|
|
309
|
+
f"Delete {sm.user_kernels_cache_directory} ({sm.cache_size})?",
|
|
310
|
+
abort=True,
|
|
311
|
+
)
|
|
312
|
+
sm.clear_cache()
|
|
313
|
+
click.echo(f"Cleared {sm.user_kernels_cache_directory}", err=True)
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
main = cli
|