jcmsuite 7.4.2__py3-none-any.whl

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.

Potentially problematic release.


This version of jcmsuite might be problematic. Click here for more details.

Files changed (119) hide show
  1. jcmsuite/__init__.py +22 -0
  2. jcmsuite/_build_info.py +4 -0
  3. jcmsuite/context/__init__.py +44 -0
  4. jcmsuite/context/interface_metadata.py +158 -0
  5. jcmsuite/context/models.py +213 -0
  6. jcmsuite/context/scope.py +210 -0
  7. jcmsuite/context/solver_context.py +569 -0
  8. jcmsuite/context/subprocess_tools.py +172 -0
  9. jcmsuite/contract.py +47 -0
  10. jcmsuite/daemon/__init__.py +19 -0
  11. jcmsuite/daemon/handler.py +925 -0
  12. jcmsuite/daemon/internal/__init__.py +4 -0
  13. jcmsuite/daemon/internal/bundle_protocol.py +64 -0
  14. jcmsuite/daemon/internal/handler_helpers.py +368 -0
  15. jcmsuite/daemon/internal/handler_resource_jobs.py +227 -0
  16. jcmsuite/daemon/internal/handler_wait.py +564 -0
  17. jcmsuite/daemon/models.py +349 -0
  18. jcmsuite/daemon/namespaces.py +250 -0
  19. jcmsuite/daemon/protocol.py +801 -0
  20. jcmsuite/daemon/resources.py +407 -0
  21. jcmsuite/daemon/scope.py +53 -0
  22. jcmsuite/daemon/transport.py +223 -0
  23. jcmsuite/editing/__init__.py +10 -0
  24. jcmsuite/editing/editor.py +274 -0
  25. jcmsuite/exceptions/__init__.py +32 -0
  26. jcmsuite/exceptions/errors.py +173 -0
  27. jcmsuite/geo/__init__.py +10 -0
  28. jcmsuite/geo/mesh.py +302 -0
  29. jcmsuite/info/__init__.py +10 -0
  30. jcmsuite/info/runtime_info.py +45 -0
  31. jcmsuite/internal/__init__.py +2 -0
  32. jcmsuite/internal/diagnostics.py +74 -0
  33. jcmsuite/internal/progress.py +80 -0
  34. jcmsuite/loaders/__init__.py +18 -0
  35. jcmsuite/loaders/blob_header.py +315 -0
  36. jcmsuite/loaders/cartesian_field_reader.py +249 -0
  37. jcmsuite/loaders/cartesian_fields.py +324 -0
  38. jcmsuite/loaders/nested_mapping.py +69 -0
  39. jcmsuite/loaders/powerflux.py +136 -0
  40. jcmsuite/loaders/table.py +637 -0
  41. jcmsuite/logging/__init__.py +22 -0
  42. jcmsuite/logging/runtime.py +210 -0
  43. jcmsuite/results/__init__.py +126 -0
  44. jcmsuite/results/artifacts.py +806 -0
  45. jcmsuite/results/discovery.py +82 -0
  46. jcmsuite/results/field_exports.py +1062 -0
  47. jcmsuite/results/field_payloads.py +453 -0
  48. jcmsuite/results/internal/__init__.py +4 -0
  49. jcmsuite/results/internal/export/__init__.py +4 -0
  50. jcmsuite/results/internal/export/common.py +56 -0
  51. jcmsuite/results/internal/export/pandas/__init__.py +4 -0
  52. jcmsuite/results/internal/export/pandas/common.py +165 -0
  53. jcmsuite/results/internal/export/pandas/payload.py +480 -0
  54. jcmsuite/results/internal/export/pandas/rows.py +484 -0
  55. jcmsuite/results/internal/export/preview.py +178 -0
  56. jcmsuite/results/internal/export/xarray/__init__.py +4 -0
  57. jcmsuite/results/internal/export/xarray/export.py +688 -0
  58. jcmsuite/results/internal/export/xarray/grouped.py +608 -0
  59. jcmsuite/results/internal/export/xarray/headers.py +290 -0
  60. jcmsuite/results/internal/export/xarray/runtime.py +99 -0
  61. jcmsuite/results/internal/export/xarray/shared.py +246 -0
  62. jcmsuite/results/internal/export/xarray/tabular.py +304 -0
  63. jcmsuite/results/internal/export/xarray/types.py +28 -0
  64. jcmsuite/results/internal/models/__init__.py +4 -0
  65. jcmsuite/results/internal/models/batch.py +1081 -0
  66. jcmsuite/results/internal/models/batch_postprocess.py +1728 -0
  67. jcmsuite/results/internal/models/bundle.py +343 -0
  68. jcmsuite/results/internal/models/core.py +556 -0
  69. jcmsuite/results/internal/models/submission.py +1157 -0
  70. jcmsuite/results/internal/resultbag/__init__.py +4 -0
  71. jcmsuite/results/internal/resultbag/access.py +489 -0
  72. jcmsuite/results/internal/resultbag/iteration.py +199 -0
  73. jcmsuite/results/internal/resultbag/query.py +226 -0
  74. jcmsuite/results/internal/resultbag/raw.py +407 -0
  75. jcmsuite/results/internal/resultbag/source_files.py +142 -0
  76. jcmsuite/results/internal/resultbag/store.py +881 -0
  77. jcmsuite/results/internal/resultbag/utils.py +258 -0
  78. jcmsuite/results/models.py +76 -0
  79. jcmsuite/results/opening.py +55 -0
  80. jcmsuite/results/pandas_export.py +325 -0
  81. jcmsuite/results/payloads.py +478 -0
  82. jcmsuite/results/postprocess.py +97 -0
  83. jcmsuite/results/postprocess_payloads.py +757 -0
  84. jcmsuite/results/postprocess_record.py +418 -0
  85. jcmsuite/results/resultbag.py +279 -0
  86. jcmsuite/results/resultbag_management.py +433 -0
  87. jcmsuite/results/structured_derivatives.py +387 -0
  88. jcmsuite/solve/__init__.py +10 -0
  89. jcmsuite/solve/daemon_bundle_staging.py +100 -0
  90. jcmsuite/solve/daemon_bundle_wait.py +89 -0
  91. jcmsuite/solve/orchestration.py +1576 -0
  92. jcmsuite/solve/orchestration_execution.py +180 -0
  93. jcmsuite/solve/orchestration_routing.py +128 -0
  94. jcmsuite/solve/orchestration_support.py +323 -0
  95. jcmsuite/solve/path_resolution.py +98 -0
  96. jcmsuite/solve/progress.py +20 -0
  97. jcmsuite/solve/solver.py +709 -0
  98. jcmsuite/solve/staging.py +264 -0
  99. jcmsuite/solve/types.py +25 -0
  100. jcmsuite/solve/working_dirs.py +227 -0
  101. jcmsuite/templates/__init__.py +11 -0
  102. jcmsuite/templates/converter.py +71 -0
  103. jcmsuite/templates/formatting.py +335 -0
  104. jcmsuite/templates/formatting_cli.py +47 -0
  105. jcmsuite/templates/rendering.py +666 -0
  106. jcmsuite/torch/__init__.py +25 -0
  107. jcmsuite/torch/autograd.py +488 -0
  108. jcmsuite/torch/coordinate_policy.py +82 -0
  109. jcmsuite/torch/core.py +312 -0
  110. jcmsuite/torch/results/__init__.py +51 -0
  111. jcmsuite/torch/types.py +84 -0
  112. jcmsuite/torch/validation.py +208 -0
  113. jcmsuite/torch/wrappers.py +4332 -0
  114. jcmsuite/view/__init__.py +10 -0
  115. jcmsuite/view/viewer.py +122 -0
  116. jcmsuite-7.4.2.dist-info/METADATA +180 -0
  117. jcmsuite-7.4.2.dist-info/RECORD +119 -0
  118. jcmsuite-7.4.2.dist-info/WHEEL +4 -0
  119. jcmsuite-7.4.2.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,881 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Persistent Resultbag storage implementation."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import atexit
9
+ import copy
10
+ import hashlib
11
+ import json
12
+ import pickle
13
+ import sqlite3
14
+ import weakref
15
+ from collections.abc import Callable, Mapping, Sequence
16
+ from pathlib import Path
17
+ from typing import cast
18
+
19
+ from ....exceptions import InvalidConfigurationError
20
+ from .access import ResultbagAccessMixin
21
+ from .iteration import ResultbagIterationMixin
22
+ from .source_files import ResultbagSourceFilesMixin
23
+ from .utils import (
24
+ _canonicalize_key_value,
25
+ _safe_close_connection,
26
+ )
27
+
28
+
29
+ class _ResultbagStore(
30
+ ResultbagSourceFilesMixin, ResultbagAccessMixin, ResultbagIterationMixin
31
+ ):
32
+ """Store and query solve results in a persistent Resultbag.
33
+
34
+ .. warning::
35
+ Only open Resultbag files from trusted sources. Loading a stored result
36
+ or log uses Python pickle and can execute code from the file.
37
+
38
+ Parameters
39
+ ----------
40
+ filepath : str | Path
41
+ Resultbag storage path. When the path has no suffix, `.jcmrb` is
42
+ appended automatically.
43
+ keys : Mapping[str, object] | Sequence[str] | None, optional
44
+ project keys or a sequence of project key names that defines the
45
+ stored fields. When you reopen a Resultbag, `None` preserves its
46
+ existing fields. If stored data exists, call
47
+ `resultbag.management.reset()` before you change the fields.
48
+
49
+ Notes
50
+ -----
51
+ Use one Resultbag for one logical project and one set of source files.
52
+ Source-file checks determine whether stored results can be reused.
53
+ """
54
+
55
+ _open_instances: weakref.WeakSet[_ResultbagStore] = weakref.WeakSet()
56
+ _atexit_registered: bool = False
57
+
58
+ def __init__(
59
+ self,
60
+ filepath: str | Path,
61
+ keys: Mapping[str, object] | Sequence[str] | None = None,
62
+ ) -> None:
63
+ """Open or create a Resultbag.
64
+
65
+ .. warning::
66
+ Only open Resultbag files from trusted sources. Loading a stored
67
+ result or log uses Python pickle and can execute code from the file.
68
+
69
+ Parameters
70
+ ----------
71
+ filepath : str | Path
72
+ Resultbag storage path. When the path has no suffix, `.jcmrb` is
73
+ appended automatically.
74
+ keys : Mapping[str, object] | Sequence[str] | None, optional
75
+ project keys or a sequence of project key names that defines the
76
+ stored fields. When you reopen a Resultbag, `None` preserves its
77
+ existing fields. If stored data exists, call
78
+ `resultbag.management.reset()` before you change the fields.
79
+
80
+ Raises
81
+ ------
82
+ InvalidConfigurationError
83
+ If the parent directory of `filepath` does not exist, or if the
84
+ requested project key fields differ while stored data exists.
85
+ """
86
+
87
+ candidate_filepath: Path = Path(filepath).expanduser()
88
+ if candidate_filepath.suffix == "":
89
+ candidate_filepath = candidate_filepath.with_suffix(".jcmrb")
90
+ resolved_filepath: Path = candidate_filepath.resolve()
91
+ if not resolved_filepath.parent.exists():
92
+ raise InvalidConfigurationError(
93
+ f"Resultbag directory does not exist: {resolved_filepath.parent}"
94
+ )
95
+ self._filepath: Path = resolved_filepath
96
+ self._connection: sqlite3.Connection = sqlite3.connect(
97
+ str(self._filepath),
98
+ check_same_thread=False,
99
+ )
100
+ self._connection_finalizer = weakref.finalize(
101
+ self,
102
+ _safe_close_connection,
103
+ self._connection,
104
+ )
105
+ self._closed: bool = False
106
+ self._running_job_keys: dict[int, dict[str, object]] = {}
107
+ self._running_job_suffix_patterns: dict[int, str | None] = {}
108
+ self._ensure_schema()
109
+
110
+ has_stored_fieldnames: bool = self._get_metadata("fieldnames") is not None
111
+ existing_fieldnames: list[str] = self._load_fieldnames()
112
+ normalized_fieldnames: list[str]
113
+ if keys is None:
114
+ normalized_fieldnames = existing_fieldnames
115
+ elif isinstance(keys, Mapping):
116
+ normalized_fieldnames = [str(key) for key in keys.keys()]
117
+ else:
118
+ normalized_fieldnames = [str(key) for key in keys]
119
+
120
+ if has_stored_fieldnames and existing_fieldnames != normalized_fieldnames:
121
+ cursor: sqlite3.Cursor = self._connection.cursor()
122
+ cursor.execute(
123
+ "SELECT EXISTS(SELECT 1 FROM entries) "
124
+ "OR EXISTS(SELECT 1 FROM attempt_logs)"
125
+ )
126
+ stored_data_exists: bool = bool(cursor.fetchone()[0])
127
+ if stored_data_exists:
128
+ self.close()
129
+ raise InvalidConfigurationError(
130
+ "Resultbag cannot change Project Key fields while entries exist. "
131
+ "Call `resultbag.management.reset()` before reopening with "
132
+ "different fields."
133
+ )
134
+ self._store_fieldnames(normalized_fieldnames)
135
+ self._register_instance_for_atexit()
136
+
137
+ def close(self) -> None:
138
+ """Close the Resultbag file.
139
+
140
+ Returns
141
+ -------
142
+ None
143
+ This method has no return value. Repeated calls have no effect.
144
+ """
145
+
146
+ if self._closed:
147
+ return
148
+ self._closed = True
149
+ self._open_instances.discard(self)
150
+ if self._connection_finalizer.alive:
151
+ self._connection_finalizer()
152
+
153
+ def _register_instance_for_atexit(self) -> None:
154
+ """Track open instance and install one-time process-exit cleanup hook."""
155
+
156
+ self._open_instances.add(self)
157
+ if not self._atexit_registered:
158
+ atexit.register(self._close_open_instances_for_exit)
159
+ self._atexit_registered = True
160
+
161
+ @classmethod
162
+ def _close_open_instances_for_exit(cls) -> None:
163
+ """Close any still-open resultbags during process teardown."""
164
+
165
+ open_instances: list[_ResultbagStore] = list(cls._open_instances)
166
+ open_instance: _ResultbagStore
167
+ for open_instance in open_instances:
168
+ open_instance.close()
169
+
170
+ def __enter__(self) -> _ResultbagStore:
171
+ """Return self for context-managed usage.
172
+
173
+ Returns
174
+ -------
175
+ Resultbag
176
+ This resultbag instance.
177
+ """
178
+
179
+ return self
180
+
181
+ def __exit__(
182
+ self,
183
+ exc_type: type[BaseException] | None,
184
+ exc: BaseException | None,
185
+ tb: object | None,
186
+ ) -> None:
187
+ """Close the connection on context-manager exit.
188
+
189
+ Parameters
190
+ ----------
191
+ exc_type : type[BaseException] | None
192
+ Exception type raised in the managed block, if any.
193
+ exc : BaseException | None
194
+ Exception instance raised in the managed block, if any.
195
+ tb : object | None
196
+ Traceback object associated with `exc`, if any.
197
+
198
+ Returns
199
+ -------
200
+ None
201
+ Always closes the connection.
202
+ """
203
+
204
+ del exc_type, exc, tb
205
+ self.close()
206
+
207
+ def _ensure_schema(self) -> None:
208
+ """Create SQLite schema on first use."""
209
+
210
+ cursor: sqlite3.Cursor = self._connection.cursor()
211
+ cursor.execute("""
212
+ CREATE TABLE IF NOT EXISTS metadata (
213
+ key TEXT PRIMARY KEY,
214
+ value TEXT NOT NULL
215
+ )
216
+ """)
217
+ cursor.execute("""
218
+ CREATE TABLE IF NOT EXISTS entries (
219
+ tag TEXT PRIMARY KEY,
220
+ keys_json TEXT NOT NULL,
221
+ result_blob BLOB NOT NULL,
222
+ log_blob BLOB NOT NULL,
223
+ payload_format INTEGER NOT NULL DEFAULT 0
224
+ )
225
+ """)
226
+ cursor.execute("PRAGMA table_info(entries)")
227
+ entry_columns: set[str] = {str(row[1]) for row in cursor.fetchall()}
228
+ if "payload_format" not in entry_columns:
229
+ cursor.execute(
230
+ "ALTER TABLE entries ADD COLUMN payload_format INTEGER NOT NULL DEFAULT 0"
231
+ )
232
+ cursor.execute("""
233
+ CREATE TABLE IF NOT EXISTS attempt_logs (
234
+ tag TEXT NOT NULL,
235
+ keys_json TEXT NOT NULL,
236
+ attempt_index INTEGER NOT NULL,
237
+ payload_blob BLOB NOT NULL,
238
+ PRIMARY KEY (tag, attempt_index)
239
+ )
240
+ """)
241
+ self._connection.commit()
242
+
243
+ def _set_metadata(self, key: str, value: str) -> None:
244
+ """Write one metadata key/value entry to the Resultbag.
245
+
246
+ Parameters
247
+ ----------
248
+ key : str
249
+ Value passed via ``key``.
250
+ value : str
251
+ Value processed by this helper.
252
+
253
+ Returns
254
+ -------
255
+ None
256
+ No value is returned.
257
+
258
+ Notes
259
+ -----
260
+ Internal API: this helper is an implementation detail and may change
261
+ without notice.
262
+ """
263
+
264
+ cursor: sqlite3.Cursor = self._connection.cursor()
265
+ cursor.execute(
266
+ "REPLACE INTO metadata (key, value) VALUES (?, ?)",
267
+ (key, value),
268
+ )
269
+ self._connection.commit()
270
+
271
+ def _get_metadata(self, key: str) -> str | None:
272
+ """Read one metadata value from the Resultbag.
273
+
274
+ Parameters
275
+ ----------
276
+ key : str
277
+ Value passed via ``key``.
278
+
279
+ Returns
280
+ -------
281
+ str | None
282
+ Computed optional string output.
283
+
284
+ Notes
285
+ -----
286
+ Internal API: this helper is an implementation detail and may change
287
+ without notice.
288
+ """
289
+
290
+ cursor: sqlite3.Cursor = self._connection.cursor()
291
+ cursor.execute("SELECT value FROM metadata WHERE key = ?", (key,))
292
+ row: tuple[str] | None = cursor.fetchone()
293
+ if row is None:
294
+ return None
295
+ return row[0]
296
+
297
+ def _store_fieldnames(self, fieldnames: Sequence[str]) -> None:
298
+ """Store fieldnames.
299
+
300
+ Parameters
301
+ ----------
302
+ fieldnames : Sequence[str]
303
+ Value passed via ``fieldnames``.
304
+
305
+ Returns
306
+ -------
307
+ None
308
+ No value is returned.
309
+
310
+ Notes
311
+ -----
312
+ Internal API: this helper is an implementation detail and may change
313
+ without notice.
314
+ """
315
+
316
+ self._set_metadata("fieldnames", json.dumps(list(fieldnames)))
317
+
318
+ def _load_fieldnames(self) -> list[str]:
319
+ """Load fieldnames.
320
+
321
+ Parameters
322
+ ----------
323
+ None
324
+ This helper uses internal state only.
325
+
326
+ Returns
327
+ -------
328
+ list[str]
329
+ Normalized list output.
330
+
331
+ Notes
332
+ -----
333
+ Internal API: this helper is an implementation detail and may change
334
+ without notice.
335
+ """
336
+
337
+ raw_fieldnames: str | None = self._get_metadata("fieldnames")
338
+ if raw_fieldnames is None:
339
+ return []
340
+ loaded: object = cast(object, json.loads(raw_fieldnames))
341
+ if not isinstance(loaded, list):
342
+ return []
343
+ return [str(item) for item in loaded]
344
+
345
+ def _filter_keys(self, keys: Mapping[str, object]) -> dict[str, object]:
346
+ """Filter keys.
347
+
348
+ Parameters
349
+ ----------
350
+ keys : Mapping[str, object]
351
+ Key payload supplied via `keys` for filtering/lookup.
352
+
353
+ Returns
354
+ -------
355
+ dict[str, object]
356
+ Normalized mapping output.
357
+
358
+ Notes
359
+ -----
360
+ Internal API: this helper is an implementation detail and may change
361
+ without notice.
362
+ """
363
+
364
+ fieldnames: list[str] = self._load_fieldnames()
365
+ if not fieldnames:
366
+ return {str(key): value for key, value in keys.items()}
367
+ filtered: dict[str, object] = {}
368
+ field_name: str
369
+ for field_name in fieldnames:
370
+ if field_name in keys:
371
+ filtered[field_name] = keys[field_name]
372
+ return filtered
373
+
374
+ def _keys_to_canonical_json(
375
+ self,
376
+ keys: Mapping[str, object],
377
+ *,
378
+ suffix_pattern: str | None = None,
379
+ ) -> str:
380
+ """Serialize solve keys to canonical JSON for stable resultbag indexing.
381
+
382
+ Parameters
383
+ ----------
384
+ keys : Mapping[str, object]
385
+ Key payload supplied via `keys` for filtering/lookup.
386
+ suffix_pattern : str | None, optional
387
+ Optional suffix pattern that scopes this stored result.
388
+
389
+ Returns
390
+ -------
391
+ str
392
+ Normalized string value.
393
+
394
+ Notes
395
+ -----
396
+ Internal API: this helper is an implementation detail and may change
397
+ without notice.
398
+ """
399
+
400
+ filtered_keys: dict[str, object] = self._filter_keys(keys)
401
+ if suffix_pattern is not None:
402
+ filtered_keys = dict(filtered_keys)
403
+ filtered_keys["__suffix_pattern__"] = suffix_pattern
404
+ canonical_object: object = _canonicalize_key_value(filtered_keys)
405
+ if not isinstance(canonical_object, dict):
406
+ raise InvalidConfigurationError("Resultbag key canonicalization failed.")
407
+ return json.dumps(canonical_object, sort_keys=True, separators=(",", ":"))
408
+
409
+ def _get_tag(
410
+ self,
411
+ keys: Mapping[str, object],
412
+ *,
413
+ suffix_pattern: str | None = None,
414
+ ) -> str:
415
+ """Return stable key tag for a key dictionary.
416
+
417
+ Parameters
418
+ ----------
419
+ keys : Mapping[str, object]
420
+ Key dictionary used for canonical tag derivation.
421
+ suffix_pattern : str | None, optional
422
+ Optional suffix pattern that scopes this stored result.
423
+
424
+ Returns
425
+ -------
426
+ str
427
+ Deterministic MD5 tag over canonicalized key payload.
428
+ """
429
+
430
+ canonical_json: str = self._keys_to_canonical_json(
431
+ keys,
432
+ suffix_pattern=suffix_pattern,
433
+ )
434
+ return hashlib.md5(canonical_json.encode("utf-8")).hexdigest()
435
+
436
+ def _set_job_id(
437
+ self,
438
+ keys: Mapping[str, object],
439
+ id: int,
440
+ *,
441
+ suffix_pattern: str | None,
442
+ ) -> None:
443
+ """Associate a running job ID with a key dictionary.
444
+
445
+ Parameters
446
+ ----------
447
+ keys : Mapping[str, object]
448
+ Key dictionary to associate with the running job.
449
+ id : int
450
+ Running daemon job ID.
451
+
452
+ Returns
453
+ -------
454
+ None
455
+ Stores the association in the in-memory running-job map.
456
+ """
457
+
458
+ self._running_job_keys[id] = copy.deepcopy(self._filter_keys(keys))
459
+ self._running_job_suffix_patterns[id] = suffix_pattern
460
+
461
+ def _release(self, id: int) -> None:
462
+ """Release a running-job association.
463
+
464
+ Parameters
465
+ ----------
466
+ id : int
467
+ Running daemon job ID to remove from tracking.
468
+
469
+ Returns
470
+ -------
471
+ None
472
+ Removes the job association when present.
473
+ """
474
+
475
+ if id in self._running_job_keys:
476
+ del self._running_job_keys[id]
477
+ self._running_job_suffix_patterns.pop(id, None)
478
+
479
+ def _get_keys_by_job_id(self, id: int) -> dict[str, object]:
480
+ """Return key dictionary associated with a running job ID.
481
+
482
+ Parameters
483
+ ----------
484
+ id : int
485
+ Running daemon job ID.
486
+
487
+ Returns
488
+ -------
489
+ dict[str, object]
490
+ Copy of the tracked key dictionary.
491
+
492
+ Raises
493
+ ------
494
+ InvalidConfigurationError
495
+ If the job ID is not tracked by this resultbag.
496
+ """
497
+
498
+ if id not in self._running_job_keys:
499
+ raise InvalidConfigurationError(
500
+ f"Job id {id} is not tracked by this Resultbag."
501
+ )
502
+ return copy.deepcopy(self._running_job_keys[id])
503
+
504
+ def add(
505
+ self,
506
+ *,
507
+ keys: Mapping[str, object],
508
+ result: object,
509
+ log: object | None = None,
510
+ suffix_pattern: str | None = None,
511
+ ) -> None:
512
+ """Store a result and its log for one set of project keys.
513
+
514
+ Parameters
515
+ ----------
516
+ keys : Mapping[str, object]
517
+ project keys that identify the Resultbag entry.
518
+ result : object
519
+ Result to store.
520
+ log : object | None, optional
521
+ Log to store with the result.
522
+ suffix_pattern : str | None, optional
523
+ Suffix pattern that identifies the result. `None` identifies the
524
+ unsuffixed result.
525
+
526
+ Returns
527
+ -------
528
+ None
529
+ This method has no return value. The method adds or replaces the
530
+ Resultbag entry.
531
+
532
+ """
533
+
534
+ from ...models import SolveExecutionLog
535
+ from .raw import _log_to_dict, raw_result_from_solve_result
536
+
537
+ if not isinstance(result, dict):
538
+ from ...models import BundledSolveResult, SolveResult
539
+
540
+ if isinstance(result, (SolveResult, BundledSolveResult)):
541
+ result = raw_result_from_solve_result(result)
542
+ if isinstance(log, (SolveExecutionLog, str)):
543
+ log = _log_to_dict(log)
544
+
545
+ resolved_keys: dict[str, object] = self._filter_keys(keys)
546
+
547
+ canonical_json: str = self._keys_to_canonical_json(
548
+ resolved_keys,
549
+ suffix_pattern=suffix_pattern,
550
+ )
551
+ tag: str = hashlib.md5(canonical_json.encode("utf-8")).hexdigest()
552
+ result_blob: bytes = pickle.dumps(result, protocol=pickle.HIGHEST_PROTOCOL)
553
+ log_blob: bytes = pickle.dumps(log, protocol=pickle.HIGHEST_PROTOCOL)
554
+
555
+ cursor: sqlite3.Cursor = self._connection.cursor()
556
+ cursor.execute(
557
+ """
558
+ REPLACE INTO entries
559
+ (tag, keys_json, result_blob, log_blob, payload_format)
560
+ VALUES (?, ?, ?, ?, ?)
561
+ """,
562
+ (tag, canonical_json, result_blob, log_blob, 1),
563
+ )
564
+ self._connection.commit()
565
+
566
+ def _add_for_job(
567
+ self,
568
+ *,
569
+ id: int,
570
+ result: object,
571
+ log: object | None,
572
+ ) -> None:
573
+ """Store a daemon result using its tracked key dictionary."""
574
+
575
+ self.add(
576
+ keys=self._get_keys_by_job_id(id),
577
+ result=result,
578
+ log=log,
579
+ suffix_pattern=self._running_job_suffix_patterns.get(id),
580
+ )
581
+
582
+ def add_attempt_log(
583
+ self,
584
+ *,
585
+ keys: Mapping[str, object],
586
+ attempt_index: int,
587
+ payload: object,
588
+ suffix_pattern: str | None = None,
589
+ ) -> None:
590
+ """Store the log from one solve attempt.
591
+
592
+ Parameters
593
+ ----------
594
+ keys : Mapping[str, object]
595
+ project keys that identify the Resultbag entry.
596
+ attempt_index : int
597
+ Zero-based attempt index.
598
+ payload : object
599
+ Attempt log to store.
600
+ suffix_pattern : str | None, optional
601
+ Suffix pattern that identifies the result. `None` identifies the
602
+ unsuffixed result.
603
+ """
604
+
605
+ if attempt_index < 0:
606
+ raise InvalidConfigurationError("attempt_index must be >= 0.")
607
+ resolved_keys: dict[str, object] = self._filter_keys(keys)
608
+ canonical_json: str = self._keys_to_canonical_json(
609
+ resolved_keys,
610
+ suffix_pattern=suffix_pattern,
611
+ )
612
+ tag: str = hashlib.md5(canonical_json.encode("utf-8")).hexdigest()
613
+ payload_blob: bytes = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
614
+
615
+ cursor: sqlite3.Cursor = self._connection.cursor()
616
+ cursor.execute(
617
+ """
618
+ REPLACE INTO attempt_logs (tag, keys_json, attempt_index, payload_blob)
619
+ VALUES (?, ?, ?, ?)
620
+ """,
621
+ (tag, canonical_json, attempt_index, payload_blob),
622
+ )
623
+ self._connection.commit()
624
+
625
+ def get_attempt_logs(
626
+ self,
627
+ keys: Mapping[str, object],
628
+ *,
629
+ suffix_pattern: str | None = None,
630
+ ) -> tuple[object, ...]:
631
+ """Return the stored solve-attempt logs for one Resultbag entry.
632
+
633
+ Parameters
634
+ ----------
635
+ keys : Mapping[str, object]
636
+ project keys that identify the Resultbag entry.
637
+ suffix_pattern : str | None, optional
638
+ Suffix pattern that identifies the result. `None` identifies the
639
+ unsuffixed result.
640
+
641
+ Returns
642
+ -------
643
+ tuple[object, ...]
644
+ Attempt logs in order of their `attempt_index` values.
645
+
646
+ Notes
647
+ -----
648
+ Only load attempt logs from a Resultbag file that you trust. This
649
+ method uses Python pickle to load each stored object.
650
+ """
651
+
652
+ resolved_keys: dict[str, object] = self._filter_keys(keys)
653
+ canonical_json: str = self._keys_to_canonical_json(
654
+ resolved_keys,
655
+ suffix_pattern=suffix_pattern,
656
+ )
657
+ tag: str = hashlib.md5(canonical_json.encode("utf-8")).hexdigest()
658
+ cursor: sqlite3.Cursor = self._connection.cursor()
659
+ cursor.execute(
660
+ """
661
+ SELECT payload_blob
662
+ FROM attempt_logs
663
+ WHERE tag = ?
664
+ ORDER BY attempt_index ASC
665
+ """,
666
+ (tag,),
667
+ )
668
+ rows: list[tuple[bytes]] = cursor.fetchall()
669
+ return tuple(cast(object, pickle.loads(row[0])) for row in rows)
670
+
671
+ def clear_attempt_logs(
672
+ self,
673
+ keys: Mapping[str, object],
674
+ *,
675
+ suffix_pattern: str | None = None,
676
+ ) -> None:
677
+ """Remove the solve-attempt logs for one Resultbag entry."""
678
+
679
+ resolved_keys: dict[str, object] = self._filter_keys(keys)
680
+ canonical_json: str = self._keys_to_canonical_json(
681
+ resolved_keys,
682
+ suffix_pattern=suffix_pattern,
683
+ )
684
+ tag: str = hashlib.md5(canonical_json.encode("utf-8")).hexdigest()
685
+ cursor: sqlite3.Cursor = self._connection.cursor()
686
+ cursor.execute("DELETE FROM attempt_logs WHERE tag = ?", (tag,))
687
+ self._connection.commit()
688
+
689
+ def _check_result(
690
+ self,
691
+ keys: Mapping[str, object],
692
+ *,
693
+ suffix_pattern: str | None = None,
694
+ ) -> bool:
695
+ """Return whether a result exists for the given keys.
696
+
697
+ Parameters
698
+ ----------
699
+ keys : Mapping[str, object]
700
+ Key dictionary to check.
701
+ suffix_pattern : str | None, optional
702
+ Optional suffix pattern that scopes this stored result.
703
+
704
+ Returns
705
+ -------
706
+ bool
707
+ `True` when an entry exists for the canonical key tag.
708
+ """
709
+
710
+ tag: str = self._get_tag(keys, suffix_pattern=suffix_pattern)
711
+ cursor: sqlite3.Cursor = self._connection.cursor()
712
+ cursor.execute("SELECT 1 FROM entries WHERE tag = ?", (tag,))
713
+ return cursor.fetchone() is not None
714
+
715
+ def _get_result(
716
+ self,
717
+ keys: Mapping[str, object],
718
+ *,
719
+ suffix_pattern: str | None = None,
720
+ ) -> object:
721
+ """Return the stored result for one set of project keys.
722
+
723
+ Parameters
724
+ ----------
725
+ keys : Mapping[str, object]
726
+ project keys that identify the Resultbag entry.
727
+ suffix_pattern : str | None, optional
728
+ Optional suffix pattern that scopes this stored result.
729
+
730
+ Returns
731
+ -------
732
+ object
733
+ Stored result.
734
+
735
+ Raises
736
+ ------
737
+ InvalidConfigurationError
738
+ If no entry exists for the canonical key tag.
739
+
740
+ Notes
741
+ -----
742
+ Only load results from a Resultbag file that you trust. This method
743
+ uses Python pickle to load the stored object.
744
+ """
745
+
746
+ tag: str = self._get_tag(keys, suffix_pattern=suffix_pattern)
747
+ cursor: sqlite3.Cursor = self._connection.cursor()
748
+ cursor.execute(
749
+ "SELECT result_blob, payload_format FROM entries WHERE tag = ?", (tag,)
750
+ )
751
+ row: tuple[bytes, int] | None = cursor.fetchone()
752
+ if row is None:
753
+ raise InvalidConfigurationError(f"No result found for key tag {tag}.")
754
+ if row[1] != 1:
755
+ raise InvalidConfigurationError(
756
+ "Resultbag entry uses an unsupported legacy result format. "
757
+ "Reset the Resultbag before accessing it."
758
+ )
759
+ return cast(object, pickle.loads(row[0]))
760
+
761
+ def get_log(
762
+ self,
763
+ keys: Mapping[str, object],
764
+ *,
765
+ suffix_pattern: str | None = None,
766
+ ) -> object:
767
+ """Return the stored log for one set of project keys.
768
+
769
+ Parameters
770
+ ----------
771
+ keys : Mapping[str, object]
772
+ project keys that identify the Resultbag entry.
773
+ suffix_pattern : str | None, optional
774
+ Optional suffix pattern that scopes this stored log.
775
+
776
+ Returns
777
+ -------
778
+ object
779
+ Stored log.
780
+
781
+ Raises
782
+ ------
783
+ InvalidConfigurationError
784
+ If no entry exists for the canonical key tag.
785
+
786
+ Notes
787
+ -----
788
+ Only load logs from a Resultbag file that you trust. This method uses
789
+ Python pickle to load the stored object.
790
+ """
791
+
792
+ tag: str = self._get_tag(keys, suffix_pattern=suffix_pattern)
793
+ cursor: sqlite3.Cursor = self._connection.cursor()
794
+ cursor.execute("SELECT log_blob FROM entries WHERE tag = ?", (tag,))
795
+ row: tuple[bytes] | None = cursor.fetchone()
796
+ if row is None:
797
+ raise InvalidConfigurationError(f"No log found for key tag {tag}.")
798
+ return cast(object, pickle.loads(row[0]))
799
+
800
+ def has_results(self) -> bool:
801
+ """Check whether the Resultbag contains a result.
802
+
803
+ Returns
804
+ -------
805
+ bool
806
+ `True` if at least one Resultbag entry exists. Otherwise, `False`.
807
+ """
808
+
809
+ cursor: sqlite3.Cursor = self._connection.cursor()
810
+ cursor.execute("SELECT COUNT(*) FROM entries")
811
+ row: tuple[int] = cursor.fetchone()
812
+ return row[0] > 0
813
+
814
+ def remove_result(
815
+ self,
816
+ keys: Mapping[str, object],
817
+ *,
818
+ suffix_pattern: str | None = None,
819
+ ) -> None:
820
+ """Remove one stored result and its logs.
821
+
822
+ Parameters
823
+ ----------
824
+ keys : Mapping[str, object]
825
+ project keys that identify the Resultbag entry.
826
+ suffix_pattern : str | None, optional
827
+ Optional suffix pattern identifying the entry to remove.
828
+
829
+ Returns
830
+ -------
831
+ None
832
+ This method has no return value. If the entry exists, the method
833
+ removes the entry and its solve-attempt logs.
834
+ """
835
+
836
+ tag: str = self._get_tag(keys, suffix_pattern=suffix_pattern)
837
+ cursor: sqlite3.Cursor = self._connection.cursor()
838
+ cursor.execute("DELETE FROM entries WHERE tag = ?", (tag,))
839
+ cursor.execute("DELETE FROM attempt_logs WHERE tag = ?", (tag,))
840
+ self._connection.commit()
841
+
842
+ def remove(self, predicate: Callable[[dict[str, object]], bool]) -> None:
843
+ """Remove entries for which the filter function returns `True`.
844
+
845
+ Parameters
846
+ ----------
847
+ predicate : Callable[[dict[str, object]], bool]
848
+ Filter function evaluated against project keys.
849
+
850
+ Returns
851
+ -------
852
+ None
853
+ Deletes all matching entries, their suffix variants, and their
854
+ attempt logs.
855
+ """
856
+
857
+ tags_to_remove: list[str] = []
858
+ tag: str
859
+ keys_dict: dict[str, object]
860
+ for tag, keys_dict in self._iter_tags_and_keys():
861
+ if predicate(keys_dict):
862
+ tags_to_remove.append(tag)
863
+ cursor: sqlite3.Cursor = self._connection.cursor()
864
+ for tag in tags_to_remove:
865
+ cursor.execute("DELETE FROM entries WHERE tag = ?", (tag,))
866
+ cursor.execute("DELETE FROM attempt_logs WHERE tag = ?", (tag,))
867
+ self._connection.commit()
868
+
869
+ def reset(self) -> None:
870
+ """Remove all stored results and solve-attempt logs.
871
+
872
+ Returns
873
+ -------
874
+ None
875
+ This method has no return value. Resultbag settings remain stored.
876
+ """
877
+
878
+ cursor: sqlite3.Cursor = self._connection.cursor()
879
+ cursor.execute("DELETE FROM entries")
880
+ cursor.execute("DELETE FROM attempt_logs")
881
+ self._connection.commit()