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.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: quick-spice-manager
3
- Version: 0.2.0
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 resolved
177
- metakernel path, and kernels directory — resolved entirely from this
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 an absolute path to an existing `.tm` file to skip FTP resolution:
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
- spacecraft="JUICE",
230
- mk="/path/to/my_local.tm",
231
- kernels_dir="/path/to/kernels",
232
- )
233
- sm.load_kernels()
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 resolved
142
- metakernel path, and kernels directory — resolved entirely from this
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 an absolute path to an existing `.tm` file to skip FTP resolution:
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
- spacecraft="JUICE",
195
- mk="/path/to/my_local.tm",
196
- kernels_dir="/path/to/kernels",
197
- )
198
- sm.load_kernels()
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.0"
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
@@ -318,7 +318,7 @@ def _resolve_tm_on_ftp(
318
318
  str
319
319
  Full FTP path of the resolved ``.tm`` file.
320
320
  """
321
- mk_clean = mk.removesuffix(".tm")
321
+ mk_clean = mk.lower().removesuffix(".tm") # tm_map's keys are lower-case
322
322
  mk_dir = f"{base}kernels/mk/"
323
323
 
324
324
  try: